m204wiki - User contributions [en]

External Call Facility

2026-01-31T21:31:33Z

Gary: /* ECF return codes and $function */

==Overview==

The External Call Facility (ECF) is a method for programs written in [[SOUL]] to invoke external, non-<var class="product">Model 204</var> modules, such as non-IFAM COBOL modules. Data can be passed between <var class="product">Model 204</var> and external modules. External modules can open non-<var class="product">Model 204</var> data sets, read or write to them, and close them. In addition, multiple modules can be called multiple times in a single run. 

ECF is available only under z/OS.

==Working with ECF==

===Loading an external module===

Each external module that is called using ECF is dynamically loaded once into memory from a nominated load library or from //STEPLIB. If <var class="product">Model 204</var> is APF authorized, then any nominated load library identified for use by ECF must also be APF authorized. Otherwise, the <var>External Load</var> statement will fail with:
COMPLETION CODE=S306 REASON CODE=000C.


The load is done by an authorized user executing the <var>[[#load|External Load]]</var> statement; for example, by User 0 during startup. The load is issued from a dedicated ECF subtask that is used exclusively for module loads and deletes.

After an external module is loaded, a call-name of up to 48 characters is associated with it. An association is set up by an authorized user executing the <var>[[#name|External Name]]</var> statement; typically by User 0 during startup. More than one call name can be associated with the same load module name.

Callers of the external module always refer to the call (logical) name rather than the load module (physical) name. Thus, if a load module name or location changes, only the setup statements need to be changed; no application code changes are required.

===Calling an external module===

A previously loaded external module is called by a user executing the <var>[[#call|External Call]]</var> statement. This invokes a separate ECF subtask to run the external module, and causes the user to enter a swappable, bumpable wait state. When the external module completes, control returns to the user. There are no restrictions on the length of time the external module can run.

Data is passed between <var class="product">Model 204</var> and an external module via a <var class="product">Model 204</var> [[Images|image]]. A copy of the image is made when the module is called, so that the caller need not remain in the server while the external module runs. The external module can modify the copy of the image. The modified image is returned to the caller, unless the <var>[[#module|External Module]]</var> statement specified <code>PARMTYPE=INPUT</code>.

===Avoiding data corruption and incorrect results===

External modules must not access any data set that <var class="product">Model 204</var> or any other external module has already opened. 
Attention: Failure to observe this could result in data corruption or abends, either in the external module or Model 204.

External modules invoked using ECF run under separate z/OS subtasks in the same address space as the <var class="product">Model 204</var> Online that invoked the module. This means that external modules run in parallel with <var class="product">Model 204</var> (and each other), even if you do not use MP/204 (multiprocessor).

Most errors that can occur in the external module are isolated from <var class="product">Model 204</var>. However, it is still possible for programming errors in external modules to corrupt or overwrite storage belonging to <var class="product">Model 204</var>. A programming error in your external module could result in data corruption, abends, or incorrect results in the external module or in Model 204.

===Stopping an external load module===

Authorized users can stop an external module in the following ways; by executing:
<ul>
<li><var>[[#stop|External Stop]]</var> statement, usage of a load module can be disabled by an authorized user. It can be enabled again by the <var>[[#start|External Start]]</var> statement.</li>

<li><var>[[#delete|External Delete]]</var> statement, a load module can be removed from storage by an authorized user. An <var>External Delete</var> statement must not be used for Language Environment (LE) modules, because z/OS does not support the use of DELETE of Language Environment main programs and an abend can result.</li>
</ul>

===ECF statistics and messages===

See the table in [[Using system statistics#Statistics with descriptions|Statistics with descriptions]] for the System-final, user-logout, user-since-last, SMF-logout, and SMF-since-last statistics that relate to ECF.

===BUMP command enhanced with the FORCE option for ECF users===

Simply bumping a user that is executing an <var>External Call</var> statement does not interrupt the external module. The external module is allowed to complete — however long that takes —and then the bump takes effect.

To interrupt an external module, you must issue a <var>[[BUMP command|BUMP]]</var> command with the <var>FORCE</var> option. Or, you can continue to use the <var>External Stop</var> statement with the <var>FORCE</var> option.

If the <var>FORCE</var> option is specified on a <var>BUMP</var> command, then the users who are running an external module are interrupted. The <var>FORCE</var> option may be combined with any other <var>BUMP</var> options. When you specify the <var>FORCE</var> option, it must be the first option on the command.

====Examples====
BUMP FORCE ALL

BUMP FORCE SUBSYS MYAPSY

BUMP FORCE MODULE MYPGM

For users who are not running an external module, the presence or absence of the <var>FORCE</var> option is irrelevant. Adding the <var>FORCE</var> option affects only users who are running an external module. The <var>FORCE</var> option does not interrupt users that are in an unbumpable wait.

==ECF SOUL statements==

You must check <var>[[$Status]]</var> and <var>[[$StatusD]]</var> return codes after each ECF statement.

===External Call statement===
<dl>
<dt>Function</dt>
<dd>Calls an external module that was previously loaded using an <var>External Load</var> statement, using a call name that was previously specified in an <var>External Name</var> statement.</dd>
<dt>Privileges</dt>
<dd>
Any user</dd>
<dt>Syntax</dt>
<dd>External Call call-name [WITH image-1 [,image-2,...image-60]] 

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>call-name</th>
<td>Logical name, either a literal or %variable, of the external module to invoke.</td>
</tr>

<tr>
<th><var>WITH clause</var></th>
<td>The optional <var>WITH</var> clause specifies the images to pass as a parameter area between the SOUL program and the external module. If no parameter area is required, you can omit the <var>WITH</var> clause.</td>
</tr>

<tr>
<th nowrap>image-1,...image-60</th>
<td>Name(s) of a previously defined image(s) to pass to the external module.</td>
</tr>
</table>
</dd>
<dt>Usage</dt>
<dd>
<ul>
<li>You can specify from one to sixty images separated by commas.</li>

<li>A return code of zero does not mean that the external module performed as it was designed; it simply means that the module was successfully invoked and completed without an abend. </li>

<li>Without a parameter area, the external module cannot directly pass any data back to a SOUL program other than via its return code. It can, of course, indirectly pass data back: for example, by updating a sequential data set that the SOUL program can then inspect.</li>

<li>If Model 204 is using an external authorizer such as ACF2, RACF, or Top/Secret: The default external-authorizer profile under which a job invoked by a privileged ECF statement runs is changed in version 7.7 of Model 204. Instead of such a job running under the job's external-authorizer profile (as it did prior to 7.7), the job runs by default in 7.7 under the user's external-authorizer profile.

The default behavior can be changed by turning on the system parameter <var>[[ECPRIV parameter|ECPRIV]]</var> 4 bit. </li>
</ul></dd>
</dl>

===External Delete statement===
<dl>
<dt>Function</dt>
<dd>Removes a previously loaded external module from storage.</dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Delete module-name


Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>A literal or a %variable that is the module name of a previously loaded external module.</td></tr>
</table></dd>
<dt>Usage</dt>
<dd>Do not use the <var>External Delete</var> statement for Language Environment modules.</dd>
</dl>

===External Load statement===
<dl>
<dt>Function</dt>
<dd>Loads an external module into storage. The module, previously defined by an <var>External Module</var> statement, is loaded and is then available to all users.</dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Load module-name


Where:
<table>
<tr class="head">
<th>Argument </th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>A literal or a %variable that is the name of the external module, a PDS member name.</td>
</tr>
</table></dd>
</dl>

===External Module statement===
<dl>
<dt>Function</dt>
<dd>Defines an external module for later loading. </dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Module module-name [DDNAME=ddname]
[PARMTYPE=INPUT | OUTPUT]
[PARMSIZE=value]
[PARMMODE=[24 | 31]]
[REENTRANT | AFFINITY]
[IDCAMS]

Where:
<table>
<tr class="head">
<th>Argument </th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name </th>
<td>A literal or %variable that is the name of the external module, a PDS member name. Required.</td></tr>

<tr>
<th>ddname </th>
<td>A literal or %variable that is the DDNAME of the PDS where the load module is located. If omitted, the standard search order or //STEPLIB is used. Optional.

Note: If <var class="product">Model 204</var> is APF authorized, then this data set must also be APF authorized.
</td></tr>

<tr>
<th><var>PARMTYPE</var> </th>
<td>The parameter (image) type passed to the external module on an <var>External Call</var> statement. Optional.
<ul>
<li><var>INPUT</var> means that any changes made by the external module to the parameter are discarded. </li>

<li><var>OUTPUT</var>, the default, means that any changes are retained.</li>
</ul>
</td></tr>

<tr>
<th><var>PARMSIZE</var> </th>
<td>A literal or %variable that is the required size of the parameter (image) passed to the external module on all <var>External Call</var> statements.

If the actual parameter size does not match the required size, the <var>External Call</var> statement fails. 

If <var>PARMSIZE</var> is not specified, the parameter size is not checked. 
</td></tr>

<tr>
<th><var>PARMMODE</var></th>
<td>Where storage to hold the copy of the parameter area is allocated. Optional.
<ul>
<li>24 means allocate in 24-bit, below-the-line storage.</li>

<li>31, the default, means allocate in 31-bit, above the line storage.</li>

<li>Do not specify <code>PARMMODE=24</code> unless the module has a specific requirement for this setting.</li>
</ul></td></tr>

<tr>
<th><var>REENTRANT</var> </th>
<td>Module that can be used by more than one user at a time. This optional argument takes effect only if the module was link-edited with the REENTRANT attribute.</td>
</tr>

<tr>
<th><var>AFFINITY</var> </th>
<td>Module always runs on the same subtask. Conversely, that subtask runs only that module.</td>
</tr>

<tr>
<th><var>IDCAMS</var> </th>
<td>The module is the [https://en.wikipedia.org/wiki/IBM_mainframe_utility_programs#IDCAMS IBM IDCAMS utility]. Specifying this option causes the IDCAMS module to be invoked in such a way that, rather than reading data from the <var>SYSIN</var> DD and sending output to the <var>SYSPRINT</var> DD, data is read from and written to the user buffer (sometimes known as the Universal Buffer).

The <var>IDCAMS</var> option is available as of Model 204 7.7. For an example, see [[#IDCAMS example|IDCAMS example]], below.

Specifying this option for a module other than IDCAMS is likely to result in abends in the module when called.
</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>
<ul>
<li>You can use an <var>External Module</var> statement to define a module using either:
<ul>
<li>New name and attributes.</li>

<li>Existing name. Attributes associated with an existing name are replaced by new attributes.</li>
</ul></li>

<li>Subtask affinity, which is specified by the <var>AFFINITY</var> keyword, is required in some situations. For example, when an external module opens a data set on one call, but does not close it till a subsequent call. Subtask affinity is required because z/OS requires that you open and close a data set from the same subtask. </li>

<li>The <var>AFFINITY</var> keyword is incompatible with the <var>REENTRANT</var> keyword. A compilation error is generated, if both are specified for the same module. You specify one or the other or neither, but not both.</li>
</ul></dd>
</dl>

===External Name statement===
<dl>
<dt>Function</dt>
<dd>Use the <var>External Name</var> statement to:
<ul>
<li>Associate a logical call name with the name of a module that was previously defined by issuing an <var>External Module</var> statement</li>

<li>Remove a previously set up association. A module can have multiple call names.</li>
</ul></dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Name call-name FOR module-name

External Name call-name REMOVE

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>call-name</th>
<td>Logical name to associate with an external module. Up to 48 characters.</td>
</tr>

<tr>
<th>module-name</th>
<td>Name of a previously loaded external module.</td>
</tr>
</table></dd>
</dl>

===External Start statement===
<dl>
<dt>Function</dt>
<dd>Enables further calls to an ECF module.</dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>

<dt>Syntax</dt>
<dd>
External Start module-name

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name </th>
<td>Name of a previously loaded external module.</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>Initially a module is in the START state. You need not issue an <var>External Start</var> statement unless you want to reverse a prior <var>External Stop</var> statement.
</dd>
</dl>

===External Stop statement===
<dl>
<dt>Function</dt>
<dd>Stops further calls to an ECF module. Currently executing calls either complete or, if the FORCE option is used, abend.</dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>

<dt>Syntax</dt>
<dd>External Stop module-name [FORCE]

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>Name of a previously loaded external module.</td>
</tr>

<tr>
<th><var>FORCE</var></th>
<td>Users currently executing the specified module are bumped.</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>The following table describes how an <var>External Stop</var> statement is evaluated.
<table>
<tr class="head">
<th>When <var>External Stop</var> statement is issued </th>
<th>
Then</th>
</tr>

<tr>
<td>If no users are executing the module </td>
<td>Module is immediately marked stopped. </td>
</tr>

<tr>
<td>If one or more users are executing the module </td>
<td>Module is marked draining until the last user finishes executing the module, then it is marked stopped. </td>
</tr>

<tr>
<td>If <var>FORCE</var> was specified </td>
<td>Current users of the module are bumped.</td>
</tr>

<tr>
<td>If <var>FORCE</var> was not specified </td>
<td>Current users of the module are allowed to complete. </td>
</tr>
</table>

In all cases, subsequent attempts by any user to call the module with an <var>External Call</var> statement result in a <var>$Status</var> of 8. 
Note: Rocket Software does not recommend using the <var>FORCE</var> option, as <var class="product">Model 204</var> cannot ensure that the external module is terminated cleanly.</dd>
</dl>

==ECF return codes and $function==

All <var>EXTERNAL</var> statements set <var>$Status</var> and <var>$StatusD</var>.
<table>
<caption>ECF return codes</caption>
<tr class="head">
<th>$Status</th>
<th>$StatusD</th>
<th>Meaning</th>
</tr>

<tr>
<td align="right">0</td>
<td align="right">0</td>
<td>ECF function completed without error</td>
</tr>

<tr>
<td align="right">1</td>
<td align="right">0</td>
<td>ECF inactive</td>
</tr>

<tr>
<td align="right">2</td>
<td align="right">1</td>
<td>User not authorized for ECF function, refer to ECPRIV parameter</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>Unable to obtain ACEE for setting ECF subtask security profile</td>
</tr>

<tr>
<td align="right">3</td>
<td align="right">1</td>
<td>Invalid module name</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>Invalid call name</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>Invalid DDNAME</td>
</tr>

<tr>
<td> </td>
<td align="right">4</td>
<td>Image inactive</td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>Invalid PARMSIZE</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">0</td>
<td>Call name not defined</td>
</tr>

<tr>
<td align="right">6</td>
<td align="right">0</td>
<td>Module not defined</td>
</tr>

<tr>
<td align="right">7</td>
<td align="right">0</td>
<td>Module not loaded</td>
</tr>

<tr>
<td align="right">8</td>
<td align="right">0</td>
<td>Module unavailable (draining or stopped)</td>
</tr>

<tr>
<td align="right">10</td>
<td align="right">0</td>
<td>Module not deleted</td>
</tr>

<tr>
<td align="right">20</td>
<td> </td>
<td>System busy; timed out</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>Module unavailable</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>No subtask available</td>
</tr>

<tr>
<td align="right">30</td>
<td> </td>
<td>Load or delete failed</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>DDNAME not present</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>DDNAME open failed</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>DDNAME close failed</td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>Load or delete failed; see the <var>[[$EcfStat]]</var> function.
</td>
</tr>

<tr>
<td> </td>
<td align="right">6</td>
<td>Internal ECF abend; see the <var>$EcfStat</var> function page.</td>
</tr>

<tr>
<td> </td>
<td align="right">7</td>
<td>Internal ECF ABEND; load or delete subtask terminated by the operating system.</td>
</tr>

<tr>
<td align="right">40</td>
<td align="right">0</td>
<td>Module failed</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>Module gave nonzero return code; see the <var>$EcfStat</var> function page.
</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>Module abend; see the <var>$EcfStat</var> function page.
</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>Insufficient memory available to allocate a buffer for the parameter area</td>
</tr>

<tr>
<td> </td>
<td align="right">4</td>
<td>Actual parameter size is not equal to <var>PARMSIZE</var></td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>When the parameter area, as updated by the external module, was being copied back to the original image(s), ECF detected that the size of one of the images had been changed. This status can occur only if an image contains a variable array whose size is changed by the external module.</td>
</tr>

<tr>
<td> </td>
<td align="right">6</td>
<td>ECF subtask terminated by the operating system</td>
</tr>

<tr>
<td align="right">50</td>
<td align="right">0</td>
<td>ECF internal table full</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>ECF ECMODS table full; increase <var>ECMODS</var> User 0 parameter</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>ECF ECNAMES table full; increase <var>ECNAMES</var> User 0 parameter</td>
</tr>
</table>

===$EcfStat function===

The <var>[[$EcfStat]]</var> function returns the detailed completion code from the previous <var>EXTERNAL</var> statement.


==ECF User 0 parameters==

The following User 0 parameters are used by ECF.

A system manager can reset only the <var>ECWAIT</var> parameter; the other ECF parameters cannot be reset.
<table>
<tr class="head">
<th>User 0 parameter </th>
<th>Returns...</th>
</tr>

<tr>
<td><var>[[ECISUBS parameter|ECISUBS]]</var> </td>
<td>Subtasks for running external modules initially attached</td>
</tr>

<tr>
<td><var>[[ECMODS parameter|ECMODS]]</var> </td>
<td>External modules to load</td>
</tr>

<tr>
<td><var>[[ECMSUBS parameter|ECMSUBS]]</var> </td>
<td>Number of ECF subtasks for running modules</td>
</tr>

<tr>
<td><var>[[ECNAMES parameter|ECNAMES]]</var> </td>
<td>Number of external call names</td>
</tr>

<tr>
<td><var>[[ECPRIV parameter|ECPRIV]]</var> </td>
<td>ECF privileges</td>
</tr>

<tr>
<td><var>[[ECPSIZE parameter|ECPSIZE]]</var> </td>
<td>Size of largest image used by ECF</td>
</tr>

<tr>
<td><var>[[ECWAIT parameter|ECWAIT]]</var> </td>
<td>ECF wait time</td>
</tr>

<tr>
<td><var>[[ECWAIT parameter|ECMAXCPU]]</var> </td>
<td>Maximum CPU time in seconds allowed for an external call of an ECF module, else 0 for no limit. If limit is exceeded, the ECF module a user 099 ABEND is reflected to the ECF task. This support added by 79Z087.</td>
</tr>
</table>

==Subtask and load module management==

Some z/OS overhead accrues in loading an external module into storage and attaching a z/OS subtask under which it runs. ECF avoids incurring this cost for every <var>External Call</var> statement by managing the load modules and subtasks as described in the following sections.

===Subtasks assignment===

At system startup, the following subtasks are started:
<ul>
<li>One subtask for loading and deleting modules</li>

<li>One or more subtasks, specified by the <var>ECISUBS</var> parameter, for executing external modules</li>
</ul>

When a user issues an <var>External Call</var> statement, an unused ECF subtask is selected on which to run the external module, up to the limit of <var>ECMSUBS</var>. Users unable to get a subtask enter a wait of up to <var>ECWAIT</var> milliseconds for a subtask to become available. When an in-use ECF subtask becomes available, because the module that was running under it ends, it is assigned to a user waiting for a subtask. If a user's wait time expires before a subtask is available, a no-subtask-available failure is returned.

===Subtask affinity===

Normally, when an external module is called via the <var>External Call</var> statement, ECF selects any free subtask on which to execute the module. Although this is appropriate for most external modules, some modules might need to always be executed on the same subtask. This is known as subtask affinity. Subtask affinity for a module is specified by the <var>AFFINITY</var> option on the <var>External Module</var> statement. The <var>AFFINITY</var> option is incompatible with the <var>REENTRANT</var> option.
<ul>
<li>If the <var>AFFINITY</var> option is not specified, the module does not have subtask affinity. This is the default. </li>

<li>If the <var>AFFINITY</var> option is specified, the module has subtask affinity. </li>
</ul>

When the first <var>External Call</var> of the module is executed, a dedicated subtask for the module is attached. A two-way association between the module and the subtask is established. That module will run on only that subtask, not on any other subtask. That subtask is used to run only that module, not any other module.

If a module has subtask affinity, and the dedicated subtask for that module is abnormally terminated for any reason, the previous dedicated subtask is detached, and a new dedicated subtask for the module is attached. A subtask could be abnormally terminated if the module it was running has an abend, or the user running the module is bumped. Therefore, specifying <var>AFFINITY</var> does not guarantee that the same subtask is always used for that module for the duration of a <var class="product">Model 204</var> Online.

If you use modules with subtask affinity, ensure that <var>ECISUBS</var> and <var>ECMSUBS</var> are appropriately set. In particular, <var>ECISUBS</var> and <var>ECMSUBS</var> must be greater than or equal to the number of modules with subtask affinity.
<ul>
<li>The <var>ECISUBS</var> parameter specifies the number of subtasks attached during system initialization. These subtasks are never used for modules with subtask affinity; the first <var>External Call</var> of a module with subtask affinity always results in a new subtask being attached (subject to <var>ECMSUBS</var>). </li>

<li>The <var>ECMSUBS</var> parameter specifies the maximum number of ECF subtasks used to run modules. The number of subtasks used for modules with subtask affinity plus the number of subtasks used for modules without subtask affinity will be a maximum of <var>ECMSUBS</var>.</li>
</ul>

===Load modules===

An external module is usually loaded into storage just once. The exception is when an <var>External Load</var> statement, possibly preceded by an <var>External Delete</var> statement, is used to reload a previously-loaded module.

Normally, one <var class="product">Model 204</var> user at a time is allowed to issue an <var>External Call</var> statement for the module. Other users who attempt to call the module while it is in use, enter a wait-state of up to <var>ECWAIT</var> milliseconds for the module to become available. When a module is freed, because the current execution of it ends, it is assigned to one of the users waiting for it. If a user's wait time expires before the module is assigned, a module-in-use failure is returned. 

If a load module was link-edited with the REENTRANT (also written, RENT) attribute, and if the <var>External Module</var> statement that defined the module characteristics specified the <var>REENTRANT</var> option, then multiple <var class="product">Model 204</var> users are allowed to simultaneously issue an <var>External Call</var> statement for the module — subject to subtask availability.

===Fulfillment order===

An <var>External Call</var> statement can invoke an external module only if both an ECF subtask is free, and for a serially reusable module, if the module is not in use by another user. The check that the module is not in use by another user is done before the allocation of a subtask so that the most restrictive condition is checked first.

==Restrictions and cautions==

The following restrictions and cautions apply to the use of ECF:
<ul>
<li>ECF loads an external module only once, when the <var>External Load</var> statement is issued. Thereafter, every user who issues an <var>External Call</var> statement for that module uses the same copy of the module. Therefore, you must write your module to initialize itself properly on every call.</li>

<li>ECF passes the copy of the parameter area to the external module using standard z/OS linkage conventions. Your external module must support these conventions to receive the parameters.</li>

<li>ECF does not provide any special initialization of the environment when you issue an <var>External Call</var> statement; it merely branches to the in-memory copy of the module. Therefore, your module must perform any required initialization and termination of its run-time environment. In particular, this means that an external module, written in any language, should be written as a main routine and not a subroutine.</li>

<li>Only one copy of a load module can be in memory at a time. This is a z/OS restriction.</li>

<li>Externally called modules must be <code>AMODE(31)</code> and either <code>RMODE(ANY)</code> or <code>RMODE(31)</code>.</li>

<li>Externally called modules must not attempt to retain any context information from one call to another. You must write the modules so that each call executes independently of any other.
</li>

<li>For efficiency purposes, ECF does not use z/OS to maintain the usage counts or status information for load modules. Control is passed by direct branch rather than use of the z/OS ATTACH, LINK, or XCTL macros. Therefore, one external module must not attempt to load or attach another external module, or attempt to reference code or data in another external module.</li>

<li>The definition of the parameter area in <var class="product">Model 204</var> — the image definition — must agree with the definition of the parameter area in the external module (in a COBOL program, the LINKAGE SECTION). If they do not agree, it is possible for the module to modify the wrong storage.

To prevent this, <var class="product">Model 204</var> checks that the external module put its results in only the assigned area — not somewhere else. <var class="product">Model 204</var> checks the area immediately past the end of the assigned area. If the unassigned area was used, <var class="product">Model 204</var> displays the following message and restarts the user:
M204.2563: MODULE=name RETURNED MORE THAN length BYTES
</li>
</ul>

==Tracking ECF==

===Wait types for ECF===

See the table of codes in the [[ONLINE_monitoring#Wait_type_values| listing of wait types]] that includes the External Call Facility, wait types 43 through 46.

===ECF statistics===

The following statistics help you track the External Call Facility. See [[Using system statistics#Statistics with descriptions|Statistics with descriptions]] for the position in the system-final, user-logout, user-since-last, SMF-logout, and/or SMF-since-last journal record layout as they apply. 
<ul>
<li>ECCALL</li>

<li>ECCNCT</li>

<li>ECCTOUT</li>

<li>ECCWAITM</li>

<li>ECCWAITS</li>

<li>ECDELETE</li>

<li>ECLOAD</li>

<li>ECMODMAX</li>

<li>ECNAMMAX</li>

<li>ECTSKMAX</li>

<li>ECTWAITM</li>

<li>ECTWAITS</li>
</ul>

Statistics include only <var>External Call</var> statements that actually called a module — even if the module subsequently abended. ECF statistics do not include <var>External Call</var> statements with parameter errors or those that timed out trying to get a module or subtask.

==ECF examples==

This section illustrates, in various languages, how to write, compile, link and invoke an external module that adds two numbers together and returns the sum. For clarity, the sample code omits error handling, other standard elements, and some JCL elements.

===COBOL sample 1===

This example uses the Language Environment enabled compiler, IBM COBOL FOR z/OS AND z/VM.
COBOL program
//COBSAMP EXEC PGM=IGYCRCTL,PARM=(NOSEQ,RENT)
//SYSLIN DD DSN=YOUR.OBJLIB(COBSAMP),DISP=SHR
//SYSIN DD *
IDENTIFICATION DIVISION.
PROGRAM-ID. COBSAMP.
DATA DIVISION.
LINKAGE SECTION.
01 M204-PARMS.
03 NUMBER-ONE PIC S9(7) COMP-3.
03 NUMBER-TWO PIC S9(9) BINARY.
03 NUMBER-SUM PIC S9(9) BINARY.
PROCEDURE DIVISION USING M204-PARMS.
COMPUTE NUMBER-SUM EQUAL NUMBER-ONE + NUMBER-TWO
MOVE ZERO TO RETURN-CODE
GOBACK.

Language Environment options
//ASMUOPT EXEC PGM=ASMA90,PARM='NOXREF'
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
// DD DSN=CEE.SCEEMAC,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSN=YOUR.OBJLIB(CEEUOPT),DISP=SHR
//SYSIN DD *
CEEUOPT CSECT
CEEUOPT AMODE ANY
CEEUOPT RMODE ANY
PRINT ON,NOGEN
CEEXOPT
ABTERMENC=(ABEND),
RTEREUS=(ON)
END

Linkedit
//LINK EXEC PGM=IEWL,PARM='LIST,MAP'
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DSN=CEE.SCEELKED,DISP=SHR
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSLIN DD *
INCLUDE OBJLIB(CEEUOPT)
INCLUDE OBJLIB(COBSAMP)
NAME COBSAMP(R)

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR
// DD DSN=CEE.SCEERUN,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.PACKED IS PACKED LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE COBSAMP
EXTERNAL LOAD COBSAMP
EXTERNAL NAME MOD_COBSAMP FOR COBSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.PACKED = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_COBSAMP WITH PARMS
PRINT %PARMS:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END

Comments
<table>
<tr class="head">
<th>COBOL </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
PIC S9(7) COMP-3
</td>
<td>
PACKED LEN 4
</td>
</tr>

<tr>
<td>
PIC S9(9) BINARY
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>
<ul>
<li>The Language Environment option <code>ABTERMENC=(ABEND)</code> must be specified.</li>

<li>Specify the Language Environment option <code>RTEREUS=(ON)</code> and code <var>GOBACK</var> instead of <var>STOP RUN</var>, as illustrated, to make the runtime environment reusable and to improve performance.</li>

<li>Setting Language Environment options is described in IBM Manual SC28-1939 <var class="book">Language Environment for z/OS & z/VM Programing Guide</var>. In the code in the "Calling from SOUL" section in the example above, Language Environment options are set by linking CEEUOPT with the COBOL module. Other methods are also available; check with your site's Language Environment administrator to determine the appropriate method to use.</li>
</ul>

===COBOL sample 2===

This example illustrates the use of multiple images using the Language Environment enabled compiler, IBM COBOL FOR z/OS AND z/VM. 
Note: Ordinarily, multiple images are only used if the parameters to be passed cannot fit into a single image. Images are limited in size to 32767 bytes.
COBOL program
IDENTIFICATION DIVISION.
PROGRAM-ID. COBSAM2.
DATA DIVISION.
LINKAGE SECTION.
01 M204-PARMS1.
03 NUMBER-ONE PIC S9(7) COMP-3.
01 M204-PARMS2.
03 NUMBER-TWO PIC S9(9) BINARY.
01 M204-PARMS3.
03 NUMBER-SUM PIC S9(9) BINARY.
PROCEDURE DIVISION USING M204-PARMS1, M204-PARMS2, M204-PARMS3.
COMPUTE NUMBER-SUM EQUAL NUMBER-ONE + NUMBER-TWO
MOVE ZERO TO RETURN-CODE
GOBACK.

Calling from SOUL
BEGIN
IMAGE PARMS1
NUMBER.ONE.PACKED IS PACKED LEN 4
END IMAGE
IMAGE PARMS2
NUMBER.TWO.BINARY IS BINARY LEN 4
END IMAGE
IMAGE PARMS3
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE COBSAM2
EXTERNAL LOAD COBSAM2
EXTERNAL NAME MOD_COBSAM2 FOR COBSAM2

PREPARE IMAGE PARMS1
PREPARE IMAGE PARMS2
PREPARE IMAGE PARMS3
%PARMS1:NUMBER.ONE.PACKED = 1
%PARMS2:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_COBSAM2 WITH PARMS1, PARMS2, PARMS3
PRINT %PARMS1:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS2:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS3:NUMBER.SUM.BINARY
END


===SAS/C sample===

This example uses the SAS/C compiler, not the IBM C compiler.
SAS/C program
//C EXEC PGM=LC370B
//STEPLIB DD DSN=SASC.LOAD,DISP=SHR
//SYSLIB DD DSN=SASC.MACLIBC,DISP=SHR
//SYSLIN DD DSN=YOUR.OBJLIB(SASCSAMP),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
typedef struct PARMAREA {
int A;
int B;
int C;
} parmarea;

int main(int argc, char **argv) {
parmarea *pptr;
if (argc != 2) {
/* the parameter list was not in OS format */
return 1000;
}
pptr = (parmarea *) argv[1];
pptr->C = pptr->A + pptr->B;
return 0;
}

Linkedit
//LC EXEC PGM=IEWL,PARM='AMODE(31),RMODE(ANY)'
//SYSLIB DD DSN=SASC.STDLIB,DISP=SHR
// DD DSN=SASC.BASELIB,DISP=SHR
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD *
INCLUDE OBJLIB(SASCSAMP)
ENTRY $MAINC
NAME SASCSAMP(R)
//*

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.BINARY IS BINARY LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE SASCSAMP
EXTERNAL LOAD SASCSAMP
EXTERNAL NAME MOD_SASCSAMP FOR SASCSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.BINARY = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_SASCSAMP WITH PARMS
PRINT %PARMS:NUMBER.ONE.BINARY WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END

Comments
<table>
<tr class="head">
<th>SAS/C </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
int
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>
<ul>
<li>The SAS/C program must be coded as a main program, not a subroutine.</li>

<li>To enable SAS/C to accept parameters in standard OS format, the entry point must be defined as <code>$MAINC</code> and the parameters handled as illustrated. This technique is described in the <var class="book">SAS/C Compiler and Library User's Guide</var>.</li>
</ul>

===Assembler sample===

This example uses the non-Language Environment assembler.
Assembler program
//ASMSAMP EXEC PGM=ASMA90
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
//SYSLIN DD DSN=YOUR.OBJLIB(ASMSAMP),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
ASMSAMP CSECT

ASMSAMP AMODE 31
ASMSAMP RMODE ANY
USING *,15
L 1,0(1) GET ADDRESS OF IMAGE COPY
XC WORKAREA,WORKAREA CLEAR WORK AREA
MVC WORKAREA+4(4),0(1) GET FIRST NUMBER (PACKED)
CVB 0,WORKAREA GET FIRST NUMBER (BINARY)
A 0,4(1) ADD SECOND NUMBER (BINARY)
ST 0,8(1) STORE SUM (BINARY)
XR 15,15 ZERO RETURN CODE
BR 14 RETURN
DS 0D
WORKAREA DS PL8 WORKING STORAGE
END ASMSAMP

Linkedit
//LASM EXEC PGM=IEWL
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD *
INCLUDE OBJLIB(ASMSAMP)
NAME ASMSAMP(R)

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.PACKED IS PACKED LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE ASMSAMP
EXTERNAL LOAD ASMSAMP
EXTERNAL NAME MOD_ASMSAMP FOR ASMSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.PACKED = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_ASMSAMP WITH PARMS
CALL CHECK.STATUS
PRINT %PARMS:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END


Comments
<table>
<tr class="head">
<th>Assembler </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
DS PL4
</td>
<td>
PACKED LEN 4
</td>
</tr>

<tr>
<td>
DS F
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>


===IDCAMS example===

This example uses the <var>IDCAMS</var> option (available as of Model 204 7.7) on the ECF <var>Module</var> statement to have IDCAMS input and output go from/to the user buffer.

====Module definition====
The following <var>External</var> statements make IDCAMS available:
b
external module idcams idcams
external load idcams
external name idcams for idcams
end


When <var>IDCAMS</var> is invoked by <var>External Call</var>, the user's [[Universal Buffer]] must contain the input lines to be passed to <code>SYSIN</code>, separated by EBCDIC linefeed characters (X'25'). The output lines from <var>IDCAMS</var> are appended to the Universal Buffer, also separated by new lines.

Before calling <var>IDCAMS</var>, the Universal Buffer must be allocated to a length sufficient to hold all of the input lines and all of the expected output lines. If the buffer is too small, output is truncated. While it is possible to calculate the optimum Universal Buffer length on each invocation, it is better to do the following to minimize storage fragmentation:
<ul>
<li>Use the same value for all invocations.</li>

<li>Use a multiple of 8K. </li>
</ul>

====Return codes====
The <var>IDCAMS</var> interface can return one of the following return codes:
<table class="thJustBold">
<tr><th>20</th>
<td>Universal Buffer was overflowed, output truncated.</td></tr>

<tr><th>24</th>
<td>Minimum outspace (2,000 bytes) not available in Universal Buffer.</td></tr>

<tr><th>28</th>
<td>No input data in Universal Buffer.</td></tr>

<tr><th>Else</th>
<td>The return code is from the IDCAMS program.</td></tr>
</table>

====SOUL code====
b
%idcams.in is longstring
%idcams.out is longstring
%lines.in is object stringlist
%lines.out is object stringlist

%hlq is string len 8
%options is string len 32
%input.len is float
%rc is float

%hlq = 'DRAKE'
%options = 'VOLUMES'

* Prepare IDCAMS input lines in stringlist. Note that that the
* TEXT TO statement supports expressions allowing %variables and
* functions to be used as the trivial example shows.
%lines.in = new
Text nocont To %lines.in
{} LISTCAT -
LEVEL({%hlq}) -
{%options}
End Text

* Note: the null expression {} in front of LISTCAT is to force
* indentation, since IDCAMS commands cannnot begin in column 1.

* Convert the stringlist to a longstring with EBCDIC new line
* delimiters at the end of each line. This is needed to use the
* Model 204 Universal Buffer feature, which only understands
* byte strings.
%idcams.in = %lines.in:CreateLines

* Force Universal Buffer allocation of sufficient size
modify buffer size=65536 nopreserve clear

* Prime Universal Buffer with input for IDCAMS, save its length
%input.len = $Lstr_Set_UserBuffer(%idcams.in)

* Call the IDCAMS wrapper, appending output to Universal Buffer
external call idcams
Printtext $status={$STATUS}, $STATUSD={$STATUSD}, $ECFSTAT={$ECFSTAT}
%rc = +$substr($ecfstat,4,5)
Printtext In simpler terms, the IDCAMS return code was {%rc}.

* Retrieve output data from Universal Buffer (too bad there isn't
* a starting offset parameter) and parse lines to stringLlist.
%idcams.out = $lstr_substr($lstr_Get_UserBuffer,%input.len+1)
%lines.out = new
%lines.out:ParseLines(%idcams.out)

Printtext IDCAMS passed the following {%lines.in:count} lines:
%lines.in:print

Printtext Which produced {%lines.out:count} lines of output:
%lines.out:print
end


[[Category:System management]]
[[Category:System-level capabilities of Model 204]]

External Call Facility

2026-01-31T21:13:42Z

Gary: /* ECF return codes and $function */

==Overview==

The External Call Facility (ECF) is a method for programs written in [[SOUL]] to invoke external, non-<var class="product">Model 204</var> modules, such as non-IFAM COBOL modules. Data can be passed between <var class="product">Model 204</var> and external modules. External modules can open non-<var class="product">Model 204</var> data sets, read or write to them, and close them. In addition, multiple modules can be called multiple times in a single run. 

ECF is available only under z/OS.

==Working with ECF==

===Loading an external module===

Each external module that is called using ECF is dynamically loaded once into memory from a nominated load library or from //STEPLIB. If <var class="product">Model 204</var> is APF authorized, then any nominated load library identified for use by ECF must also be APF authorized. Otherwise, the <var>External Load</var> statement will fail with:
COMPLETION CODE=S306 REASON CODE=000C.


The load is done by an authorized user executing the <var>[[#load|External Load]]</var> statement; for example, by User 0 during startup. The load is issued from a dedicated ECF subtask that is used exclusively for module loads and deletes.

After an external module is loaded, a call-name of up to 48 characters is associated with it. An association is set up by an authorized user executing the <var>[[#name|External Name]]</var> statement; typically by User 0 during startup. More than one call name can be associated with the same load module name.

Callers of the external module always refer to the call (logical) name rather than the load module (physical) name. Thus, if a load module name or location changes, only the setup statements need to be changed; no application code changes are required.

===Calling an external module===

A previously loaded external module is called by a user executing the <var>[[#call|External Call]]</var> statement. This invokes a separate ECF subtask to run the external module, and causes the user to enter a swappable, bumpable wait state. When the external module completes, control returns to the user. There are no restrictions on the length of time the external module can run.

Data is passed between <var class="product">Model 204</var> and an external module via a <var class="product">Model 204</var> [[Images|image]]. A copy of the image is made when the module is called, so that the caller need not remain in the server while the external module runs. The external module can modify the copy of the image. The modified image is returned to the caller, unless the <var>[[#module|External Module]]</var> statement specified <code>PARMTYPE=INPUT</code>.

===Avoiding data corruption and incorrect results===

External modules must not access any data set that <var class="product">Model 204</var> or any other external module has already opened. 
Attention: Failure to observe this could result in data corruption or abends, either in the external module or Model 204.

External modules invoked using ECF run under separate z/OS subtasks in the same address space as the <var class="product">Model 204</var> Online that invoked the module. This means that external modules run in parallel with <var class="product">Model 204</var> (and each other), even if you do not use MP/204 (multiprocessor).

Most errors that can occur in the external module are isolated from <var class="product">Model 204</var>. However, it is still possible for programming errors in external modules to corrupt or overwrite storage belonging to <var class="product">Model 204</var>. A programming error in your external module could result in data corruption, abends, or incorrect results in the external module or in Model 204.

===Stopping an external load module===

Authorized users can stop an external module in the following ways; by executing:
<ul>
<li><var>[[#stop|External Stop]]</var> statement, usage of a load module can be disabled by an authorized user. It can be enabled again by the <var>[[#start|External Start]]</var> statement.</li>

<li><var>[[#delete|External Delete]]</var> statement, a load module can be removed from storage by an authorized user. An <var>External Delete</var> statement must not be used for Language Environment (LE) modules, because z/OS does not support the use of DELETE of Language Environment main programs and an abend can result.</li>
</ul>

===ECF statistics and messages===

See the table in [[Using system statistics#Statistics with descriptions|Statistics with descriptions]] for the System-final, user-logout, user-since-last, SMF-logout, and SMF-since-last statistics that relate to ECF.

===BUMP command enhanced with the FORCE option for ECF users===

Simply bumping a user that is executing an <var>External Call</var> statement does not interrupt the external module. The external module is allowed to complete — however long that takes —and then the bump takes effect.

To interrupt an external module, you must issue a <var>[[BUMP command|BUMP]]</var> command with the <var>FORCE</var> option. Or, you can continue to use the <var>External Stop</var> statement with the <var>FORCE</var> option.

If the <var>FORCE</var> option is specified on a <var>BUMP</var> command, then the users who are running an external module are interrupted. The <var>FORCE</var> option may be combined with any other <var>BUMP</var> options. When you specify the <var>FORCE</var> option, it must be the first option on the command.

====Examples====
BUMP FORCE ALL

BUMP FORCE SUBSYS MYAPSY

BUMP FORCE MODULE MYPGM

For users who are not running an external module, the presence or absence of the <var>FORCE</var> option is irrelevant. Adding the <var>FORCE</var> option affects only users who are running an external module. The <var>FORCE</var> option does not interrupt users that are in an unbumpable wait.

==ECF SOUL statements==

You must check <var>[[$Status]]</var> and <var>[[$StatusD]]</var> return codes after each ECF statement.

===External Call statement===
<dl>
<dt>Function</dt>
<dd>Calls an external module that was previously loaded using an <var>External Load</var> statement, using a call name that was previously specified in an <var>External Name</var> statement.</dd>
<dt>Privileges</dt>
<dd>
Any user</dd>
<dt>Syntax</dt>
<dd>External Call call-name [WITH image-1 [,image-2,...image-60]] 

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>call-name</th>
<td>Logical name, either a literal or %variable, of the external module to invoke.</td>
</tr>

<tr>
<th><var>WITH clause</var></th>
<td>The optional <var>WITH</var> clause specifies the images to pass as a parameter area between the SOUL program and the external module. If no parameter area is required, you can omit the <var>WITH</var> clause.</td>
</tr>

<tr>
<th nowrap>image-1,...image-60</th>
<td>Name(s) of a previously defined image(s) to pass to the external module.</td>
</tr>
</table>
</dd>
<dt>Usage</dt>
<dd>
<ul>
<li>You can specify from one to sixty images separated by commas.</li>

<li>A return code of zero does not mean that the external module performed as it was designed; it simply means that the module was successfully invoked and completed without an abend. </li>

<li>Without a parameter area, the external module cannot directly pass any data back to a SOUL program other than via its return code. It can, of course, indirectly pass data back: for example, by updating a sequential data set that the SOUL program can then inspect.</li>

<li>If Model 204 is using an external authorizer such as ACF2, RACF, or Top/Secret: The default external-authorizer profile under which a job invoked by a privileged ECF statement runs is changed in version 7.7 of Model 204. Instead of such a job running under the job's external-authorizer profile (as it did prior to 7.7), the job runs by default in 7.7 under the user's external-authorizer profile.

The default behavior can be changed by turning on the system parameter <var>[[ECPRIV parameter|ECPRIV]]</var> 4 bit. </li>
</ul></dd>
</dl>

===External Delete statement===
<dl>
<dt>Function</dt>
<dd>Removes a previously loaded external module from storage.</dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Delete module-name


Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>A literal or a %variable that is the module name of a previously loaded external module.</td></tr>
</table></dd>
<dt>Usage</dt>
<dd>Do not use the <var>External Delete</var> statement for Language Environment modules.</dd>
</dl>

===External Load statement===
<dl>
<dt>Function</dt>
<dd>Loads an external module into storage. The module, previously defined by an <var>External Module</var> statement, is loaded and is then available to all users.</dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Load module-name


Where:
<table>
<tr class="head">
<th>Argument </th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>A literal or a %variable that is the name of the external module, a PDS member name.</td>
</tr>
</table></dd>
</dl>

===External Module statement===
<dl>
<dt>Function</dt>
<dd>Defines an external module for later loading. </dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Module module-name [DDNAME=ddname]
[PARMTYPE=INPUT | OUTPUT]
[PARMSIZE=value]
[PARMMODE=[24 | 31]]
[REENTRANT | AFFINITY]
[IDCAMS]

Where:
<table>
<tr class="head">
<th>Argument </th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name </th>
<td>A literal or %variable that is the name of the external module, a PDS member name. Required.</td></tr>

<tr>
<th>ddname </th>
<td>A literal or %variable that is the DDNAME of the PDS where the load module is located. If omitted, the standard search order or //STEPLIB is used. Optional.

Note: If <var class="product">Model 204</var> is APF authorized, then this data set must also be APF authorized.
</td></tr>

<tr>
<th><var>PARMTYPE</var> </th>
<td>The parameter (image) type passed to the external module on an <var>External Call</var> statement. Optional.
<ul>
<li><var>INPUT</var> means that any changes made by the external module to the parameter are discarded. </li>

<li><var>OUTPUT</var>, the default, means that any changes are retained.</li>
</ul>
</td></tr>

<tr>
<th><var>PARMSIZE</var> </th>
<td>A literal or %variable that is the required size of the parameter (image) passed to the external module on all <var>External Call</var> statements.

If the actual parameter size does not match the required size, the <var>External Call</var> statement fails. 

If <var>PARMSIZE</var> is not specified, the parameter size is not checked. 
</td></tr>

<tr>
<th><var>PARMMODE</var></th>
<td>Where storage to hold the copy of the parameter area is allocated. Optional.
<ul>
<li>24 means allocate in 24-bit, below-the-line storage.</li>

<li>31, the default, means allocate in 31-bit, above the line storage.</li>

<li>Do not specify <code>PARMMODE=24</code> unless the module has a specific requirement for this setting.</li>
</ul></td></tr>

<tr>
<th><var>REENTRANT</var> </th>
<td>Module that can be used by more than one user at a time. This optional argument takes effect only if the module was link-edited with the REENTRANT attribute.</td>
</tr>

<tr>
<th><var>AFFINITY</var> </th>
<td>Module always runs on the same subtask. Conversely, that subtask runs only that module.</td>
</tr>

<tr>
<th><var>IDCAMS</var> </th>
<td>The module is the [https://en.wikipedia.org/wiki/IBM_mainframe_utility_programs#IDCAMS IBM IDCAMS utility]. Specifying this option causes the IDCAMS module to be invoked in such a way that, rather than reading data from the <var>SYSIN</var> DD and sending output to the <var>SYSPRINT</var> DD, data is read from and written to the user buffer (sometimes known as the Universal Buffer).

The <var>IDCAMS</var> option is available as of Model 204 7.7. For an example, see [[#IDCAMS example|IDCAMS example]], below.

Specifying this option for a module other than IDCAMS is likely to result in abends in the module when called.
</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>
<ul>
<li>You can use an <var>External Module</var> statement to define a module using either:
<ul>
<li>New name and attributes.</li>

<li>Existing name. Attributes associated with an existing name are replaced by new attributes.</li>
</ul></li>

<li>Subtask affinity, which is specified by the <var>AFFINITY</var> keyword, is required in some situations. For example, when an external module opens a data set on one call, but does not close it till a subsequent call. Subtask affinity is required because z/OS requires that you open and close a data set from the same subtask. </li>

<li>The <var>AFFINITY</var> keyword is incompatible with the <var>REENTRANT</var> keyword. A compilation error is generated, if both are specified for the same module. You specify one or the other or neither, but not both.</li>
</ul></dd>
</dl>

===External Name statement===
<dl>
<dt>Function</dt>
<dd>Use the <var>External Name</var> statement to:
<ul>
<li>Associate a logical call name with the name of a module that was previously defined by issuing an <var>External Module</var> statement</li>

<li>Remove a previously set up association. A module can have multiple call names.</li>
</ul></dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Name call-name FOR module-name

External Name call-name REMOVE

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>call-name</th>
<td>Logical name to associate with an external module. Up to 48 characters.</td>
</tr>

<tr>
<th>module-name</th>
<td>Name of a previously loaded external module.</td>
</tr>
</table></dd>
</dl>

===External Start statement===
<dl>
<dt>Function</dt>
<dd>Enables further calls to an ECF module.</dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>

<dt>Syntax</dt>
<dd>
External Start module-name

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name </th>
<td>Name of a previously loaded external module.</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>Initially a module is in the START state. You need not issue an <var>External Start</var> statement unless you want to reverse a prior <var>External Stop</var> statement.
</dd>
</dl>

===External Stop statement===
<dl>
<dt>Function</dt>
<dd>Stops further calls to an ECF module. Currently executing calls either complete or, if the FORCE option is used, abend.</dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>

<dt>Syntax</dt>
<dd>External Stop module-name [FORCE]

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>Name of a previously loaded external module.</td>
</tr>

<tr>
<th><var>FORCE</var></th>
<td>Users currently executing the specified module are bumped.</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>The following table describes how an <var>External Stop</var> statement is evaluated.
<table>
<tr class="head">
<th>When <var>External Stop</var> statement is issued </th>
<th>
Then</th>
</tr>

<tr>
<td>If no users are executing the module </td>
<td>Module is immediately marked stopped. </td>
</tr>

<tr>
<td>If one or more users are executing the module </td>
<td>Module is marked draining until the last user finishes executing the module, then it is marked stopped. </td>
</tr>

<tr>
<td>If <var>FORCE</var> was specified </td>
<td>Current users of the module are bumped.</td>
</tr>

<tr>
<td>If <var>FORCE</var> was not specified </td>
<td>Current users of the module are allowed to complete. </td>
</tr>
</table>

In all cases, subsequent attempts by any user to call the module with an <var>External Call</var> statement result in a <var>$Status</var> of 8. 
Note: Rocket Software does not recommend using the <var>FORCE</var> option, as <var class="product">Model 204</var> cannot ensure that the external module is terminated cleanly.</dd>
</dl>

==ECF return codes and $function==

All <var>EXTERNAL</var> statements set <var>$Status</var> and <var>$StatusD</var>.
<table>
<caption>ECF return codes</caption>
<tr class="head">
<th>$Status</th>
<th>$StatusD</th>
<th>Meaning</th>
</tr>

<tr>
<td align="right">0</td>
<td align="right">0</td>
<td>ECF function completed without error</td>
</tr>

<tr>
<td align="right">1</td>
<td align="right">0</td>
<td>ECF inactive</td>
</tr>

<tr>
<td align="right">2</td>
<td align="right">0</td>
<td>User not authorized for ECF function, see ECPRIV parameter</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>Unable to obtain ACEE for setting ECF subtask security profile</td>
</tr>

<tr>
<td align="right">3</td>
<td align="right">1</td>
<td>Invalid module name</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>Invalid call name</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>Invalid DDNAME</td>
</tr>

<tr>
<td> </td>
<td align="right">4</td>
<td>Image inactive</td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>Invalid PARMSIZE</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">0</td>
<td>Call name not defined</td>
</tr>

<tr>
<td align="right">6</td>
<td align="right">0</td>
<td>Module not defined</td>
</tr>

<tr>
<td align="right">7</td>
<td align="right">0</td>
<td>Module not loaded</td>
</tr>

<tr>
<td align="right">8</td>
<td align="right">0</td>
<td>Module unavailable (draining or stopped)</td>
</tr>

<tr>
<td align="right">10</td>
<td align="right">0</td>
<td>Module not deleted</td>
</tr>

<tr>
<td align="right">20</td>
<td> </td>
<td>System busy; timed out</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>Module unavailable</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>No subtask available</td>
</tr>

<tr>
<td align="right">30</td>
<td> </td>
<td>Load or delete failed</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>DDNAME not present</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>DDNAME open failed</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>DDNAME close failed</td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>Load or delete failed; see the <var>[[$EcfStat]]</var> function.
</td>
</tr>

<tr>
<td> </td>
<td align="right">6</td>
<td>Internal ECF abend; see the <var>$EcfStat</var> function page.</td>
</tr>

<tr>
<td> </td>
<td align="right">7</td>
<td>Internal ECF ABEND; load or delete subtask terminated by the operating system.</td>
</tr>

<tr>
<td align="right">40</td>
<td align="right">0</td>
<td>Module failed</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>Module gave nonzero return code; see the <var>$EcfStat</var> function page.
</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>Module abend; see the <var>$EcfStat</var> function page.
</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>Insufficient memory available to allocate a buffer for the parameter area</td>
</tr>

<tr>
<td> </td>
<td align="right">4</td>
<td>Actual parameter size is not equal to <var>PARMSIZE</var></td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>When the parameter area, as updated by the external module, was being copied back to the original image(s), ECF detected that the size of one of the images had been changed. This status can occur only if an image contains a variable array whose size is changed by the external module.</td>
</tr>

<tr>
<td> </td>
<td align="right">6</td>
<td>ECF subtask terminated by the operating system</td>
</tr>

<tr>
<td align="right">50</td>
<td align="right">0</td>
<td>ECF internal table full</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>ECF ECMODS table full; increase <var>ECMODS</var> User 0 parameter</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>ECF ECNAMES table full; increase <var>ECNAMES</var> User 0 parameter</td>
</tr>
</table>

===$EcfStat function===

The <var>[[$EcfStat]]</var> function returns the detailed completion code from the previous <var>EXTERNAL</var> statement.


==ECF User 0 parameters==

The following User 0 parameters are used by ECF.

A system manager can reset only the <var>ECWAIT</var> parameter; the other ECF parameters cannot be reset.
<table>
<tr class="head">
<th>User 0 parameter </th>
<th>Returns...</th>
</tr>

<tr>
<td><var>[[ECISUBS parameter|ECISUBS]]</var> </td>
<td>Subtasks for running external modules initially attached</td>
</tr>

<tr>
<td><var>[[ECMODS parameter|ECMODS]]</var> </td>
<td>External modules to load</td>
</tr>

<tr>
<td><var>[[ECMSUBS parameter|ECMSUBS]]</var> </td>
<td>Number of ECF subtasks for running modules</td>
</tr>

<tr>
<td><var>[[ECNAMES parameter|ECNAMES]]</var> </td>
<td>Number of external call names</td>
</tr>

<tr>
<td><var>[[ECPRIV parameter|ECPRIV]]</var> </td>
<td>ECF privileges</td>
</tr>

<tr>
<td><var>[[ECPSIZE parameter|ECPSIZE]]</var> </td>
<td>Size of largest image used by ECF</td>
</tr>

<tr>
<td><var>[[ECWAIT parameter|ECWAIT]]</var> </td>
<td>ECF wait time</td>
</tr>

<tr>
<td><var>[[ECWAIT parameter|ECMAXCPU]]</var> </td>
<td>Maximum CPU time in seconds allowed for an external call of an ECF module, else 0 for no limit. If limit is exceeded, the ECF module a user 099 ABEND is reflected to the ECF task. This support added by 79Z087.</td>
</tr>
</table>

==Subtask and load module management==

Some z/OS overhead accrues in loading an external module into storage and attaching a z/OS subtask under which it runs. ECF avoids incurring this cost for every <var>External Call</var> statement by managing the load modules and subtasks as described in the following sections.

===Subtasks assignment===

At system startup, the following subtasks are started:
<ul>
<li>One subtask for loading and deleting modules</li>

<li>One or more subtasks, specified by the <var>ECISUBS</var> parameter, for executing external modules</li>
</ul>

When a user issues an <var>External Call</var> statement, an unused ECF subtask is selected on which to run the external module, up to the limit of <var>ECMSUBS</var>. Users unable to get a subtask enter a wait of up to <var>ECWAIT</var> milliseconds for a subtask to become available. When an in-use ECF subtask becomes available, because the module that was running under it ends, it is assigned to a user waiting for a subtask. If a user's wait time expires before a subtask is available, a no-subtask-available failure is returned.

===Subtask affinity===

Normally, when an external module is called via the <var>External Call</var> statement, ECF selects any free subtask on which to execute the module. Although this is appropriate for most external modules, some modules might need to always be executed on the same subtask. This is known as subtask affinity. Subtask affinity for a module is specified by the <var>AFFINITY</var> option on the <var>External Module</var> statement. The <var>AFFINITY</var> option is incompatible with the <var>REENTRANT</var> option.
<ul>
<li>If the <var>AFFINITY</var> option is not specified, the module does not have subtask affinity. This is the default. </li>

<li>If the <var>AFFINITY</var> option is specified, the module has subtask affinity. </li>
</ul>

When the first <var>External Call</var> of the module is executed, a dedicated subtask for the module is attached. A two-way association between the module and the subtask is established. That module will run on only that subtask, not on any other subtask. That subtask is used to run only that module, not any other module.

If a module has subtask affinity, and the dedicated subtask for that module is abnormally terminated for any reason, the previous dedicated subtask is detached, and a new dedicated subtask for the module is attached. A subtask could be abnormally terminated if the module it was running has an abend, or the user running the module is bumped. Therefore, specifying <var>AFFINITY</var> does not guarantee that the same subtask is always used for that module for the duration of a <var class="product">Model 204</var> Online.

If you use modules with subtask affinity, ensure that <var>ECISUBS</var> and <var>ECMSUBS</var> are appropriately set. In particular, <var>ECISUBS</var> and <var>ECMSUBS</var> must be greater than or equal to the number of modules with subtask affinity.
<ul>
<li>The <var>ECISUBS</var> parameter specifies the number of subtasks attached during system initialization. These subtasks are never used for modules with subtask affinity; the first <var>External Call</var> of a module with subtask affinity always results in a new subtask being attached (subject to <var>ECMSUBS</var>). </li>

<li>The <var>ECMSUBS</var> parameter specifies the maximum number of ECF subtasks used to run modules. The number of subtasks used for modules with subtask affinity plus the number of subtasks used for modules without subtask affinity will be a maximum of <var>ECMSUBS</var>.</li>
</ul>

===Load modules===

An external module is usually loaded into storage just once. The exception is when an <var>External Load</var> statement, possibly preceded by an <var>External Delete</var> statement, is used to reload a previously-loaded module.

Normally, one <var class="product">Model 204</var> user at a time is allowed to issue an <var>External Call</var> statement for the module. Other users who attempt to call the module while it is in use, enter a wait-state of up to <var>ECWAIT</var> milliseconds for the module to become available. When a module is freed, because the current execution of it ends, it is assigned to one of the users waiting for it. If a user's wait time expires before the module is assigned, a module-in-use failure is returned. 

If a load module was link-edited with the REENTRANT (also written, RENT) attribute, and if the <var>External Module</var> statement that defined the module characteristics specified the <var>REENTRANT</var> option, then multiple <var class="product">Model 204</var> users are allowed to simultaneously issue an <var>External Call</var> statement for the module — subject to subtask availability.

===Fulfillment order===

An <var>External Call</var> statement can invoke an external module only if both an ECF subtask is free, and for a serially reusable module, if the module is not in use by another user. The check that the module is not in use by another user is done before the allocation of a subtask so that the most restrictive condition is checked first.

==Restrictions and cautions==

The following restrictions and cautions apply to the use of ECF:
<ul>
<li>ECF loads an external module only once, when the <var>External Load</var> statement is issued. Thereafter, every user who issues an <var>External Call</var> statement for that module uses the same copy of the module. Therefore, you must write your module to initialize itself properly on every call.</li>

<li>ECF passes the copy of the parameter area to the external module using standard z/OS linkage conventions. Your external module must support these conventions to receive the parameters.</li>

<li>ECF does not provide any special initialization of the environment when you issue an <var>External Call</var> statement; it merely branches to the in-memory copy of the module. Therefore, your module must perform any required initialization and termination of its run-time environment. In particular, this means that an external module, written in any language, should be written as a main routine and not a subroutine.</li>

<li>Only one copy of a load module can be in memory at a time. This is a z/OS restriction.</li>

<li>Externally called modules must be <code>AMODE(31)</code> and either <code>RMODE(ANY)</code> or <code>RMODE(31)</code>.</li>

<li>Externally called modules must not attempt to retain any context information from one call to another. You must write the modules so that each call executes independently of any other.
</li>

<li>For efficiency purposes, ECF does not use z/OS to maintain the usage counts or status information for load modules. Control is passed by direct branch rather than use of the z/OS ATTACH, LINK, or XCTL macros. Therefore, one external module must not attempt to load or attach another external module, or attempt to reference code or data in another external module.</li>

<li>The definition of the parameter area in <var class="product">Model 204</var> — the image definition — must agree with the definition of the parameter area in the external module (in a COBOL program, the LINKAGE SECTION). If they do not agree, it is possible for the module to modify the wrong storage.

To prevent this, <var class="product">Model 204</var> checks that the external module put its results in only the assigned area — not somewhere else. <var class="product">Model 204</var> checks the area immediately past the end of the assigned area. If the unassigned area was used, <var class="product">Model 204</var> displays the following message and restarts the user:
M204.2563: MODULE=name RETURNED MORE THAN length BYTES
</li>
</ul>

==Tracking ECF==

===Wait types for ECF===

See the table of codes in the [[ONLINE_monitoring#Wait_type_values| listing of wait types]] that includes the External Call Facility, wait types 43 through 46.

===ECF statistics===

The following statistics help you track the External Call Facility. See [[Using system statistics#Statistics with descriptions|Statistics with descriptions]] for the position in the system-final, user-logout, user-since-last, SMF-logout, and/or SMF-since-last journal record layout as they apply. 
<ul>
<li>ECCALL</li>

<li>ECCNCT</li>

<li>ECCTOUT</li>

<li>ECCWAITM</li>

<li>ECCWAITS</li>

<li>ECDELETE</li>

<li>ECLOAD</li>

<li>ECMODMAX</li>

<li>ECNAMMAX</li>

<li>ECTSKMAX</li>

<li>ECTWAITM</li>

<li>ECTWAITS</li>
</ul>

Statistics include only <var>External Call</var> statements that actually called a module — even if the module subsequently abended. ECF statistics do not include <var>External Call</var> statements with parameter errors or those that timed out trying to get a module or subtask.

==ECF examples==

This section illustrates, in various languages, how to write, compile, link and invoke an external module that adds two numbers together and returns the sum. For clarity, the sample code omits error handling, other standard elements, and some JCL elements.

===COBOL sample 1===

This example uses the Language Environment enabled compiler, IBM COBOL FOR z/OS AND z/VM.
COBOL program
//COBSAMP EXEC PGM=IGYCRCTL,PARM=(NOSEQ,RENT)
//SYSLIN DD DSN=YOUR.OBJLIB(COBSAMP),DISP=SHR
//SYSIN DD *
IDENTIFICATION DIVISION.
PROGRAM-ID. COBSAMP.
DATA DIVISION.
LINKAGE SECTION.
01 M204-PARMS.
03 NUMBER-ONE PIC S9(7) COMP-3.
03 NUMBER-TWO PIC S9(9) BINARY.
03 NUMBER-SUM PIC S9(9) BINARY.
PROCEDURE DIVISION USING M204-PARMS.
COMPUTE NUMBER-SUM EQUAL NUMBER-ONE + NUMBER-TWO
MOVE ZERO TO RETURN-CODE
GOBACK.

Language Environment options
//ASMUOPT EXEC PGM=ASMA90,PARM='NOXREF'
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
// DD DSN=CEE.SCEEMAC,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSN=YOUR.OBJLIB(CEEUOPT),DISP=SHR
//SYSIN DD *
CEEUOPT CSECT
CEEUOPT AMODE ANY
CEEUOPT RMODE ANY
PRINT ON,NOGEN
CEEXOPT
ABTERMENC=(ABEND),
RTEREUS=(ON)
END

Linkedit
//LINK EXEC PGM=IEWL,PARM='LIST,MAP'
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DSN=CEE.SCEELKED,DISP=SHR
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSLIN DD *
INCLUDE OBJLIB(CEEUOPT)
INCLUDE OBJLIB(COBSAMP)
NAME COBSAMP(R)

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR
// DD DSN=CEE.SCEERUN,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.PACKED IS PACKED LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE COBSAMP
EXTERNAL LOAD COBSAMP
EXTERNAL NAME MOD_COBSAMP FOR COBSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.PACKED = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_COBSAMP WITH PARMS
PRINT %PARMS:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END

Comments
<table>
<tr class="head">
<th>COBOL </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
PIC S9(7) COMP-3
</td>
<td>
PACKED LEN 4
</td>
</tr>

<tr>
<td>
PIC S9(9) BINARY
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>
<ul>
<li>The Language Environment option <code>ABTERMENC=(ABEND)</code> must be specified.</li>

<li>Specify the Language Environment option <code>RTEREUS=(ON)</code> and code <var>GOBACK</var> instead of <var>STOP RUN</var>, as illustrated, to make the runtime environment reusable and to improve performance.</li>

<li>Setting Language Environment options is described in IBM Manual SC28-1939 <var class="book">Language Environment for z/OS & z/VM Programing Guide</var>. In the code in the "Calling from SOUL" section in the example above, Language Environment options are set by linking CEEUOPT with the COBOL module. Other methods are also available; check with your site's Language Environment administrator to determine the appropriate method to use.</li>
</ul>

===COBOL sample 2===

This example illustrates the use of multiple images using the Language Environment enabled compiler, IBM COBOL FOR z/OS AND z/VM. 
Note: Ordinarily, multiple images are only used if the parameters to be passed cannot fit into a single image. Images are limited in size to 32767 bytes.
COBOL program
IDENTIFICATION DIVISION.
PROGRAM-ID. COBSAM2.
DATA DIVISION.
LINKAGE SECTION.
01 M204-PARMS1.
03 NUMBER-ONE PIC S9(7) COMP-3.
01 M204-PARMS2.
03 NUMBER-TWO PIC S9(9) BINARY.
01 M204-PARMS3.
03 NUMBER-SUM PIC S9(9) BINARY.
PROCEDURE DIVISION USING M204-PARMS1, M204-PARMS2, M204-PARMS3.
COMPUTE NUMBER-SUM EQUAL NUMBER-ONE + NUMBER-TWO
MOVE ZERO TO RETURN-CODE
GOBACK.

Calling from SOUL
BEGIN
IMAGE PARMS1
NUMBER.ONE.PACKED IS PACKED LEN 4
END IMAGE
IMAGE PARMS2
NUMBER.TWO.BINARY IS BINARY LEN 4
END IMAGE
IMAGE PARMS3
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE COBSAM2
EXTERNAL LOAD COBSAM2
EXTERNAL NAME MOD_COBSAM2 FOR COBSAM2

PREPARE IMAGE PARMS1
PREPARE IMAGE PARMS2
PREPARE IMAGE PARMS3
%PARMS1:NUMBER.ONE.PACKED = 1
%PARMS2:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_COBSAM2 WITH PARMS1, PARMS2, PARMS3
PRINT %PARMS1:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS2:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS3:NUMBER.SUM.BINARY
END


===SAS/C sample===

This example uses the SAS/C compiler, not the IBM C compiler.
SAS/C program
//C EXEC PGM=LC370B
//STEPLIB DD DSN=SASC.LOAD,DISP=SHR
//SYSLIB DD DSN=SASC.MACLIBC,DISP=SHR
//SYSLIN DD DSN=YOUR.OBJLIB(SASCSAMP),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
typedef struct PARMAREA {
int A;
int B;
int C;
} parmarea;

int main(int argc, char **argv) {
parmarea *pptr;
if (argc != 2) {
/* the parameter list was not in OS format */
return 1000;
}
pptr = (parmarea *) argv[1];
pptr->C = pptr->A + pptr->B;
return 0;
}

Linkedit
//LC EXEC PGM=IEWL,PARM='AMODE(31),RMODE(ANY)'
//SYSLIB DD DSN=SASC.STDLIB,DISP=SHR
// DD DSN=SASC.BASELIB,DISP=SHR
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD *
INCLUDE OBJLIB(SASCSAMP)
ENTRY $MAINC
NAME SASCSAMP(R)
//*

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.BINARY IS BINARY LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE SASCSAMP
EXTERNAL LOAD SASCSAMP
EXTERNAL NAME MOD_SASCSAMP FOR SASCSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.BINARY = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_SASCSAMP WITH PARMS
PRINT %PARMS:NUMBER.ONE.BINARY WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END

Comments
<table>
<tr class="head">
<th>SAS/C </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
int
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>
<ul>
<li>The SAS/C program must be coded as a main program, not a subroutine.</li>

<li>To enable SAS/C to accept parameters in standard OS format, the entry point must be defined as <code>$MAINC</code> and the parameters handled as illustrated. This technique is described in the <var class="book">SAS/C Compiler and Library User's Guide</var>.</li>
</ul>

===Assembler sample===

This example uses the non-Language Environment assembler.
Assembler program
//ASMSAMP EXEC PGM=ASMA90
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
//SYSLIN DD DSN=YOUR.OBJLIB(ASMSAMP),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
ASMSAMP CSECT

ASMSAMP AMODE 31
ASMSAMP RMODE ANY
USING *,15
L 1,0(1) GET ADDRESS OF IMAGE COPY
XC WORKAREA,WORKAREA CLEAR WORK AREA
MVC WORKAREA+4(4),0(1) GET FIRST NUMBER (PACKED)
CVB 0,WORKAREA GET FIRST NUMBER (BINARY)
A 0,4(1) ADD SECOND NUMBER (BINARY)
ST 0,8(1) STORE SUM (BINARY)
XR 15,15 ZERO RETURN CODE
BR 14 RETURN
DS 0D
WORKAREA DS PL8 WORKING STORAGE
END ASMSAMP

Linkedit
//LASM EXEC PGM=IEWL
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD *
INCLUDE OBJLIB(ASMSAMP)
NAME ASMSAMP(R)

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.PACKED IS PACKED LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE ASMSAMP
EXTERNAL LOAD ASMSAMP
EXTERNAL NAME MOD_ASMSAMP FOR ASMSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.PACKED = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_ASMSAMP WITH PARMS
CALL CHECK.STATUS
PRINT %PARMS:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END


Comments
<table>
<tr class="head">
<th>Assembler </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
DS PL4
</td>
<td>
PACKED LEN 4
</td>
</tr>

<tr>
<td>
DS F
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>


===IDCAMS example===

This example uses the <var>IDCAMS</var> option (available as of Model 204 7.7) on the ECF <var>Module</var> statement to have IDCAMS input and output go from/to the user buffer.

====Module definition====
The following <var>External</var> statements make IDCAMS available:
b
external module idcams idcams
external load idcams
external name idcams for idcams
end


When <var>IDCAMS</var> is invoked by <var>External Call</var>, the user's [[Universal Buffer]] must contain the input lines to be passed to <code>SYSIN</code>, separated by EBCDIC linefeed characters (X'25'). The output lines from <var>IDCAMS</var> are appended to the Universal Buffer, also separated by new lines.

Before calling <var>IDCAMS</var>, the Universal Buffer must be allocated to a length sufficient to hold all of the input lines and all of the expected output lines. If the buffer is too small, output is truncated. While it is possible to calculate the optimum Universal Buffer length on each invocation, it is better to do the following to minimize storage fragmentation:
<ul>
<li>Use the same value for all invocations.</li>

<li>Use a multiple of 8K. </li>
</ul>

====Return codes====
The <var>IDCAMS</var> interface can return one of the following return codes:
<table class="thJustBold">
<tr><th>20</th>
<td>Universal Buffer was overflowed, output truncated.</td></tr>

<tr><th>24</th>
<td>Minimum outspace (2,000 bytes) not available in Universal Buffer.</td></tr>

<tr><th>28</th>
<td>No input data in Universal Buffer.</td></tr>

<tr><th>Else</th>
<td>The return code is from the IDCAMS program.</td></tr>
</table>

====SOUL code====
b
%idcams.in is longstring
%idcams.out is longstring
%lines.in is object stringlist
%lines.out is object stringlist

%hlq is string len 8
%options is string len 32
%input.len is float
%rc is float

%hlq = 'DRAKE'
%options = 'VOLUMES'

* Prepare IDCAMS input lines in stringlist. Note that that the
* TEXT TO statement supports expressions allowing %variables and
* functions to be used as the trivial example shows.
%lines.in = new
Text nocont To %lines.in
{} LISTCAT -
LEVEL({%hlq}) -
{%options}
End Text

* Note: the null expression {} in front of LISTCAT is to force
* indentation, since IDCAMS commands cannnot begin in column 1.

* Convert the stringlist to a longstring with EBCDIC new line
* delimiters at the end of each line. This is needed to use the
* Model 204 Universal Buffer feature, which only understands
* byte strings.
%idcams.in = %lines.in:CreateLines

* Force Universal Buffer allocation of sufficient size
modify buffer size=65536 nopreserve clear

* Prime Universal Buffer with input for IDCAMS, save its length
%input.len = $Lstr_Set_UserBuffer(%idcams.in)

* Call the IDCAMS wrapper, appending output to Universal Buffer
external call idcams
Printtext $status={$STATUS}, $STATUSD={$STATUSD}, $ECFSTAT={$ECFSTAT}
%rc = +$substr($ecfstat,4,5)
Printtext In simpler terms, the IDCAMS return code was {%rc}.

* Retrieve output data from Universal Buffer (too bad there isn't
* a starting offset parameter) and parse lines to stringLlist.
%idcams.out = $lstr_substr($lstr_Get_UserBuffer,%input.len+1)
%lines.out = new
%lines.out:ParseLines(%idcams.out)

Printtext IDCAMS passed the following {%lines.in:count} lines:
%lines.in:print

Printtext Which produced {%lines.out:count} lines of output:
%lines.out:print
end


[[Category:System management]]
[[Category:System-level capabilities of Model 204]]

External Call Facility

2026-01-31T21:12:59Z

Gary: /* ECF return codes and $function */

==Overview==

The External Call Facility (ECF) is a method for programs written in [[SOUL]] to invoke external, non-<var class="product">Model 204</var> modules, such as non-IFAM COBOL modules. Data can be passed between <var class="product">Model 204</var> and external modules. External modules can open non-<var class="product">Model 204</var> data sets, read or write to them, and close them. In addition, multiple modules can be called multiple times in a single run. 

ECF is available only under z/OS.

==Working with ECF==

===Loading an external module===

Each external module that is called using ECF is dynamically loaded once into memory from a nominated load library or from //STEPLIB. If <var class="product">Model 204</var> is APF authorized, then any nominated load library identified for use by ECF must also be APF authorized. Otherwise, the <var>External Load</var> statement will fail with:
COMPLETION CODE=S306 REASON CODE=000C.


The load is done by an authorized user executing the <var>[[#load|External Load]]</var> statement; for example, by User 0 during startup. The load is issued from a dedicated ECF subtask that is used exclusively for module loads and deletes.

After an external module is loaded, a call-name of up to 48 characters is associated with it. An association is set up by an authorized user executing the <var>[[#name|External Name]]</var> statement; typically by User 0 during startup. More than one call name can be associated with the same load module name.

Callers of the external module always refer to the call (logical) name rather than the load module (physical) name. Thus, if a load module name or location changes, only the setup statements need to be changed; no application code changes are required.

===Calling an external module===

A previously loaded external module is called by a user executing the <var>[[#call|External Call]]</var> statement. This invokes a separate ECF subtask to run the external module, and causes the user to enter a swappable, bumpable wait state. When the external module completes, control returns to the user. There are no restrictions on the length of time the external module can run.

Data is passed between <var class="product">Model 204</var> and an external module via a <var class="product">Model 204</var> [[Images|image]]. A copy of the image is made when the module is called, so that the caller need not remain in the server while the external module runs. The external module can modify the copy of the image. The modified image is returned to the caller, unless the <var>[[#module|External Module]]</var> statement specified <code>PARMTYPE=INPUT</code>.

===Avoiding data corruption and incorrect results===

External modules must not access any data set that <var class="product">Model 204</var> or any other external module has already opened. 
Attention: Failure to observe this could result in data corruption or abends, either in the external module or Model 204.

External modules invoked using ECF run under separate z/OS subtasks in the same address space as the <var class="product">Model 204</var> Online that invoked the module. This means that external modules run in parallel with <var class="product">Model 204</var> (and each other), even if you do not use MP/204 (multiprocessor).

Most errors that can occur in the external module are isolated from <var class="product">Model 204</var>. However, it is still possible for programming errors in external modules to corrupt or overwrite storage belonging to <var class="product">Model 204</var>. A programming error in your external module could result in data corruption, abends, or incorrect results in the external module or in Model 204.

===Stopping an external load module===

Authorized users can stop an external module in the following ways; by executing:
<ul>
<li><var>[[#stop|External Stop]]</var> statement, usage of a load module can be disabled by an authorized user. It can be enabled again by the <var>[[#start|External Start]]</var> statement.</li>

<li><var>[[#delete|External Delete]]</var> statement, a load module can be removed from storage by an authorized user. An <var>External Delete</var> statement must not be used for Language Environment (LE) modules, because z/OS does not support the use of DELETE of Language Environment main programs and an abend can result.</li>
</ul>

===ECF statistics and messages===

See the table in [[Using system statistics#Statistics with descriptions|Statistics with descriptions]] for the System-final, user-logout, user-since-last, SMF-logout, and SMF-since-last statistics that relate to ECF.

===BUMP command enhanced with the FORCE option for ECF users===

Simply bumping a user that is executing an <var>External Call</var> statement does not interrupt the external module. The external module is allowed to complete — however long that takes —and then the bump takes effect.

To interrupt an external module, you must issue a <var>[[BUMP command|BUMP]]</var> command with the <var>FORCE</var> option. Or, you can continue to use the <var>External Stop</var> statement with the <var>FORCE</var> option.

If the <var>FORCE</var> option is specified on a <var>BUMP</var> command, then the users who are running an external module are interrupted. The <var>FORCE</var> option may be combined with any other <var>BUMP</var> options. When you specify the <var>FORCE</var> option, it must be the first option on the command.

====Examples====
BUMP FORCE ALL

BUMP FORCE SUBSYS MYAPSY

BUMP FORCE MODULE MYPGM

For users who are not running an external module, the presence or absence of the <var>FORCE</var> option is irrelevant. Adding the <var>FORCE</var> option affects only users who are running an external module. The <var>FORCE</var> option does not interrupt users that are in an unbumpable wait.

==ECF SOUL statements==

You must check <var>[[$Status]]</var> and <var>[[$StatusD]]</var> return codes after each ECF statement.

===External Call statement===
<dl>
<dt>Function</dt>
<dd>Calls an external module that was previously loaded using an <var>External Load</var> statement, using a call name that was previously specified in an <var>External Name</var> statement.</dd>
<dt>Privileges</dt>
<dd>
Any user</dd>
<dt>Syntax</dt>
<dd>External Call call-name [WITH image-1 [,image-2,...image-60]] 

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>call-name</th>
<td>Logical name, either a literal or %variable, of the external module to invoke.</td>
</tr>

<tr>
<th><var>WITH clause</var></th>
<td>The optional <var>WITH</var> clause specifies the images to pass as a parameter area between the SOUL program and the external module. If no parameter area is required, you can omit the <var>WITH</var> clause.</td>
</tr>

<tr>
<th nowrap>image-1,...image-60</th>
<td>Name(s) of a previously defined image(s) to pass to the external module.</td>
</tr>
</table>
</dd>
<dt>Usage</dt>
<dd>
<ul>
<li>You can specify from one to sixty images separated by commas.</li>

<li>A return code of zero does not mean that the external module performed as it was designed; it simply means that the module was successfully invoked and completed without an abend. </li>

<li>Without a parameter area, the external module cannot directly pass any data back to a SOUL program other than via its return code. It can, of course, indirectly pass data back: for example, by updating a sequential data set that the SOUL program can then inspect.</li>

<li>If Model 204 is using an external authorizer such as ACF2, RACF, or Top/Secret: The default external-authorizer profile under which a job invoked by a privileged ECF statement runs is changed in version 7.7 of Model 204. Instead of such a job running under the job's external-authorizer profile (as it did prior to 7.7), the job runs by default in 7.7 under the user's external-authorizer profile.

The default behavior can be changed by turning on the system parameter <var>[[ECPRIV parameter|ECPRIV]]</var> 4 bit. </li>
</ul></dd>
</dl>

===External Delete statement===
<dl>
<dt>Function</dt>
<dd>Removes a previously loaded external module from storage.</dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Delete module-name


Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>A literal or a %variable that is the module name of a previously loaded external module.</td></tr>
</table></dd>
<dt>Usage</dt>
<dd>Do not use the <var>External Delete</var> statement for Language Environment modules.</dd>
</dl>

===External Load statement===
<dl>
<dt>Function</dt>
<dd>Loads an external module into storage. The module, previously defined by an <var>External Module</var> statement, is loaded and is then available to all users.</dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Load module-name


Where:
<table>
<tr class="head">
<th>Argument </th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>A literal or a %variable that is the name of the external module, a PDS member name.</td>
</tr>
</table></dd>
</dl>

===External Module statement===
<dl>
<dt>Function</dt>
<dd>Defines an external module for later loading. </dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Module module-name [DDNAME=ddname]
[PARMTYPE=INPUT | OUTPUT]
[PARMSIZE=value]
[PARMMODE=[24 | 31]]
[REENTRANT | AFFINITY]
[IDCAMS]

Where:
<table>
<tr class="head">
<th>Argument </th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name </th>
<td>A literal or %variable that is the name of the external module, a PDS member name. Required.</td></tr>

<tr>
<th>ddname </th>
<td>A literal or %variable that is the DDNAME of the PDS where the load module is located. If omitted, the standard search order or //STEPLIB is used. Optional.

Note: If <var class="product">Model 204</var> is APF authorized, then this data set must also be APF authorized.
</td></tr>

<tr>
<th><var>PARMTYPE</var> </th>
<td>The parameter (image) type passed to the external module on an <var>External Call</var> statement. Optional.
<ul>
<li><var>INPUT</var> means that any changes made by the external module to the parameter are discarded. </li>

<li><var>OUTPUT</var>, the default, means that any changes are retained.</li>
</ul>
</td></tr>

<tr>
<th><var>PARMSIZE</var> </th>
<td>A literal or %variable that is the required size of the parameter (image) passed to the external module on all <var>External Call</var> statements.

If the actual parameter size does not match the required size, the <var>External Call</var> statement fails. 

If <var>PARMSIZE</var> is not specified, the parameter size is not checked. 
</td></tr>

<tr>
<th><var>PARMMODE</var></th>
<td>Where storage to hold the copy of the parameter area is allocated. Optional.
<ul>
<li>24 means allocate in 24-bit, below-the-line storage.</li>

<li>31, the default, means allocate in 31-bit, above the line storage.</li>

<li>Do not specify <code>PARMMODE=24</code> unless the module has a specific requirement for this setting.</li>
</ul></td></tr>

<tr>
<th><var>REENTRANT</var> </th>
<td>Module that can be used by more than one user at a time. This optional argument takes effect only if the module was link-edited with the REENTRANT attribute.</td>
</tr>

<tr>
<th><var>AFFINITY</var> </th>
<td>Module always runs on the same subtask. Conversely, that subtask runs only that module.</td>
</tr>

<tr>
<th><var>IDCAMS</var> </th>
<td>The module is the [https://en.wikipedia.org/wiki/IBM_mainframe_utility_programs#IDCAMS IBM IDCAMS utility]. Specifying this option causes the IDCAMS module to be invoked in such a way that, rather than reading data from the <var>SYSIN</var> DD and sending output to the <var>SYSPRINT</var> DD, data is read from and written to the user buffer (sometimes known as the Universal Buffer).

The <var>IDCAMS</var> option is available as of Model 204 7.7. For an example, see [[#IDCAMS example|IDCAMS example]], below.

Specifying this option for a module other than IDCAMS is likely to result in abends in the module when called.
</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>
<ul>
<li>You can use an <var>External Module</var> statement to define a module using either:
<ul>
<li>New name and attributes.</li>

<li>Existing name. Attributes associated with an existing name are replaced by new attributes.</li>
</ul></li>

<li>Subtask affinity, which is specified by the <var>AFFINITY</var> keyword, is required in some situations. For example, when an external module opens a data set on one call, but does not close it till a subsequent call. Subtask affinity is required because z/OS requires that you open and close a data set from the same subtask. </li>

<li>The <var>AFFINITY</var> keyword is incompatible with the <var>REENTRANT</var> keyword. A compilation error is generated, if both are specified for the same module. You specify one or the other or neither, but not both.</li>
</ul></dd>
</dl>

===External Name statement===
<dl>
<dt>Function</dt>
<dd>Use the <var>External Name</var> statement to:
<ul>
<li>Associate a logical call name with the name of a module that was previously defined by issuing an <var>External Module</var> statement</li>

<li>Remove a previously set up association. A module can have multiple call names.</li>
</ul></dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Name call-name FOR module-name

External Name call-name REMOVE

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>call-name</th>
<td>Logical name to associate with an external module. Up to 48 characters.</td>
</tr>

<tr>
<th>module-name</th>
<td>Name of a previously loaded external module.</td>
</tr>
</table></dd>
</dl>

===External Start statement===
<dl>
<dt>Function</dt>
<dd>Enables further calls to an ECF module.</dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>

<dt>Syntax</dt>
<dd>
External Start module-name

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name </th>
<td>Name of a previously loaded external module.</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>Initially a module is in the START state. You need not issue an <var>External Start</var> statement unless you want to reverse a prior <var>External Stop</var> statement.
</dd>
</dl>

===External Stop statement===
<dl>
<dt>Function</dt>
<dd>Stops further calls to an ECF module. Currently executing calls either complete or, if the FORCE option is used, abend.</dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>

<dt>Syntax</dt>
<dd>External Stop module-name [FORCE]

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>Name of a previously loaded external module.</td>
</tr>

<tr>
<th><var>FORCE</var></th>
<td>Users currently executing the specified module are bumped.</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>The following table describes how an <var>External Stop</var> statement is evaluated.
<table>
<tr class="head">
<th>When <var>External Stop</var> statement is issued </th>
<th>
Then</th>
</tr>

<tr>
<td>If no users are executing the module </td>
<td>Module is immediately marked stopped. </td>
</tr>

<tr>
<td>If one or more users are executing the module </td>
<td>Module is marked draining until the last user finishes executing the module, then it is marked stopped. </td>
</tr>

<tr>
<td>If <var>FORCE</var> was specified </td>
<td>Current users of the module are bumped.</td>
</tr>

<tr>
<td>If <var>FORCE</var> was not specified </td>
<td>Current users of the module are allowed to complete. </td>
</tr>
</table>

In all cases, subsequent attempts by any user to call the module with an <var>External Call</var> statement result in a <var>$Status</var> of 8. 
Note: Rocket Software does not recommend using the <var>FORCE</var> option, as <var class="product">Model 204</var> cannot ensure that the external module is terminated cleanly.</dd>
</dl>

==ECF return codes and $function==

All <var>EXTERNAL</var> statements set <var>$Status</var> and <var>$StatusD</var>.
<table>
<caption>ECF return codes</caption>
<tr class="head">
<th>$Status</th>
<th>$StatusD</th>
<th>Meaning</th>
</tr>

<tr>
<td align="right">0</td>
<td align="right">0</td>
<td>ECF function completed without error</td>
</tr>

<tr>
<td align="right">1</td>
<td align="right">0</td>
<td>ECF inactive</td>
</tr>

<tr>
<td align="right">2</td>
<td align="right">0</td>
<td>User not authorized for ECF function, see ECPRIV</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>Unable to obtain ACEE for setting ECF subtask security profile</td>
</tr>

<tr>
<td align="right">3</td>
<td align="right">1</td>
<td>Invalid module name</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>Invalid call name</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>Invalid DDNAME</td>
</tr>

<tr>
<td> </td>
<td align="right">4</td>
<td>Image inactive</td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>Invalid PARMSIZE</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">0</td>
<td>Call name not defined</td>
</tr>

<tr>
<td align="right">6</td>
<td align="right">0</td>
<td>Module not defined</td>
</tr>

<tr>
<td align="right">7</td>
<td align="right">0</td>
<td>Module not loaded</td>
</tr>

<tr>
<td align="right">8</td>
<td align="right">0</td>
<td>Module unavailable (draining or stopped)</td>
</tr>

<tr>
<td align="right">10</td>
<td align="right">0</td>
<td>Module not deleted</td>
</tr>

<tr>
<td align="right">20</td>
<td> </td>
<td>System busy; timed out</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>Module unavailable</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>No subtask available</td>
</tr>

<tr>
<td align="right">30</td>
<td> </td>
<td>Load or delete failed</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>DDNAME not present</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>DDNAME open failed</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>DDNAME close failed</td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>Load or delete failed; see the <var>[[$EcfStat]]</var> function.
</td>
</tr>

<tr>
<td> </td>
<td align="right">6</td>
<td>Internal ECF abend; see the <var>$EcfStat</var> function page.</td>
</tr>

<tr>
<td> </td>
<td align="right">7</td>
<td>Internal ECF ABEND; load or delete subtask terminated by the operating system.</td>
</tr>

<tr>
<td align="right">40</td>
<td align="right">0</td>
<td>Module failed</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>Module gave nonzero return code; see the <var>$EcfStat</var> function page.
</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>Module abend; see the <var>$EcfStat</var> function page.
</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>Insufficient memory available to allocate a buffer for the parameter area</td>
</tr>

<tr>
<td> </td>
<td align="right">4</td>
<td>Actual parameter size is not equal to <var>PARMSIZE</var></td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>When the parameter area, as updated by the external module, was being copied back to the original image(s), ECF detected that the size of one of the images had been changed. This status can occur only if an image contains a variable array whose size is changed by the external module.</td>
</tr>

<tr>
<td> </td>
<td align="right">6</td>
<td>ECF subtask terminated by the operating system</td>
</tr>

<tr>
<td align="right">50</td>
<td align="right">0</td>
<td>ECF internal table full</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>ECF ECMODS table full; increase <var>ECMODS</var> User 0 parameter</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>ECF ECNAMES table full; increase <var>ECNAMES</var> User 0 parameter</td>
</tr>
</table>

===$EcfStat function===

The <var>[[$EcfStat]]</var> function returns the detailed completion code from the previous <var>EXTERNAL</var> statement.


==ECF User 0 parameters==

The following User 0 parameters are used by ECF.

A system manager can reset only the <var>ECWAIT</var> parameter; the other ECF parameters cannot be reset.
<table>
<tr class="head">
<th>User 0 parameter </th>
<th>Returns...</th>
</tr>

<tr>
<td><var>[[ECISUBS parameter|ECISUBS]]</var> </td>
<td>Subtasks for running external modules initially attached</td>
</tr>

<tr>
<td><var>[[ECMODS parameter|ECMODS]]</var> </td>
<td>External modules to load</td>
</tr>

<tr>
<td><var>[[ECMSUBS parameter|ECMSUBS]]</var> </td>
<td>Number of ECF subtasks for running modules</td>
</tr>

<tr>
<td><var>[[ECNAMES parameter|ECNAMES]]</var> </td>
<td>Number of external call names</td>
</tr>

<tr>
<td><var>[[ECPRIV parameter|ECPRIV]]</var> </td>
<td>ECF privileges</td>
</tr>

<tr>
<td><var>[[ECPSIZE parameter|ECPSIZE]]</var> </td>
<td>Size of largest image used by ECF</td>
</tr>

<tr>
<td><var>[[ECWAIT parameter|ECWAIT]]</var> </td>
<td>ECF wait time</td>
</tr>

<tr>
<td><var>[[ECWAIT parameter|ECMAXCPU]]</var> </td>
<td>Maximum CPU time in seconds allowed for an external call of an ECF module, else 0 for no limit. If limit is exceeded, the ECF module a user 099 ABEND is reflected to the ECF task. This support added by 79Z087.</td>
</tr>
</table>

==Subtask and load module management==

Some z/OS overhead accrues in loading an external module into storage and attaching a z/OS subtask under which it runs. ECF avoids incurring this cost for every <var>External Call</var> statement by managing the load modules and subtasks as described in the following sections.

===Subtasks assignment===

At system startup, the following subtasks are started:
<ul>
<li>One subtask for loading and deleting modules</li>

<li>One or more subtasks, specified by the <var>ECISUBS</var> parameter, for executing external modules</li>
</ul>

When a user issues an <var>External Call</var> statement, an unused ECF subtask is selected on which to run the external module, up to the limit of <var>ECMSUBS</var>. Users unable to get a subtask enter a wait of up to <var>ECWAIT</var> milliseconds for a subtask to become available. When an in-use ECF subtask becomes available, because the module that was running under it ends, it is assigned to a user waiting for a subtask. If a user's wait time expires before a subtask is available, a no-subtask-available failure is returned.

===Subtask affinity===

Normally, when an external module is called via the <var>External Call</var> statement, ECF selects any free subtask on which to execute the module. Although this is appropriate for most external modules, some modules might need to always be executed on the same subtask. This is known as subtask affinity. Subtask affinity for a module is specified by the <var>AFFINITY</var> option on the <var>External Module</var> statement. The <var>AFFINITY</var> option is incompatible with the <var>REENTRANT</var> option.
<ul>
<li>If the <var>AFFINITY</var> option is not specified, the module does not have subtask affinity. This is the default. </li>

<li>If the <var>AFFINITY</var> option is specified, the module has subtask affinity. </li>
</ul>

When the first <var>External Call</var> of the module is executed, a dedicated subtask for the module is attached. A two-way association between the module and the subtask is established. That module will run on only that subtask, not on any other subtask. That subtask is used to run only that module, not any other module.

If a module has subtask affinity, and the dedicated subtask for that module is abnormally terminated for any reason, the previous dedicated subtask is detached, and a new dedicated subtask for the module is attached. A subtask could be abnormally terminated if the module it was running has an abend, or the user running the module is bumped. Therefore, specifying <var>AFFINITY</var> does not guarantee that the same subtask is always used for that module for the duration of a <var class="product">Model 204</var> Online.

If you use modules with subtask affinity, ensure that <var>ECISUBS</var> and <var>ECMSUBS</var> are appropriately set. In particular, <var>ECISUBS</var> and <var>ECMSUBS</var> must be greater than or equal to the number of modules with subtask affinity.
<ul>
<li>The <var>ECISUBS</var> parameter specifies the number of subtasks attached during system initialization. These subtasks are never used for modules with subtask affinity; the first <var>External Call</var> of a module with subtask affinity always results in a new subtask being attached (subject to <var>ECMSUBS</var>). </li>

<li>The <var>ECMSUBS</var> parameter specifies the maximum number of ECF subtasks used to run modules. The number of subtasks used for modules with subtask affinity plus the number of subtasks used for modules without subtask affinity will be a maximum of <var>ECMSUBS</var>.</li>
</ul>

===Load modules===

An external module is usually loaded into storage just once. The exception is when an <var>External Load</var> statement, possibly preceded by an <var>External Delete</var> statement, is used to reload a previously-loaded module.

Normally, one <var class="product">Model 204</var> user at a time is allowed to issue an <var>External Call</var> statement for the module. Other users who attempt to call the module while it is in use, enter a wait-state of up to <var>ECWAIT</var> milliseconds for the module to become available. When a module is freed, because the current execution of it ends, it is assigned to one of the users waiting for it. If a user's wait time expires before the module is assigned, a module-in-use failure is returned. 

If a load module was link-edited with the REENTRANT (also written, RENT) attribute, and if the <var>External Module</var> statement that defined the module characteristics specified the <var>REENTRANT</var> option, then multiple <var class="product">Model 204</var> users are allowed to simultaneously issue an <var>External Call</var> statement for the module — subject to subtask availability.

===Fulfillment order===

An <var>External Call</var> statement can invoke an external module only if both an ECF subtask is free, and for a serially reusable module, if the module is not in use by another user. The check that the module is not in use by another user is done before the allocation of a subtask so that the most restrictive condition is checked first.

==Restrictions and cautions==

The following restrictions and cautions apply to the use of ECF:
<ul>
<li>ECF loads an external module only once, when the <var>External Load</var> statement is issued. Thereafter, every user who issues an <var>External Call</var> statement for that module uses the same copy of the module. Therefore, you must write your module to initialize itself properly on every call.</li>

<li>ECF passes the copy of the parameter area to the external module using standard z/OS linkage conventions. Your external module must support these conventions to receive the parameters.</li>

<li>ECF does not provide any special initialization of the environment when you issue an <var>External Call</var> statement; it merely branches to the in-memory copy of the module. Therefore, your module must perform any required initialization and termination of its run-time environment. In particular, this means that an external module, written in any language, should be written as a main routine and not a subroutine.</li>

<li>Only one copy of a load module can be in memory at a time. This is a z/OS restriction.</li>

<li>Externally called modules must be <code>AMODE(31)</code> and either <code>RMODE(ANY)</code> or <code>RMODE(31)</code>.</li>

<li>Externally called modules must not attempt to retain any context information from one call to another. You must write the modules so that each call executes independently of any other.
</li>

<li>For efficiency purposes, ECF does not use z/OS to maintain the usage counts or status information for load modules. Control is passed by direct branch rather than use of the z/OS ATTACH, LINK, or XCTL macros. Therefore, one external module must not attempt to load or attach another external module, or attempt to reference code or data in another external module.</li>

<li>The definition of the parameter area in <var class="product">Model 204</var> — the image definition — must agree with the definition of the parameter area in the external module (in a COBOL program, the LINKAGE SECTION). If they do not agree, it is possible for the module to modify the wrong storage.

To prevent this, <var class="product">Model 204</var> checks that the external module put its results in only the assigned area — not somewhere else. <var class="product">Model 204</var> checks the area immediately past the end of the assigned area. If the unassigned area was used, <var class="product">Model 204</var> displays the following message and restarts the user:
M204.2563: MODULE=name RETURNED MORE THAN length BYTES
</li>
</ul>

==Tracking ECF==

===Wait types for ECF===

See the table of codes in the [[ONLINE_monitoring#Wait_type_values| listing of wait types]] that includes the External Call Facility, wait types 43 through 46.

===ECF statistics===

The following statistics help you track the External Call Facility. See [[Using system statistics#Statistics with descriptions|Statistics with descriptions]] for the position in the system-final, user-logout, user-since-last, SMF-logout, and/or SMF-since-last journal record layout as they apply. 
<ul>
<li>ECCALL</li>

<li>ECCNCT</li>

<li>ECCTOUT</li>

<li>ECCWAITM</li>

<li>ECCWAITS</li>

<li>ECDELETE</li>

<li>ECLOAD</li>

<li>ECMODMAX</li>

<li>ECNAMMAX</li>

<li>ECTSKMAX</li>

<li>ECTWAITM</li>

<li>ECTWAITS</li>
</ul>

Statistics include only <var>External Call</var> statements that actually called a module — even if the module subsequently abended. ECF statistics do not include <var>External Call</var> statements with parameter errors or those that timed out trying to get a module or subtask.

==ECF examples==

This section illustrates, in various languages, how to write, compile, link and invoke an external module that adds two numbers together and returns the sum. For clarity, the sample code omits error handling, other standard elements, and some JCL elements.

===COBOL sample 1===

This example uses the Language Environment enabled compiler, IBM COBOL FOR z/OS AND z/VM.
COBOL program
//COBSAMP EXEC PGM=IGYCRCTL,PARM=(NOSEQ,RENT)
//SYSLIN DD DSN=YOUR.OBJLIB(COBSAMP),DISP=SHR
//SYSIN DD *
IDENTIFICATION DIVISION.
PROGRAM-ID. COBSAMP.
DATA DIVISION.
LINKAGE SECTION.
01 M204-PARMS.
03 NUMBER-ONE PIC S9(7) COMP-3.
03 NUMBER-TWO PIC S9(9) BINARY.
03 NUMBER-SUM PIC S9(9) BINARY.
PROCEDURE DIVISION USING M204-PARMS.
COMPUTE NUMBER-SUM EQUAL NUMBER-ONE + NUMBER-TWO
MOVE ZERO TO RETURN-CODE
GOBACK.

Language Environment options
//ASMUOPT EXEC PGM=ASMA90,PARM='NOXREF'
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
// DD DSN=CEE.SCEEMAC,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSN=YOUR.OBJLIB(CEEUOPT),DISP=SHR
//SYSIN DD *
CEEUOPT CSECT
CEEUOPT AMODE ANY
CEEUOPT RMODE ANY
PRINT ON,NOGEN
CEEXOPT
ABTERMENC=(ABEND),
RTEREUS=(ON)
END

Linkedit
//LINK EXEC PGM=IEWL,PARM='LIST,MAP'
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DSN=CEE.SCEELKED,DISP=SHR
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSLIN DD *
INCLUDE OBJLIB(CEEUOPT)
INCLUDE OBJLIB(COBSAMP)
NAME COBSAMP(R)

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR
// DD DSN=CEE.SCEERUN,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.PACKED IS PACKED LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE COBSAMP
EXTERNAL LOAD COBSAMP
EXTERNAL NAME MOD_COBSAMP FOR COBSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.PACKED = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_COBSAMP WITH PARMS
PRINT %PARMS:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END

Comments
<table>
<tr class="head">
<th>COBOL </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
PIC S9(7) COMP-3
</td>
<td>
PACKED LEN 4
</td>
</tr>

<tr>
<td>
PIC S9(9) BINARY
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>
<ul>
<li>The Language Environment option <code>ABTERMENC=(ABEND)</code> must be specified.</li>

<li>Specify the Language Environment option <code>RTEREUS=(ON)</code> and code <var>GOBACK</var> instead of <var>STOP RUN</var>, as illustrated, to make the runtime environment reusable and to improve performance.</li>

<li>Setting Language Environment options is described in IBM Manual SC28-1939 <var class="book">Language Environment for z/OS & z/VM Programing Guide</var>. In the code in the "Calling from SOUL" section in the example above, Language Environment options are set by linking CEEUOPT with the COBOL module. Other methods are also available; check with your site's Language Environment administrator to determine the appropriate method to use.</li>
</ul>

===COBOL sample 2===

This example illustrates the use of multiple images using the Language Environment enabled compiler, IBM COBOL FOR z/OS AND z/VM. 
Note: Ordinarily, multiple images are only used if the parameters to be passed cannot fit into a single image. Images are limited in size to 32767 bytes.
COBOL program
IDENTIFICATION DIVISION.
PROGRAM-ID. COBSAM2.
DATA DIVISION.
LINKAGE SECTION.
01 M204-PARMS1.
03 NUMBER-ONE PIC S9(7) COMP-3.
01 M204-PARMS2.
03 NUMBER-TWO PIC S9(9) BINARY.
01 M204-PARMS3.
03 NUMBER-SUM PIC S9(9) BINARY.
PROCEDURE DIVISION USING M204-PARMS1, M204-PARMS2, M204-PARMS3.
COMPUTE NUMBER-SUM EQUAL NUMBER-ONE + NUMBER-TWO
MOVE ZERO TO RETURN-CODE
GOBACK.

Calling from SOUL
BEGIN
IMAGE PARMS1
NUMBER.ONE.PACKED IS PACKED LEN 4
END IMAGE
IMAGE PARMS2
NUMBER.TWO.BINARY IS BINARY LEN 4
END IMAGE
IMAGE PARMS3
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE COBSAM2
EXTERNAL LOAD COBSAM2
EXTERNAL NAME MOD_COBSAM2 FOR COBSAM2

PREPARE IMAGE PARMS1
PREPARE IMAGE PARMS2
PREPARE IMAGE PARMS3
%PARMS1:NUMBER.ONE.PACKED = 1
%PARMS2:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_COBSAM2 WITH PARMS1, PARMS2, PARMS3
PRINT %PARMS1:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS2:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS3:NUMBER.SUM.BINARY
END


===SAS/C sample===

This example uses the SAS/C compiler, not the IBM C compiler.
SAS/C program
//C EXEC PGM=LC370B
//STEPLIB DD DSN=SASC.LOAD,DISP=SHR
//SYSLIB DD DSN=SASC.MACLIBC,DISP=SHR
//SYSLIN DD DSN=YOUR.OBJLIB(SASCSAMP),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
typedef struct PARMAREA {
int A;
int B;
int C;
} parmarea;

int main(int argc, char **argv) {
parmarea *pptr;
if (argc != 2) {
/* the parameter list was not in OS format */
return 1000;
}
pptr = (parmarea *) argv[1];
pptr->C = pptr->A + pptr->B;
return 0;
}

Linkedit
//LC EXEC PGM=IEWL,PARM='AMODE(31),RMODE(ANY)'
//SYSLIB DD DSN=SASC.STDLIB,DISP=SHR
// DD DSN=SASC.BASELIB,DISP=SHR
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD *
INCLUDE OBJLIB(SASCSAMP)
ENTRY $MAINC
NAME SASCSAMP(R)
//*

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.BINARY IS BINARY LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE SASCSAMP
EXTERNAL LOAD SASCSAMP
EXTERNAL NAME MOD_SASCSAMP FOR SASCSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.BINARY = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_SASCSAMP WITH PARMS
PRINT %PARMS:NUMBER.ONE.BINARY WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END

Comments
<table>
<tr class="head">
<th>SAS/C </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
int
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>
<ul>
<li>The SAS/C program must be coded as a main program, not a subroutine.</li>

<li>To enable SAS/C to accept parameters in standard OS format, the entry point must be defined as <code>$MAINC</code> and the parameters handled as illustrated. This technique is described in the <var class="book">SAS/C Compiler and Library User's Guide</var>.</li>
</ul>

===Assembler sample===

This example uses the non-Language Environment assembler.
Assembler program
//ASMSAMP EXEC PGM=ASMA90
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
//SYSLIN DD DSN=YOUR.OBJLIB(ASMSAMP),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
ASMSAMP CSECT

ASMSAMP AMODE 31
ASMSAMP RMODE ANY
USING *,15
L 1,0(1) GET ADDRESS OF IMAGE COPY
XC WORKAREA,WORKAREA CLEAR WORK AREA
MVC WORKAREA+4(4),0(1) GET FIRST NUMBER (PACKED)
CVB 0,WORKAREA GET FIRST NUMBER (BINARY)
A 0,4(1) ADD SECOND NUMBER (BINARY)
ST 0,8(1) STORE SUM (BINARY)
XR 15,15 ZERO RETURN CODE
BR 14 RETURN
DS 0D
WORKAREA DS PL8 WORKING STORAGE
END ASMSAMP

Linkedit
//LASM EXEC PGM=IEWL
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD *
INCLUDE OBJLIB(ASMSAMP)
NAME ASMSAMP(R)

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.PACKED IS PACKED LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE ASMSAMP
EXTERNAL LOAD ASMSAMP
EXTERNAL NAME MOD_ASMSAMP FOR ASMSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.PACKED = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_ASMSAMP WITH PARMS
CALL CHECK.STATUS
PRINT %PARMS:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END


Comments
<table>
<tr class="head">
<th>Assembler </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
DS PL4
</td>
<td>
PACKED LEN 4
</td>
</tr>

<tr>
<td>
DS F
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>


===IDCAMS example===

This example uses the <var>IDCAMS</var> option (available as of Model 204 7.7) on the ECF <var>Module</var> statement to have IDCAMS input and output go from/to the user buffer.

====Module definition====
The following <var>External</var> statements make IDCAMS available:
b
external module idcams idcams
external load idcams
external name idcams for idcams
end


When <var>IDCAMS</var> is invoked by <var>External Call</var>, the user's [[Universal Buffer]] must contain the input lines to be passed to <code>SYSIN</code>, separated by EBCDIC linefeed characters (X'25'). The output lines from <var>IDCAMS</var> are appended to the Universal Buffer, also separated by new lines.

Before calling <var>IDCAMS</var>, the Universal Buffer must be allocated to a length sufficient to hold all of the input lines and all of the expected output lines. If the buffer is too small, output is truncated. While it is possible to calculate the optimum Universal Buffer length on each invocation, it is better to do the following to minimize storage fragmentation:
<ul>
<li>Use the same value for all invocations.</li>

<li>Use a multiple of 8K. </li>
</ul>

====Return codes====
The <var>IDCAMS</var> interface can return one of the following return codes:
<table class="thJustBold">
<tr><th>20</th>
<td>Universal Buffer was overflowed, output truncated.</td></tr>

<tr><th>24</th>
<td>Minimum outspace (2,000 bytes) not available in Universal Buffer.</td></tr>

<tr><th>28</th>
<td>No input data in Universal Buffer.</td></tr>

<tr><th>Else</th>
<td>The return code is from the IDCAMS program.</td></tr>
</table>

====SOUL code====
b
%idcams.in is longstring
%idcams.out is longstring
%lines.in is object stringlist
%lines.out is object stringlist

%hlq is string len 8
%options is string len 32
%input.len is float
%rc is float

%hlq = 'DRAKE'
%options = 'VOLUMES'

* Prepare IDCAMS input lines in stringlist. Note that that the
* TEXT TO statement supports expressions allowing %variables and
* functions to be used as the trivial example shows.
%lines.in = new
Text nocont To %lines.in
{} LISTCAT -
LEVEL({%hlq}) -
{%options}
End Text

* Note: the null expression {} in front of LISTCAT is to force
* indentation, since IDCAMS commands cannnot begin in column 1.

* Convert the stringlist to a longstring with EBCDIC new line
* delimiters at the end of each line. This is needed to use the
* Model 204 Universal Buffer feature, which only understands
* byte strings.
%idcams.in = %lines.in:CreateLines

* Force Universal Buffer allocation of sufficient size
modify buffer size=65536 nopreserve clear

* Prime Universal Buffer with input for IDCAMS, save its length
%input.len = $Lstr_Set_UserBuffer(%idcams.in)

* Call the IDCAMS wrapper, appending output to Universal Buffer
external call idcams
Printtext $status={$STATUS}, $STATUSD={$STATUSD}, $ECFSTAT={$ECFSTAT}
%rc = +$substr($ecfstat,4,5)
Printtext In simpler terms, the IDCAMS return code was {%rc}.

* Retrieve output data from Universal Buffer (too bad there isn't
* a starting offset parameter) and parse lines to stringLlist.
%idcams.out = $lstr_substr($lstr_Get_UserBuffer,%input.len+1)
%lines.out = new
%lines.out:ParseLines(%idcams.out)

Printtext IDCAMS passed the following {%lines.in:count} lines:
%lines.in:print

Printtext Which produced {%lines.out:count} lines of output:
%lines.out:print
end


[[Category:System management]]
[[Category:System-level capabilities of Model 204]]

External Call Facility

2025-12-28T15:19:14Z

Gary: /* ECF User 0 parameters */

==Overview==

The External Call Facility (ECF) is a method for programs written in [[SOUL]] to invoke external, non-<var class="product">Model 204</var> modules, such as non-IFAM COBOL modules. Data can be passed between <var class="product">Model 204</var> and external modules. External modules can open non-<var class="product">Model 204</var> data sets, read or write to them, and close them. In addition, multiple modules can be called multiple times in a single run. 

ECF is available only under z/OS.

==Working with ECF==

===Loading an external module===

Each external module that is called using ECF is dynamically loaded once into memory from a nominated load library or from //STEPLIB. If <var class="product">Model 204</var> is APF authorized, then any nominated load library identified for use by ECF must also be APF authorized. Otherwise, the <var>External Load</var> statement will fail with:
COMPLETION CODE=S306 REASON CODE=000C.


The load is done by an authorized user executing the <var>[[#load|External Load]]</var> statement; for example, by User 0 during startup. The load is issued from a dedicated ECF subtask that is used exclusively for module loads and deletes.

After an external module is loaded, a call-name of up to 48 characters is associated with it. An association is set up by an authorized user executing the <var>[[#name|External Name]]</var> statement; typically by User 0 during startup. More than one call name can be associated with the same load module name.

Callers of the external module always refer to the call (logical) name rather than the load module (physical) name. Thus, if a load module name or location changes, only the setup statements need to be changed; no application code changes are required.

===Calling an external module===

A previously loaded external module is called by a user executing the <var>[[#call|External Call]]</var> statement. This invokes a separate ECF subtask to run the external module, and causes the user to enter a swappable, bumpable wait state. When the external module completes, control returns to the user. There are no restrictions on the length of time the external module can run.

Data is passed between <var class="product">Model 204</var> and an external module via a <var class="product">Model 204</var> [[Images|image]]. A copy of the image is made when the module is called, so that the caller need not remain in the server while the external module runs. The external module can modify the copy of the image. The modified image is returned to the caller, unless the <var>[[#module|External Module]]</var> statement specified <code>PARMTYPE=INPUT</code>.

===Avoiding data corruption and incorrect results===

External modules must not access any data set that <var class="product">Model 204</var> or any other external module has already opened. 
Attention: Failure to observe this could result in data corruption or abends, either in the external module or Model 204.

External modules invoked using ECF run under separate z/OS subtasks in the same address space as the <var class="product">Model 204</var> Online that invoked the module. This means that external modules run in parallel with <var class="product">Model 204</var> (and each other), even if you do not use MP/204 (multiprocessor).

Most errors that can occur in the external module are isolated from <var class="product">Model 204</var>. However, it is still possible for programming errors in external modules to corrupt or overwrite storage belonging to <var class="product">Model 204</var>. A programming error in your external module could result in data corruption, abends, or incorrect results in the external module or in Model 204.

===Stopping an external load module===

Authorized users can stop an external module in the following ways; by executing:
<ul>
<li><var>[[#stop|External Stop]]</var> statement, usage of a load module can be disabled by an authorized user. It can be enabled again by the <var>[[#start|External Start]]</var> statement.</li>

<li><var>[[#delete|External Delete]]</var> statement, a load module can be removed from storage by an authorized user. An <var>External Delete</var> statement must not be used for Language Environment (LE) modules, because z/OS does not support the use of DELETE of Language Environment main programs and an abend can result.</li>
</ul>

===ECF statistics and messages===

See the table in [[Using system statistics#Statistics with descriptions|Statistics with descriptions]] for the System-final, user-logout, user-since-last, SMF-logout, and SMF-since-last statistics that relate to ECF.

===BUMP command enhanced with the FORCE option for ECF users===

Simply bumping a user that is executing an <var>External Call</var> statement does not interrupt the external module. The external module is allowed to complete — however long that takes —and then the bump takes effect.

To interrupt an external module, you must issue a <var>[[BUMP command|BUMP]]</var> command with the <var>FORCE</var> option. Or, you can continue to use the <var>External Stop</var> statement with the <var>FORCE</var> option.

If the <var>FORCE</var> option is specified on a <var>BUMP</var> command, then the users who are running an external module are interrupted. The <var>FORCE</var> option may be combined with any other <var>BUMP</var> options. When you specify the <var>FORCE</var> option, it must be the first option on the command.

====Examples====
BUMP FORCE ALL

BUMP FORCE SUBSYS MYAPSY

BUMP FORCE MODULE MYPGM

For users who are not running an external module, the presence or absence of the <var>FORCE</var> option is irrelevant. Adding the <var>FORCE</var> option affects only users who are running an external module. The <var>FORCE</var> option does not interrupt users that are in an unbumpable wait.

==ECF SOUL statements==

You must check <var>[[$Status]]</var> and <var>[[$StatusD]]</var> return codes after each ECF statement.

===External Call statement===
<dl>
<dt>Function</dt>
<dd>Calls an external module that was previously loaded using an <var>External Load</var> statement, using a call name that was previously specified in an <var>External Name</var> statement.</dd>
<dt>Privileges</dt>
<dd>
Any user</dd>
<dt>Syntax</dt>
<dd>External Call call-name [WITH image-1 [,image-2,...image-60]] 

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>call-name</th>
<td>Logical name, either a literal or %variable, of the external module to invoke.</td>
</tr>

<tr>
<th><var>WITH clause</var></th>
<td>The optional <var>WITH</var> clause specifies the images to pass as a parameter area between the SOUL program and the external module. If no parameter area is required, you can omit the <var>WITH</var> clause.</td>
</tr>

<tr>
<th nowrap>image-1,...image-60</th>
<td>Name(s) of a previously defined image(s) to pass to the external module.</td>
</tr>
</table>
</dd>
<dt>Usage</dt>
<dd>
<ul>
<li>You can specify from one to sixty images separated by commas.</li>

<li>A return code of zero does not mean that the external module performed as it was designed; it simply means that the module was successfully invoked and completed without an abend. </li>

<li>Without a parameter area, the external module cannot directly pass any data back to a SOUL program other than via its return code. It can, of course, indirectly pass data back: for example, by updating a sequential data set that the SOUL program can then inspect.</li>

<li>If Model 204 is using an external authorizer such as ACF2, RACF, or Top/Secret: The default external-authorizer profile under which a job invoked by a privileged ECF statement runs is changed in version 7.7 of Model 204. Instead of such a job running under the job's external-authorizer profile (as it did prior to 7.7), the job runs by default in 7.7 under the user's external-authorizer profile.

The default behavior can be changed by turning on the system parameter <var>[[ECPRIV parameter|ECPRIV]]</var> 4 bit. </li>
</ul></dd>
</dl>

===External Delete statement===
<dl>
<dt>Function</dt>
<dd>Removes a previously loaded external module from storage.</dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Delete module-name


Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>A literal or a %variable that is the module name of a previously loaded external module.</td></tr>
</table></dd>
<dt>Usage</dt>
<dd>Do not use the <var>External Delete</var> statement for Language Environment modules.</dd>
</dl>

===External Load statement===
<dl>
<dt>Function</dt>
<dd>Loads an external module into storage. The module, previously defined by an <var>External Module</var> statement, is loaded and is then available to all users.</dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Load module-name


Where:
<table>
<tr class="head">
<th>Argument </th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>A literal or a %variable that is the name of the external module, a PDS member name.</td>
</tr>
</table></dd>
</dl>

===External Module statement===
<dl>
<dt>Function</dt>
<dd>Defines an external module for later loading. </dd>
<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Module module-name [DDNAME=ddname]
[PARMTYPE=INPUT | OUTPUT]
[PARMSIZE=value]
[PARMMODE=[24 | 31]]
[REENTRANT | AFFINITY]
[IDCAMS]

Where:
<table>
<tr class="head">
<th>Argument </th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name </th>
<td>A literal or %variable that is the name of the external module, a PDS member name. Required.</td></tr>

<tr>
<th>ddname </th>
<td>A literal or %variable that is the DDNAME of the PDS where the load module is located. If omitted, the standard search order or //STEPLIB is used. Optional.

Note: If <var class="product">Model 204</var> is APF authorized, then this data set must also be APF authorized.
</td></tr>

<tr>
<th><var>PARMTYPE</var> </th>
<td>The parameter (image) type passed to the external module on an <var>External Call</var> statement. Optional.
<ul>
<li><var>INPUT</var> means that any changes made by the external module to the parameter are discarded. </li>

<li><var>OUTPUT</var>, the default, means that any changes are retained.</li>
</ul>
</td></tr>

<tr>
<th><var>PARMSIZE</var> </th>
<td>A literal or %variable that is the required size of the parameter (image) passed to the external module on all <var>External Call</var> statements.

If the actual parameter size does not match the required size, the <var>External Call</var> statement fails. 

If <var>PARMSIZE</var> is not specified, the parameter size is not checked. 
</td></tr>

<tr>
<th><var>PARMMODE</var></th>
<td>Where storage to hold the copy of the parameter area is allocated. Optional.
<ul>
<li>24 means allocate in 24-bit, below-the-line storage.</li>

<li>31, the default, means allocate in 31-bit, above the line storage.</li>

<li>Do not specify <code>PARMMODE=24</code> unless the module has a specific requirement for this setting.</li>
</ul></td></tr>

<tr>
<th><var>REENTRANT</var> </th>
<td>Module that can be used by more than one user at a time. This optional argument takes effect only if the module was link-edited with the REENTRANT attribute.</td>
</tr>

<tr>
<th><var>AFFINITY</var> </th>
<td>Module always runs on the same subtask. Conversely, that subtask runs only that module.</td>
</tr>

<tr>
<th><var>IDCAMS</var> </th>
<td>The module is the [https://en.wikipedia.org/wiki/IBM_mainframe_utility_programs#IDCAMS IBM IDCAMS utility]. Specifying this option causes the IDCAMS module to be invoked in such a way that, rather than reading data from the <var>SYSIN</var> DD and sending output to the <var>SYSPRINT</var> DD, data is read from and written to the user buffer (sometimes known as the Universal Buffer).

The <var>IDCAMS</var> option is available as of Model 204 7.7. For an example, see [[#IDCAMS example|IDCAMS example]], below.

Specifying this option for a module other than IDCAMS is likely to result in abends in the module when called.
</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>
<ul>
<li>You can use an <var>External Module</var> statement to define a module using either:
<ul>
<li>New name and attributes.</li>

<li>Existing name. Attributes associated with an existing name are replaced by new attributes.</li>
</ul></li>

<li>Subtask affinity, which is specified by the <var>AFFINITY</var> keyword, is required in some situations. For example, when an external module opens a data set on one call, but does not close it till a subsequent call. Subtask affinity is required because z/OS requires that you open and close a data set from the same subtask. </li>

<li>The <var>AFFINITY</var> keyword is incompatible with the <var>REENTRANT</var> keyword. A compilation error is generated, if both are specified for the same module. You specify one or the other or neither, but not both.</li>
</ul></dd>
</dl>

===External Name statement===
<dl>
<dt>Function</dt>
<dd>Use the <var>External Name</var> statement to:
<ul>
<li>Associate a logical call name with the name of a module that was previously defined by issuing an <var>External Module</var> statement</li>

<li>Remove a previously set up association. A module can have multiple call names.</li>
</ul></dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>
<dt>Syntax</dt>
<dd>
External Name call-name FOR module-name

External Name call-name REMOVE

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>call-name</th>
<td>Logical name to associate with an external module. Up to 48 characters.</td>
</tr>

<tr>
<th>module-name</th>
<td>Name of a previously loaded external module.</td>
</tr>
</table></dd>
</dl>

===External Start statement===
<dl>
<dt>Function</dt>
<dd>Enables further calls to an ECF module.</dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>

<dt>Syntax</dt>
<dd>
External Start module-name

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name </th>
<td>Name of a previously loaded external module.</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>Initially a module is in the START state. You need not issue an <var>External Start</var> statement unless you want to reverse a prior <var>External Stop</var> statement.
</dd>
</dl>

===External Stop statement===
<dl>
<dt>Function</dt>
<dd>Stops further calls to an ECF module. Currently executing calls either complete or, if the FORCE option is used, abend.</dd>

<dt>Privileges</dt>
<dd>System manager or User 0</dd>

<dt>Syntax</dt>
<dd>External Stop module-name [FORCE]

Where:
<table>
<tr class="head">
<th>Argument</th>
<th>Specifies...</th>
</tr>

<tr>
<th>module-name</th>
<td>Name of a previously loaded external module.</td>
</tr>

<tr>
<th><var>FORCE</var></th>
<td>Users currently executing the specified module are bumped.</td>
</tr>
</table></dd>

<dt>Usage</dt>
<dd>The following table describes how an <var>External Stop</var> statement is evaluated.
<table>
<tr class="head">
<th>When <var>External Stop</var> statement is issued </th>
<th>
Then</th>
</tr>

<tr>
<td>If no users are executing the module </td>
<td>Module is immediately marked stopped. </td>
</tr>

<tr>
<td>If one or more users are executing the module </td>
<td>Module is marked draining until the last user finishes executing the module, then it is marked stopped. </td>
</tr>

<tr>
<td>If <var>FORCE</var> was specified </td>
<td>Current users of the module are bumped.</td>
</tr>

<tr>
<td>If <var>FORCE</var> was not specified </td>
<td>Current users of the module are allowed to complete. </td>
</tr>
</table>

In all cases, subsequent attempts by any user to call the module with an <var>External Call</var> statement result in a <var>$Status</var> of 8. 
Note: Rocket Software does not recommend using the <var>FORCE</var> option, as <var class="product">Model 204</var> cannot ensure that the external module is terminated cleanly.</dd>
</dl>

==ECF return codes and $function==

All <var>EXTERNAL</var> statements set <var>$Status</var> and <var>$StatusD</var>.
<table>
<caption>ECF return codes</caption>
<tr class="head">
<th>$Status</th>
<th>$StatusD</th>
<th>Meaning</th>
</tr>

<tr>
<td align="right">0</td>
<td align="right">0</td>
<td>ECF function completed without error</td>
</tr>

<tr>
<td align="right">1</td>
<td align="right">0</td>
<td>ECF inactive</td>
</tr>

<tr>
<td align="right">2</td>
<td align="right">0</td>
<td>Not authorized</td>
</tr>

<tr>
<td align="right">3</td>
<td align="right">1</td>
<td>Invalid module name</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>Invalid call name</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>Invalid DDNAME</td>
</tr>

<tr>
<td> </td>
<td align="right">4</td>
<td>Image inactive</td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>Invalid PARMSIZE</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">0</td>
<td>Call name not defined</td>
</tr>

<tr>
<td align="right">6</td>
<td align="right">0</td>
<td>Module not defined</td>
</tr>

<tr>
<td align="right">7</td>
<td align="right">0</td>
<td>Module not loaded</td>
</tr>

<tr>
<td align="right">8</td>
<td align="right">0</td>
<td>Module unavailable (draining or stopped)</td>
</tr>

<tr>
<td align="right">10</td>
<td align="right">0</td>
<td>Module not deleted</td>
</tr>

<tr>
<td align="right">20</td>
<td> </td>
<td>System busy; timed out</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>Module unavailable</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>No subtask available</td>
</tr>

<tr>
<td align="right">30</td>
<td> </td>
<td>Load or delete failed</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>DDNAME not present</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>DDNAME open failed</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>DDNAME close failed</td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>Load or delete failed; see the <var>[[$EcfStat]]</var> function.
</td>
</tr>

<tr>
<td> </td>
<td align="right">6</td>
<td>Internal ECF abend; see the <var>$EcfStat</var> function page.</td>
</tr>

<tr>
<td> </td>
<td align="right">7</td>
<td>Internal ECF ABEND; load or delete subtask terminated by the operating system.</td>
</tr>

<tr>
<td align="right">40</td>
<td align="right">0</td>
<td>Module failed</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>Module gave nonzero return code; see the <var>$EcfStat</var> function page.
</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>Module abend; see the <var>$EcfStat</var> function page.
</td>
</tr>

<tr>
<td> </td>
<td align="right">3</td>
<td>Insufficient memory available to allocate a buffer for the parameter area</td>
</tr>

<tr>
<td> </td>
<td align="right">4</td>
<td>Actual parameter size is not equal to <var>PARMSIZE</var></td>
</tr>

<tr>
<td> </td>
<td align="right">5</td>
<td>When the parameter area, as updated by the external module, was being copied back to the original image(s), ECF detected that the size of one of the images had been changed. This status can occur only if an image contains a variable array whose size is changed by the external module.</td>
</tr>

<tr>
<td> </td>
<td align="right">6</td>
<td>ECF subtask terminated by the operating system</td>
</tr>

<tr>
<td align="right">50</td>
<td align="right">0</td>
<td>ECF internal table full</td>
</tr>

<tr>
<td> </td>
<td align="right">1</td>
<td>ECF ECMODS table full; increase <var>ECMODS</var> User 0 parameter</td>
</tr>

<tr>
<td> </td>
<td align="right">2</td>
<td>ECF ECNAMES table full; increase <var>ECNAMES</var> User 0 parameter</td>
</tr>
</table>

===$EcfStat function===

The <var>[[$EcfStat]]</var> function returns the detailed completion code from the previous <var>EXTERNAL</var> statement.


==ECF User 0 parameters==

The following User 0 parameters are used by ECF.

A system manager can reset only the <var>ECWAIT</var> parameter; the other ECF parameters cannot be reset.
<table>
<tr class="head">
<th>User 0 parameter </th>
<th>Returns...</th>
</tr>

<tr>
<td><var>[[ECISUBS parameter|ECISUBS]]</var> </td>
<td>Subtasks for running external modules initially attached</td>
</tr>

<tr>
<td><var>[[ECMODS parameter|ECMODS]]</var> </td>
<td>External modules to load</td>
</tr>

<tr>
<td><var>[[ECMSUBS parameter|ECMSUBS]]</var> </td>
<td>Number of ECF subtasks for running modules</td>
</tr>

<tr>
<td><var>[[ECNAMES parameter|ECNAMES]]</var> </td>
<td>Number of external call names</td>
</tr>

<tr>
<td><var>[[ECPRIV parameter|ECPRIV]]</var> </td>
<td>ECF privileges</td>
</tr>

<tr>
<td><var>[[ECPSIZE parameter|ECPSIZE]]</var> </td>
<td>Size of largest image used by ECF</td>
</tr>

<tr>
<td><var>[[ECWAIT parameter|ECWAIT]]</var> </td>
<td>ECF wait time</td>
</tr>

<tr>
<td><var>[[ECWAIT parameter|ECMAXCPU]]</var> </td>
<td>Maximum CPU time in seconds allowed for an external call of an ECF module, else 0 for no limit. If limit is exceeded, the ECF module a user 099 ABEND is reflected to the ECF task. This support added by 79Z087.</td>
</tr>
</table>

==Subtask and load module management==

Some z/OS overhead accrues in loading an external module into storage and attaching a z/OS subtask under which it runs. ECF avoids incurring this cost for every <var>External Call</var> statement by managing the load modules and subtasks as described in the following sections.

===Subtasks assignment===

At system startup, the following subtasks are started:
<ul>
<li>One subtask for loading and deleting modules</li>

<li>One or more subtasks, specified by the <var>ECISUBS</var> parameter, for executing external modules</li>
</ul>

When a user issues an <var>External Call</var> statement, an unused ECF subtask is selected on which to run the external module, up to the limit of <var>ECMSUBS</var>. Users unable to get a subtask enter a wait of up to <var>ECWAIT</var> milliseconds for a subtask to become available. When an in-use ECF subtask becomes available, because the module that was running under it ends, it is assigned to a user waiting for a subtask. If a user's wait time expires before a subtask is available, a no-subtask-available failure is returned.

===Subtask affinity===

Normally, when an external module is called via the <var>External Call</var> statement, ECF selects any free subtask on which to execute the module. Although this is appropriate for most external modules, some modules might need to always be executed on the same subtask. This is known as subtask affinity. Subtask affinity for a module is specified by the <var>AFFINITY</var> option on the <var>External Module</var> statement. The <var>AFFINITY</var> option is incompatible with the <var>REENTRANT</var> option.
<ul>
<li>If the <var>AFFINITY</var> option is not specified, the module does not have subtask affinity. This is the default. </li>

<li>If the <var>AFFINITY</var> option is specified, the module has subtask affinity. </li>
</ul>

When the first <var>External Call</var> of the module is executed, a dedicated subtask for the module is attached. A two-way association between the module and the subtask is established. That module will run on only that subtask, not on any other subtask. That subtask is used to run only that module, not any other module.

If a module has subtask affinity, and the dedicated subtask for that module is abnormally terminated for any reason, the previous dedicated subtask is detached, and a new dedicated subtask for the module is attached. A subtask could be abnormally terminated if the module it was running has an abend, or the user running the module is bumped. Therefore, specifying <var>AFFINITY</var> does not guarantee that the same subtask is always used for that module for the duration of a <var class="product">Model 204</var> Online.

If you use modules with subtask affinity, ensure that <var>ECISUBS</var> and <var>ECMSUBS</var> are appropriately set. In particular, <var>ECISUBS</var> and <var>ECMSUBS</var> must be greater than or equal to the number of modules with subtask affinity.
<ul>
<li>The <var>ECISUBS</var> parameter specifies the number of subtasks attached during system initialization. These subtasks are never used for modules with subtask affinity; the first <var>External Call</var> of a module with subtask affinity always results in a new subtask being attached (subject to <var>ECMSUBS</var>). </li>

<li>The <var>ECMSUBS</var> parameter specifies the maximum number of ECF subtasks used to run modules. The number of subtasks used for modules with subtask affinity plus the number of subtasks used for modules without subtask affinity will be a maximum of <var>ECMSUBS</var>.</li>
</ul>

===Load modules===

An external module is usually loaded into storage just once. The exception is when an <var>External Load</var> statement, possibly preceded by an <var>External Delete</var> statement, is used to reload a previously-loaded module.

Normally, one <var class="product">Model 204</var> user at a time is allowed to issue an <var>External Call</var> statement for the module. Other users who attempt to call the module while it is in use, enter a wait-state of up to <var>ECWAIT</var> milliseconds for the module to become available. When a module is freed, because the current execution of it ends, it is assigned to one of the users waiting for it. If a user's wait time expires before the module is assigned, a module-in-use failure is returned. 

If a load module was link-edited with the REENTRANT (also written, RENT) attribute, and if the <var>External Module</var> statement that defined the module characteristics specified the <var>REENTRANT</var> option, then multiple <var class="product">Model 204</var> users are allowed to simultaneously issue an <var>External Call</var> statement for the module — subject to subtask availability.

===Fulfillment order===

An <var>External Call</var> statement can invoke an external module only if both an ECF subtask is free, and for a serially reusable module, if the module is not in use by another user. The check that the module is not in use by another user is done before the allocation of a subtask so that the most restrictive condition is checked first.

==Restrictions and cautions==

The following restrictions and cautions apply to the use of ECF:
<ul>
<li>ECF loads an external module only once, when the <var>External Load</var> statement is issued. Thereafter, every user who issues an <var>External Call</var> statement for that module uses the same copy of the module. Therefore, you must write your module to initialize itself properly on every call.</li>

<li>ECF passes the copy of the parameter area to the external module using standard z/OS linkage conventions. Your external module must support these conventions to receive the parameters.</li>

<li>ECF does not provide any special initialization of the environment when you issue an <var>External Call</var> statement; it merely branches to the in-memory copy of the module. Therefore, your module must perform any required initialization and termination of its run-time environment. In particular, this means that an external module, written in any language, should be written as a main routine and not a subroutine.</li>

<li>Only one copy of a load module can be in memory at a time. This is a z/OS restriction.</li>

<li>Externally called modules must be <code>AMODE(31)</code> and either <code>RMODE(ANY)</code> or <code>RMODE(31)</code>.</li>

<li>Externally called modules must not attempt to retain any context information from one call to another. You must write the modules so that each call executes independently of any other.
</li>

<li>For efficiency purposes, ECF does not use z/OS to maintain the usage counts or status information for load modules. Control is passed by direct branch rather than use of the z/OS ATTACH, LINK, or XCTL macros. Therefore, one external module must not attempt to load or attach another external module, or attempt to reference code or data in another external module.</li>

<li>The definition of the parameter area in <var class="product">Model 204</var> — the image definition — must agree with the definition of the parameter area in the external module (in a COBOL program, the LINKAGE SECTION). If they do not agree, it is possible for the module to modify the wrong storage.

To prevent this, <var class="product">Model 204</var> checks that the external module put its results in only the assigned area — not somewhere else. <var class="product">Model 204</var> checks the area immediately past the end of the assigned area. If the unassigned area was used, <var class="product">Model 204</var> displays the following message and restarts the user:
M204.2563: MODULE=name RETURNED MORE THAN length BYTES
</li>
</ul>

==Tracking ECF==

===Wait types for ECF===

See the table of codes in the [[ONLINE_monitoring#Wait_type_values| listing of wait types]] that includes the External Call Facility, wait types 43 through 46.

===ECF statistics===

The following statistics help you track the External Call Facility. See [[Using system statistics#Statistics with descriptions|Statistics with descriptions]] for the position in the system-final, user-logout, user-since-last, SMF-logout, and/or SMF-since-last journal record layout as they apply. 
<ul>
<li>ECCALL</li>

<li>ECCNCT</li>

<li>ECCTOUT</li>

<li>ECCWAITM</li>

<li>ECCWAITS</li>

<li>ECDELETE</li>

<li>ECLOAD</li>

<li>ECMODMAX</li>

<li>ECNAMMAX</li>

<li>ECTSKMAX</li>

<li>ECTWAITM</li>

<li>ECTWAITS</li>
</ul>

Statistics include only <var>External Call</var> statements that actually called a module — even if the module subsequently abended. ECF statistics do not include <var>External Call</var> statements with parameter errors or those that timed out trying to get a module or subtask.

==ECF examples==

This section illustrates, in various languages, how to write, compile, link and invoke an external module that adds two numbers together and returns the sum. For clarity, the sample code omits error handling, other standard elements, and some JCL elements.

===COBOL sample 1===

This example uses the Language Environment enabled compiler, IBM COBOL FOR z/OS AND z/VM.
COBOL program
//COBSAMP EXEC PGM=IGYCRCTL,PARM=(NOSEQ,RENT)
//SYSLIN DD DSN=YOUR.OBJLIB(COBSAMP),DISP=SHR
//SYSIN DD *
IDENTIFICATION DIVISION.
PROGRAM-ID. COBSAMP.
DATA DIVISION.
LINKAGE SECTION.
01 M204-PARMS.
03 NUMBER-ONE PIC S9(7) COMP-3.
03 NUMBER-TWO PIC S9(9) BINARY.
03 NUMBER-SUM PIC S9(9) BINARY.
PROCEDURE DIVISION USING M204-PARMS.
COMPUTE NUMBER-SUM EQUAL NUMBER-ONE + NUMBER-TWO
MOVE ZERO TO RETURN-CODE
GOBACK.

Language Environment options
//ASMUOPT EXEC PGM=ASMA90,PARM='NOXREF'
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
// DD DSN=CEE.SCEEMAC,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD DSN=YOUR.OBJLIB(CEEUOPT),DISP=SHR
//SYSIN DD *
CEEUOPT CSECT
CEEUOPT AMODE ANY
CEEUOPT RMODE ANY
PRINT ON,NOGEN
CEEXOPT
ABTERMENC=(ABEND),
RTEREUS=(ON)
END

Linkedit
//LINK EXEC PGM=IEWL,PARM='LIST,MAP'
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DSN=CEE.SCEELKED,DISP=SHR
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSLIN DD *
INCLUDE OBJLIB(CEEUOPT)
INCLUDE OBJLIB(COBSAMP)
NAME COBSAMP(R)

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR
// DD DSN=CEE.SCEERUN,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.PACKED IS PACKED LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE COBSAMP
EXTERNAL LOAD COBSAMP
EXTERNAL NAME MOD_COBSAMP FOR COBSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.PACKED = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_COBSAMP WITH PARMS
PRINT %PARMS:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END

Comments
<table>
<tr class="head">
<th>COBOL </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
PIC S9(7) COMP-3
</td>
<td>
PACKED LEN 4
</td>
</tr>

<tr>
<td>
PIC S9(9) BINARY
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>
<ul>
<li>The Language Environment option <code>ABTERMENC=(ABEND)</code> must be specified.</li>

<li>Specify the Language Environment option <code>RTEREUS=(ON)</code> and code <var>GOBACK</var> instead of <var>STOP RUN</var>, as illustrated, to make the runtime environment reusable and to improve performance.</li>

<li>Setting Language Environment options is described in IBM Manual SC28-1939 <var class="book">Language Environment for z/OS & z/VM Programing Guide</var>. In the code in the "Calling from SOUL" section in the example above, Language Environment options are set by linking CEEUOPT with the COBOL module. Other methods are also available; check with your site's Language Environment administrator to determine the appropriate method to use.</li>
</ul>

===COBOL sample 2===

This example illustrates the use of multiple images using the Language Environment enabled compiler, IBM COBOL FOR z/OS AND z/VM. 
Note: Ordinarily, multiple images are only used if the parameters to be passed cannot fit into a single image. Images are limited in size to 32767 bytes.
COBOL program
IDENTIFICATION DIVISION.
PROGRAM-ID. COBSAM2.
DATA DIVISION.
LINKAGE SECTION.
01 M204-PARMS1.
03 NUMBER-ONE PIC S9(7) COMP-3.
01 M204-PARMS2.
03 NUMBER-TWO PIC S9(9) BINARY.
01 M204-PARMS3.
03 NUMBER-SUM PIC S9(9) BINARY.
PROCEDURE DIVISION USING M204-PARMS1, M204-PARMS2, M204-PARMS3.
COMPUTE NUMBER-SUM EQUAL NUMBER-ONE + NUMBER-TWO
MOVE ZERO TO RETURN-CODE
GOBACK.

Calling from SOUL
BEGIN
IMAGE PARMS1
NUMBER.ONE.PACKED IS PACKED LEN 4
END IMAGE
IMAGE PARMS2
NUMBER.TWO.BINARY IS BINARY LEN 4
END IMAGE
IMAGE PARMS3
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE COBSAM2
EXTERNAL LOAD COBSAM2
EXTERNAL NAME MOD_COBSAM2 FOR COBSAM2

PREPARE IMAGE PARMS1
PREPARE IMAGE PARMS2
PREPARE IMAGE PARMS3
%PARMS1:NUMBER.ONE.PACKED = 1
%PARMS2:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_COBSAM2 WITH PARMS1, PARMS2, PARMS3
PRINT %PARMS1:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS2:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS3:NUMBER.SUM.BINARY
END


===SAS/C sample===

This example uses the SAS/C compiler, not the IBM C compiler.
SAS/C program
//C EXEC PGM=LC370B
//STEPLIB DD DSN=SASC.LOAD,DISP=SHR
//SYSLIB DD DSN=SASC.MACLIBC,DISP=SHR
//SYSLIN DD DSN=YOUR.OBJLIB(SASCSAMP),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
typedef struct PARMAREA {
int A;
int B;
int C;
} parmarea;

int main(int argc, char **argv) {
parmarea *pptr;
if (argc != 2) {
/* the parameter list was not in OS format */
return 1000;
}
pptr = (parmarea *) argv[1];
pptr->C = pptr->A + pptr->B;
return 0;
}

Linkedit
//LC EXEC PGM=IEWL,PARM='AMODE(31),RMODE(ANY)'
//SYSLIB DD DSN=SASC.STDLIB,DISP=SHR
// DD DSN=SASC.BASELIB,DISP=SHR
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD *
INCLUDE OBJLIB(SASCSAMP)
ENTRY $MAINC
NAME SASCSAMP(R)
//*

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.BINARY IS BINARY LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE SASCSAMP
EXTERNAL LOAD SASCSAMP
EXTERNAL NAME MOD_SASCSAMP FOR SASCSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.BINARY = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_SASCSAMP WITH PARMS
PRINT %PARMS:NUMBER.ONE.BINARY WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END

Comments
<table>
<tr class="head">
<th>SAS/C </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
int
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>
<ul>
<li>The SAS/C program must be coded as a main program, not a subroutine.</li>

<li>To enable SAS/C to accept parameters in standard OS format, the entry point must be defined as <code>$MAINC</code> and the parameters handled as illustrated. This technique is described in the <var class="book">SAS/C Compiler and Library User's Guide</var>.</li>
</ul>

===Assembler sample===

This example uses the non-Language Environment assembler.
Assembler program
//ASMSAMP EXEC PGM=ASMA90
//SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR
//SYSLIN DD DSN=YOUR.OBJLIB(ASMSAMP),DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
ASMSAMP CSECT

ASMSAMP AMODE 31
ASMSAMP RMODE ANY
USING *,15
L 1,0(1) GET ADDRESS OF IMAGE COPY
XC WORKAREA,WORKAREA CLEAR WORK AREA
MVC WORKAREA+4(4),0(1) GET FIRST NUMBER (PACKED)
CVB 0,WORKAREA GET FIRST NUMBER (BINARY)
A 0,4(1) ADD SECOND NUMBER (BINARY)
ST 0,8(1) STORE SUM (BINARY)
XR 15,15 ZERO RETURN CODE
BR 14 RETURN
DS 0D
WORKAREA DS PL8 WORKING STORAGE
END ASMSAMP

Linkedit
//LASM EXEC PGM=IEWL
//OBJLIB DD DSN=YOUR.OBJLIB,DISP=SHR
//SYSLMOD DD DSN=YOUR.LOADLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSLIN DD *
INCLUDE OBJLIB(ASMSAMP)
NAME ASMSAMP(R)

Calling from SOUL
//ONLINE EXEC PGM=ONLINE
//STEPLIB DD DSN=M204.LOADLIB,DISP=SHR
// DD DSN=YOUR.LOADLIB,DISP=SHR

BEGIN
IMAGE PARMS
NUMBER.ONE.PACKED IS PACKED LEN 4
NUMBER.TWO.BINARY IS BINARY LEN 4
NUMBER.SUM.BINARY IS BINARY LEN 4
END IMAGE

EXTERNAL MODULE ASMSAMP
EXTERNAL LOAD ASMSAMP
EXTERNAL NAME MOD_ASMSAMP FOR ASMSAMP

PREPARE IMAGE PARMS
%PARMS:NUMBER.ONE.PACKED = 1
%PARMS:NUMBER.TWO.BINARY = 2
EXTERNAL CALL MOD_ASMSAMP WITH PARMS
CALL CHECK.STATUS
PRINT %PARMS:NUMBER.ONE.PACKED WITH ' + ' WITH -
%PARMS:NUMBER.TWO.BINARY WITH ' = ' WITH -
%PARMS:NUMBER.SUM.BINARY
END


Comments
<table>
<tr class="head">
<th>Assembler </th>
<th>Corresponds to SOUL</th>
</tr>

<tr>
<td>
DS PL4
</td>
<td>
PACKED LEN 4
</td>
</tr>

<tr>
<td>
DS F
</td>
<td>
BINARY LEN 4
</td>
</tr>
</table>


===IDCAMS example===

This example uses the <var>IDCAMS</var> option (available as of Model 204 7.7) on the ECF <var>Module</var> statement to have IDCAMS input and output go from/to the user buffer.

====Module definition====
The following <var>External</var> statements make IDCAMS available:
b
external module idcams idcams
external load idcams
external name idcams for idcams
end


When <var>IDCAMS</var> is invoked by <var>External Call</var>, the user's [[Universal Buffer]] must contain the input lines to be passed to <code>SYSIN</code>, separated by EBCDIC linefeed characters (X'25'). The output lines from <var>IDCAMS</var> are appended to the Universal Buffer, also separated by new lines.

Before calling <var>IDCAMS</var>, the Universal Buffer must be allocated to a length sufficient to hold all of the input lines and all of the expected output lines. If the buffer is too small, output is truncated. While it is possible to calculate the optimum Universal Buffer length on each invocation, it is better to do the following to minimize storage fragmentation:
<ul>
<li>Use the same value for all invocations.</li>

<li>Use a multiple of 8K. </li>
</ul>

====Return codes====
The <var>IDCAMS</var> interface can return one of the following return codes:
<table class="thJustBold">
<tr><th>20</th>
<td>Universal Buffer was overflowed, output truncated.</td></tr>

<tr><th>24</th>
<td>Minimum outspace (2,000 bytes) not available in Universal Buffer.</td></tr>

<tr><th>28</th>
<td>No input data in Universal Buffer.</td></tr>

<tr><th>Else</th>
<td>The return code is from the IDCAMS program.</td></tr>
</table>

====SOUL code====
b
%idcams.in is longstring
%idcams.out is longstring
%lines.in is object stringlist
%lines.out is object stringlist

%hlq is string len 8
%options is string len 32
%input.len is float
%rc is float

%hlq = 'DRAKE'
%options = 'VOLUMES'

* Prepare IDCAMS input lines in stringlist. Note that that the
* TEXT TO statement supports expressions allowing %variables and
* functions to be used as the trivial example shows.
%lines.in = new
Text nocont To %lines.in
{} LISTCAT -
LEVEL({%hlq}) -
{%options}
End Text

* Note: the null expression {} in front of LISTCAT is to force
* indentation, since IDCAMS commands cannnot begin in column 1.

* Convert the stringlist to a longstring with EBCDIC new line
* delimiters at the end of each line. This is needed to use the
* Model 204 Universal Buffer feature, which only understands
* byte strings.
%idcams.in = %lines.in:CreateLines

* Force Universal Buffer allocation of sufficient size
modify buffer size=65536 nopreserve clear

* Prime Universal Buffer with input for IDCAMS, save its length
%input.len = $Lstr_Set_UserBuffer(%idcams.in)

* Call the IDCAMS wrapper, appending output to Universal Buffer
external call idcams
Printtext $status={$STATUS}, $STATUSD={$STATUSD}, $ECFSTAT={$ECFSTAT}
%rc = +$substr($ecfstat,4,5)
Printtext In simpler terms, the IDCAMS return code was {%rc}.

* Retrieve output data from Universal Buffer (too bad there isn't
* a starting offset parameter) and parse lines to stringLlist.
%idcams.out = $lstr_substr($lstr_Get_UserBuffer,%input.len+1)
%lines.out = new
%lines.out:ParseLines(%idcams.out)

Printtext IDCAMS passed the following {%lines.in:count} lines:
%lines.in:print

Printtext Which produced {%lines.out:count} lines of output:
%lines.out:print
end


[[Category:System management]]
[[Category:System-level capabilities of Model 204]]

New and updated messages in Model 204 version 7.7

2016-06-08T12:51:57Z

Gary: /* M204.2960: Initialized interface %x %y */

******THIS IS A DRAFT DOCUMENT.******

[[Release_notes_for_Model_204_version_7.7_--_DRAFT|Back to 7.7 release notes]]

<div class="noautonum">__TOC__</div>

==M204 messages==

===M204.0064: NDBSERVS cannot be less than NSERVS+2, reset to NSERVS+2===
If DEBUGOPT=x'02' (server swapping debugging facility) is set, the number of debug servers (NDBSERVS) must be greater than or equal to the number of servers (NSERVS+2).

System manager response: Set NDBSERVS to NSERVS+2 or greater.

Return codes: E 0 4 AUDITAD
----

===M204.0478: RACF message display limit reached; not all messages are displayed===
RACF login messages for the current session have exceeded the number of bytes available for their display. Further messages will not be displayed.

Response: No response is needed. This message is for information only.

Return codes: I 0 0 AUDITMS
----

===M204.1414: ERROR: SORT RECORD > 16MEG===
As of release 7.7, this error condition results in an error message and not a snap.

The user has exceeded the 16M sort record limit.

System manager response: Correct and retry.

Return codes: C 0 4 CANCEL AUDITER
----

===M204.1610: Only 4095 images allowed for a single block===
As of release 7.7, the number of allowed images has been increased to 4095.

More than 4095 IMAGE statements appear before the first END IMAGE. All of the
images describe the same block of data. Model 204 allows a maximum of 4095 images
of a single data block.

Response: Reduce the number of images of this block to 4095 or less. Note that items can redefine part of an image using the AT clause without creating a separate image definition. If the images describe separate blocks of data, insert END IMAGE
statements between the images. Retry the request.

Return codes: C 0 4 ECHO AUDITER
----

===M204.2316: TCPIP ERROR: category, PROCESS=process_name, REMOTEID=remote_id, SEITUH=data_header===
As of release 7.7, this message no longer issues a snap.

Unexpected data has been received on this connection requiring the connection to be closed. <var class="term">process_name</var> identifies the name of the process opened at the time of error. <var class="term">remote_id</var> identifies the remote Internet address. SEITUH is the data header (for Rocket Software internal use).

Response: Contact the System Manager.

System manager response: Obtain the CCAAUDIT file and contact Technical Support.

Return codes: C 0 20 AUDITER NOTERM
----

===M204.2956: File filename is in-memory file===
File <var class="term">filename</var> is defined as an in-memory file, which has no zHPF capabilities.

Return codes: I 0 0 AUDITAD
----

===M204.2957: Error errno opening stream streamname for Janus Web port portname===
This message indicates why the open failed for the TCPLOG stream <var class="term">streamname</var> for the Janus Web port <var class="term">portname</var>, where <var class="term">errno</var> indicates the problem:

<table>
<tr class="head">
<th>Number</th>
<th>Meaning</th>
</tr>
<tr><td> 1 </td> <td>Operation failed</td></tr>
<tr><td> 2 </td> <td>Stream id is not available</td></tr>
<tr><td> 3 </td> <td>Nonexistent stream or unauthorized access</td></tr>
<tr><td> 4 </td> <td>Permanent I/O error</td></tr>
<tr><td> 5 </td> <td>End-of-data or record not found</td></tr>
<tr><td> 6 </td> <td>Data length greater than buffer length</td></tr>
<tr><td> 7 </td> <td>Data validation error</td></tr>
<tr><td> 8 </td> <td>Stream not ring or concatenated</td></tr>
<tr><td> 9 </td> <td>All ring members full, cannot switch</td></tr>
<tr><td> 10 </td> <td>Offload process failed</td></tr>
<tr><td> 11 </td> <td>Terminal attention</td></tr>
<tr><td> 12 </td> <td>File full condition</td></tr>
<tr><td> 13 </td> <td>Reread required for OS-concatenation</td></tr>
<tr><td> 14 </td> <td>GCORE problem for arbitration buffers</td></tr>
<tr><td> 15 </td> <td>Parallel stream members differ</td></tr>
</table>

Return codes: I 0 0 AUDITAD NOTERM
----
===M204.2958: APSYPAGE is obsolete as of 7.6. Rocket recommends using RESPAGE and/or TEMPPAGE as the alternative===
As of version 7.7, setting APSYPAGE to non-zero results in an error and prevents the Online from coming up.

System manager response: Set APSYPAGE to 0 and use an alternative; see [[APSYPAGE parameter]] for details.

Return codes: C 0 4 AUDITER
----
===M204.2960: Initialized interface (ESM) (version)===
This message is issued during Model 204 startup when a Model 204 interface to an External Security Manager (RACF, ACF2, or Top Secret) has been successfully initialized. The message identifies the relevant ESM and its version.

The AUTHCTL VIEW command may be used by a System Manager to get more information about the current security environment.

RockZap User's Guide

2014-09-06T06:32:09Z

Gary: Redirected page to Media:SirzaprNew.pdf

#redirect [[media:SirzaprNew.pdf]]

RockZap User's Guide

2014-09-06T06:17:57Z

Gary: Created page with "media:SirzaprNew.pdf"

[[media:SirzaprNew.pdf]]

Downloading and applying fixes

2014-09-06T05:52:27Z

Gary: Created page with "Somebody has to write this page, sorry."

Somebody has to write this page, sorry.

Web help download fixes

2014-09-06T05:16:22Z

Gary: Redirected page to Downloading and applying fixes

#REDIRECT [[Downloading and applying fixes]]

Downloading macro libraries

2014-09-06T03:46:59Z

Gary: Created page with "==How can the macro libraries be downloaded?== The macro libraries can be downloaded by..."

==How can the macro libraries be downloaded?==
The macro libraries can be downloaded by clicking on
the link for the macro library with the right mouse
button. This will (on most browsers) bring up a pop-up menu
that will have an option Save Link As, Save target As,
Save As or something similar. Select this option and then
set the appropriate target directory (and name if desired)
for the file. The macro library will then be downloaded to to
the indicated location.

Alternatively, the left mouse button can be clicked on
the link for an macro library. This will result in the browser
prompting the user whether the file should be saved, where it
should be saved and under what name. Some browsers prompt
for this information before the macro library is actually
downloaded, others prompt for it after. Obviously, those
that prompt after will present a considerable delay before
the prompt. Opera actually prompts as soon as it receives the
file header but continues downloading while waiting for the
user response.

If the e-mail transfer is selected the macro library will be e-mailed
to the indicated e-mail address as an attachment. The attachment should
be saved to a local file and then uploaded to the mainframe exactly as
if it had been downloaded directly. Receiving the object deck via e-mail
allows the library to be sent to a different person/workstation
than the one initiating the request.

==How can the macro libraries be uploaded to the mainframe?==
Once the macro libraries are downloaded to the workstation they must
be uploaded to the MVS, VM or VSE system on the IBM mainframe.
Any file transfer mechanism can be used including FTP and IND$FILE
but regardless of the transfer mechanism some rules must be
observed.

First, the macro libraries contain binary data and hence must
be transferred as binary.

Second, the format and LRECL of the file must be specified during
the upload. This is because most workstation systems (including
Windows, Mac OS and Unix) do not have a concept of file formats
and LRECL's. This information would be lost if it were not specified
during the upload. The format of the uploaded file must be F under
VM systems and FB under MVS and VSE systems. The LRECL must be
80 on all systems and under MVS and VSE the blocksize can be any multiple
of 80 though 3120 is a common blocksize for object libraries.

When using FTP, the characteristics (RECFM, LRECL and BLOCKSIZE) of
the uploaded file can be set with the SITE and LOCSITE
FTP commands. The SITE command should be used if the FTP client
is on the workstation and the server is on the mainframe. In this case
the SITE command might have to be sent as a "quote" to the mainframe.
How this is done, depends on your workstation's FTP client.
The LOCSITE command should be used if the FTP client is on the
mainframe and the server is on the workstation.

Under MVS, you can upload an macro library either as a member of a Partitioned
Data Set (PDS) or as an individual sequential file. A PDS is recommended as
a good way to collect all your Sirius macro library uploads in one DSN, using
the member name to show the product and version.

==What are the Sirius Mods?==
The Sirius Mods is a collection of functions and enhancements
to the core Model 204 load module. These enhancements are either
products in and of themselves, or they are prerequisites for products which
are written in User Language. A site is authorized to download all of the
Sirus Mods if it is licensed for any of the products that
require these enhancements. Your authorization zap will then enable the
appropriate set of products.

Products that require the Sirius Mods include:

* Fast/Backup
* Fast/Reload
* Fast/Unload User Language Interface
* Janus Network Security
* Janus Open Server
* Janus Open Client
* Janus SOAP
* Janus Specialty Data Store
* Janus TCP/IP Base
* Janus Web Server
* Japanese Functions
* SirDBA
* SirFact
* SirFile
* Sirius Performance Enhancements
* Sirius Performance Enhancements V2
* SirLib
* SirMon
* SirPro
* SirSafe
* SirScan
* SirTune
* SirXref
* Sir2000 Field Migration Facility
* Sir2000 User Language Tools
* Trusted Login Facility

You can determine which of these products your site is authorized for by
examining <a href="https://m204.rocketsoftware.com/dlist">your customer profile</a>.
After the Sirius Mods are installed you can verify product authorizations by issuing
the SIRIUS command in an Online running a load module that
includes the Sirius Mods.

==Where can more documentation be found?==
The Rocket M204 macro libraries are distributed on an as-is basis, so no more
documentation is available.

==Is there any other help available?==
As always, if you have any questions about the installation of Rocket M204
products, you should not hesitate to call our technical
support number at +1.800.755.4222. You can also e-mail us at
[[mailto:m204support@rocketsoftware.com m204support@rocketsoftware.com]].

Downloading and installing client (workstation) files

2014-09-06T03:32:31Z

Gary: Created page with "==How can the client files be downloaded?== Files for client (workstation) files can..."

==How can the client files be downloaded?==
Files for client (workstation) files can be loaded by clicking on the link for a particular file
with the right mouse button.
This will (on most browsers) bring up a pop-up menu
that will have an option Save Link As, Save target As,
Save As, or something similar. Select this option, and then
set the appropriate target directory (and name if desired)
for the file. The file will then be downloaded to
the indicated location.

Alternatively, click the left mouse button on
the link for a file. This will result in the browser
prompting the user whether the file should be saved, where it
should be saved, and under what name. Some browsers prompt
for this information before the file is actually
downloaded; others prompt for it after. Obviously, those
that prompt after will present a considerable delay before
the prompt. Opera actually prompts as soon as it receives the
file header but continues downloading while waiting for the
user response.
The downloaded files can be 8 megabytes or bigger.
This means that the actual download can take several minutes,
depending on the size of
object file and the speed of the network link to Sirius's
web server.

==Where can more documentation be found?==
All the manuals for Rocket M204 products can be found on the [[Model 204 documentation]] page.
Of particular interest if you are doing a Sirius Mods install is the
[[media:SiriNew.pdf | Sirius Mods Installation Guide]].

==Is there any other help available?==
As always, if you have any questions about the installation of Rocket M204
products, you should not hesitate to call our technical
support number at +1.800.755.4222. You can also e-mail us at
[[mailto:m204support@rocketsoftware.com m204support@rocketsoftware.com]].

Downloading and restoring SOUL files

2014-09-06T03:13:58Z

Gary: /* How can the uploaded files be installed on the mainframe? */

==What is UL/SPF?==
UL/SPF is a family of tools that enhance programmer-productivity and
enable performance monitoring, sophisticated journal querying and other
programmer, DBA and system administrator
activities inside a Model 204 online. UL/SPF is implemented as a
set of APSYs, written in User Language. UL/SPF must
be installed in each online where its features are needed. Installation
requires Rocket M204 SOUL code, some files
that must be allocated locally, and the creation of the necessary APSYs.
The source code for all UL/SPF subsystems is in the SIRIUS procedure file,
which must be physically allocated to the online for the installation process.
The Sirius Mods must also be installed in the target online prior to
the installation of UL/SPF.

==How do I get the UL/SPF installation file?==
SOUL code for the UL/SPF product is distributed in the form of a dump of the
SIRIUS file from the Rocket M204 support site.
On most browsers a fly-out menu will provide options to
Save Link As... or Save Target As... or something similar.
After selecting a target directory, the file will download in binary
format.

Alternatively, the left mouse button can be clicked on
the link for a dump file. This will usually result in the browser
prompting the user whether the file should be saved, where it
should be saved and under what name.

Download times depend on the speed of your connection.

Aternatively, the dump file can be e-mailed as an attachment by clicking
on the e-mail link above. The attached binary should
be saved to a local file and then uploaded to the mainframe exactly as
if it had been downloaded directly. E-mail delivery can be useful if your
firewall disallows web downloads.

==How can the dump file be uploaded to the mainframe?==
The Sirius dump file must then be uploaded to your MVS, VM or
VSE system on your mainframe.
Any file transfer mechanism can be used including FTP and IND$FILE,
but regardless of the transfer mechanism some rules must be observed.

First, the dump files contain binary data, and so must
be transferred as binary. That is, no translation from ASCII to
EBCDIC must occur as a result of the upload.

Second, the format and LRECL of the file must be specified during
the upload. This is because most workstation systems (including
Windows, Mac OS and Unix) do not have a concept of file formats
and LRECL's. The format of the uploaded file must be F and
the LRECL must be 6184. Under MVS and VSE the blocksize must be 6184.

When using FTP, the characteristics (RECFM, LRECL and BLOCKSIZE) of
the uploaded file can be set with the SITE and LOCSITE
FTP commands. The SITE command should be used if the FTP client
is on the workstation and the server is on the mainframe. In this case
the SITE command might have to be sent as a "quote" to the mainframe.
How this is done, depends on your workstation's FTP client.
The LOCSITE command should be used if the FTP client is on the
mainframe and the server is on the workstation.

==How can the uploaded files be installed on the mainframe?==
Once uploaded to your mainframe, use the standard Model 204 RESTORE
command to restore the dump file to a Model 204 file with a DDNAME of SIRIUS.

'''''File Size:''''' The ''SIRIUS'' file must be allocated with at least
4200 Model 204 pages.

The rest of the installation process for the Sirius Software User
Language products is described in the [[UL/SPF installation guide |
UL/SPF Installation and Maintenance Guide]], including ancilliary files that must be allocated.

==Applying Maintenance==
The uploaded files will contain all the latest maintenance.
As such, no maintenance need be applied to the uploaded file.
Subsequent fixes can be applied by downloading User Language
fixes, loading them into the SIRFIXES file and applying them
to the appropriate Model 204 file with SIRFIX. Most sites find it easier
to return to this page and re-download a new copy of the SIRIUS
file, as the downloadable copy always has the latest maintenance applied.

Downloading and restoring SOUL files

2014-09-06T03:12:15Z

Gary: Created page with "==What is UL/SPF?== UL/SPF is a family of tools that e..."

==What is UL/SPF?==
UL/SPF is a family of tools that enhance programmer-productivity and
enable performance monitoring, sophisticated journal querying and other
programmer, DBA and system administrator
activities inside a Model 204 online. UL/SPF is implemented as a
set of APSYs, written in User Language. UL/SPF must
be installed in each online where its features are needed. Installation
requires Rocket M204 SOUL code, some files
that must be allocated locally, and the creation of the necessary APSYs.
The source code for all UL/SPF subsystems is in the SIRIUS procedure file,
which must be physically allocated to the online for the installation process.
The Sirius Mods must also be installed in the target online prior to
the installation of UL/SPF.

==How do I get the UL/SPF installation file?==
SOUL code for the UL/SPF product is distributed in the form of a dump of the
SIRIUS file from the Rocket M204 support site.
On most browsers a fly-out menu will provide options to
Save Link As... or Save Target As... or something similar.
After selecting a target directory, the file will download in binary
format.

Alternatively, the left mouse button can be clicked on
the link for a dump file. This will usually result in the browser
prompting the user whether the file should be saved, where it
should be saved and under what name.

Download times depend on the speed of your connection.

Aternatively, the dump file can be e-mailed as an attachment by clicking
on the e-mail link above. The attached binary should
be saved to a local file and then uploaded to the mainframe exactly as
if it had been downloaded directly. E-mail delivery can be useful if your
firewall disallows web downloads.

==How can the dump file be uploaded to the mainframe?==
The Sirius dump file must then be uploaded to your MVS, VM or
VSE system on your mainframe.
Any file transfer mechanism can be used including FTP and IND$FILE,
but regardless of the transfer mechanism some rules must be observed.

First, the dump files contain binary data, and so must
be transferred as binary. That is, no translation from ASCII to
EBCDIC must occur as a result of the upload.

Second, the format and LRECL of the file must be specified during
the upload. This is because most workstation systems (including
Windows, Mac OS and Unix) do not have a concept of file formats
and LRECL's. The format of the uploaded file must be F and
the LRECL must be 6184. Under MVS and VSE the blocksize must be 6184.

When using FTP, the characteristics (RECFM, LRECL and BLOCKSIZE) of
the uploaded file can be set with the SITE and LOCSITE
FTP commands. The SITE command should be used if the FTP client
is on the workstation and the server is on the mainframe. In this case
the SITE command might have to be sent as a "quote" to the mainframe.
How this is done, depends on your workstation's FTP client.
The LOCSITE command should be used if the FTP client is on the
mainframe and the server is on the workstation.

==How can the uploaded files be installed on the mainframe?==
Once uploaded to your mainframe, use the standard Model 204 RESTORE
command to restore the dump file to a Model 204 file with a DDNAME of SIRIUS.

'''''File Size:''''' The ''SIRIUS'' file must be allocated with at least
4200 Model 204 pages.

The rest of the installation process for the Sirius Software User
Language products is described in the <a href="http://m204wiki.rocketsoftware.com/index.php/UL/SPF_installation_guide">
UL/SPF Installation and Maintenance Guide</a>, including ancilliary files that must be allocated.

==Applying Maintenance==
The uploaded files will contain all the latest maintenance.
As such, no maintenance need be applied to the uploaded file.
Subsequent fixes can be applied by downloading User Language
fixes, loading them into the SIRFIXES file and applying them
to the appropriate Model 204 file with SIRFIX. Most sites find it easier
to return to this page and re-download a new copy of the SIRIUS
file, as the downloadable copy always has the latest maintenance applied.

Web help download client files

2014-09-06T02:47:42Z

Gary: Redirected page to Downloading and installing client (workstation) files

#REDIRECT [[Downloading and installing client (workstation) files]]

Web help download SOUL files

2014-09-06T02:04:03Z

Gary: Redirected page to Downloading and restoring SOUL files

#REDIRECT [[Downloading and restoring SOUL files]]

Web help download macro libraries

2014-09-06T02:03:39Z

Gary: Redirected page to Downloading and restoring macro libraries

#REDIRECT [[Downloading and restoring macro libraries]]

Web help download SOUL files

2014-09-06T01:47:32Z

Gary: Redirected page to Downloading and restoring Rocket SOUL files

#REDIRECT [[Downloading and restoring Rocket SOUL files]]

Web help download object files

2014-09-06T01:35:55Z

Gary: Redirected page to Downloading and installing Rocket M204 products

#REDIRECT [[Downloading and installing Rocket M204 products]]

Downloading and installing Rocket M204 products

2014-09-06T01:32:34Z

Gary: /* How can the above object files be downloaded? */

==How can the object files be downloaded?==
The object files can be downloaded by clicking on the link for the object file with the right mouse button.
This will (on most browsers) bring up a pop-up menu that will have an option Save Link As, Save target As, Save As, or something similar.
Select this option, and then set the appropriate target directory (and name if desired) for the file.
The object file will then be downloaded to the indicated location.

Alternatively, click the left mouse button on the link for an object file. This will result in the browser prompting the user whether the file should be saved, where it should be saved, and under what name.
Some browsers prompt for this information before the object file is actually downloaded; others prompt for it after.
Obviously, those that prompt after will present a considerable delay before the prompt.
Opera actually prompts as soon as it receives the file header but continues downloading while waiting for the user response.

Object files are customized for a particular site, simplifying the installation process.
Because of this, there may be a noticeable delay in processing a download request.
In addition, the downloaded object files can range in size from hundreds of kilobytes to perhaps 10 megabytes.

If an e-mail transfer is selected, the object deck will be e-mailed to the indicated e-mail address as an attachment.
The attachment should be saved to a local file and then uploaded to the mainframe exactly as if it had been downloaded directly.
Receiving the object deck via e-mail might take a little longer than downloading it directly, but it allows you to schedule a set of object to be sent to a different person in your organization.

==How can the object files be uploaded to the mainframe?==
Once the object files are downloaded to the workstation they must be uploaded to the z/OS, VM, or VSE system on the IBM mainframe.
Any file transfer mechanism can be used including FTP and IND$FILE, but regardless of the transfer mechanism some rules must be observed.

First, the object files contain binary data and hence must be transferred as binary.
That is, no translation from ASCII to EBCDIC must occur as a result of the upload.

Second, the format and LRECL of the file must be specified during the upload.
This is because most workstation systems (including Windows, Mac OS and Unix) do not have a concept of file formats and LRECL's.
This information would be lost if it were not specified during the upload.
The format of the uploaded file must be F under VM systems and FB under z/OS and VSE systems. The LRECL must be
80 on all systems and under z/OS and VSE the blocksize can be any multiple of 80 though 3120 is a common blocksize for object libraries.

When using FTP, the characteristics (RECFM, LRECL, and BLOCKSIZE) of the uploaded file can be set with the SITE and LOCSITE FTP commands.
The SITE command should be used if the FTP client is on the workstation and the server is on the mainframe.
In this case the SITE command might have to be sent as a "quote" to the mainframe.
How this is done depends on your workstation's FTP client.
The LOCSITE command should be used if the FTP client is on the mainframe and the server is on the workstation.

===Model 204 object library===
The Model 204 installation process entails creating a library (in z/OS, a Partitioned Data Set, or PDS), which is then used in subsequent steps to link the various Model 204 load modules.
The file which you have uploaded to the mainframe, typically as a sequential dataset (DSORG=PS in z/OS), is used as the <code>INP=</code> parameter to the following JCL PROC for a z/OS installation:

<pre>
//NEWOBJLB PROC TRK='320,50',BLK=6400
//*
//* Usage: //BLD EXEC NEWOBJLB,LIB=objectLibDsn,INP=inputStreamDsn
//*
//* Important note: The output object library (LIB=) is first deleted
//*
//* This proc creates an object library, using the input stream which
//* was downloaded from the Rocket Model 204 web site. After the
//* download, it must be un-zipped, and then FTP'd (BINARY, 80 byte
//* fixed length records) to a z/OS dataset.
//*
//* The FTP'd z/OS dataset is specified by the INP= parameter
//*
//* Note: If you thought you might want to, it's best not to try
//* to over-ride SYSIN with a DD *, because the input stream
//* contains JCL.
//*
//DEL EXEC PGM=IEFBR14
//DEL DD DSN=&LIB,DISP=(MOD,DELETE),UNIT=SYSDA,SPACE=(TRK,1)
//*
//BLDOBJLB EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD SYSOUT=A << Note: this output will contain on the order
//* of 160K lines or more
//SYSUT2 DD DISP=(NEW,CATLG),SPACE=(TRK,(&TRK,60),RLSE),
// UNIT=SYSDA,DCB=(DSORG=PO,LRECL=80,RECFM=FB,BLKSIZE=&BLK),
// DSN=&LIB
//SYSIN DD DISP=SHR,DSN=&INP
//*
// PEND
</pre>
For example, if you downloaded the input stream and then FTP'd it into <code>M204.V75.DOWNLOAD.OBJ</code>,
and the object library dataset is to be <code>M204.V75.OBJLIB</code>:
<pre>
//BLDOBJLB EXEC NEWOBJLB,
// INP=M204.V75.DOWNLOAD,
// LIB=M204.V75.OBJLIB

</pre>

The space allocation and block size are PROC parameters, but their defaults will work.
You can, of course, use any dataset name you want for the object library after <code>INP=</code> — note that in our documentation, we refer to the object library as ROKOB204.

===Other object files===
For products other than Model 204, the downloaded file is a single object file.
Under z/OS, you can upload an object file either as a member of a Partitioned Data Set (PDS) or as an individual sequential file.
A PDS is recommended as a good way to collect all your Rocket M204 object file uploads in one dataset, using the member name to show the product and version.

==Should maintenance be applied to the uploaded object files?==
When Rocket M204 products are downloaded, they will contain all of the current maintenance as well as all applicable authorization keys.
Thus no additional additional installation steps steps are required to install maintenance or authorization keys.
Subsequent fixes can be applied by downloading ZAPs and applying them, or by downloading a replacement object file and re-linking the appropriate load modules.

==How should the Model 204 load modules be linked under z/OS?==
The Model 204 object library you created contains object files, JCL, and link-edit control statements so that you can link the Model 204 load modules.
(This library, of course, has the DSNAME you chose — but in our documentation, we refer to the object library as ROKOB204).

One of the members of ROKOB204 is a text file named README, which includes a list of the Model 204 load modules, and, individual instructions for linking them.

For example, to link the ONLINE load module, there is a member named JZLONLN.
This basic JCL has simple instructions for using it.
One of the comments in the JCL is a link which you may follow for more [[M204_install#zOS_link_onl|detailed instructions]].

==What are the Sirius Mods?==
The Sirius Mods is a collection of functions and enhancements to the core Model 204 load module.
These enhancements are either products in and of themselves, or they are prerequisites for products which are written in User Language.
A site is authorized to download all of the Sirus Mods if it is licensed for any of the products that require these enhancements.
Your authorization key will then enable the appropriate set of products.

Products that require the Sirius Mods are:

* Fast/Backup
* Fast/Reload
* Fast/Unload User Language Interface
* Janus Network Security
* Janus Open Server
* Janus Open Client
* Janus SOAP
* Janus Specialty Data Store
* Janus TCP/IP Base
* Janus Web Server
* Japanese Functions
* SirDBA
* SirFact
* SirFile
* Sirius Performance Enhancements
* Sirius Performance Enhancements V2
* SirLib
* SirMon
* SirPro
* SirSafe
* SirScan
* SirTune
* SirXref
* Sir2000 Field Migration Facility
* Sir2000 User Language Tools
* Trusted Login Facility

You can determine which of these products your site is authorized for by examining <a href="https://m204.rocketsoftware.com/dlist">your customer profile</a>. After the Sirius Mods are installed, you can verify product authorizations by issuing the SIRIUS command in an Online running a load module that includes the Sirius&npsp;Mods.

==How should the Sirius Mods object file be linked under z/OS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
Under z/OS, an object deck can be re-linked with a load module.
In theory, this load module can already contain the Sirius Mods.
While this is generally OK if linking over the same release of the Sirius Mods, it is almost certainly a bad idea otherwise.
As such, it is a good idea to keep a load module without the Sirius Mods available for rebuilding a load module with the Sirius Mods.
The non-Sirius Mods load module should have all Rocket ZAPs applied, or these ZAPs should be applied after the re-link with the Sirius Mods object file.

Should Rocket provide replacement object files as part of their maintenance, these object files must never be linked ahead of the Sirius Mods object file.
This also means that replacement Rocket object files cannot simply be linked ahead of a load module containing the Sirius Mods without also linking the Sirius Mods object file ahead of the replacement object files from Rocket.

Both of the next two examples assume you uploaded the object file into library SIRIUS.LIB with a member name of SIR80074.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB. The module is linked into library SIRIUS.LOAD.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</code>

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB, along with replacement object decks for EVNU and SBFM, which were provided with Rocket maintenance and are in library M204.V7R4.FIXOBJ.
The module is linked into library SIRIUS.LOAD.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//M204FIX DD DSN=M204.V7R4.FIXOBJ,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204FIX(EVFM,SBFM)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</code>

==How should the Sirius Mods object file be linked under CMS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
This means, first, that the object file's filetype must conform to CMS conventions for object files.
The simplest way to ensure this is to use a filetype of TEXT for the object file under CMS.

To link with the Rocket-supplied M204GEN utility, the Model 204 load list must be modified to include the Sirius Mods object file.
This can be done by simply inserting a line with an "&1 &2" followed by the filename of the Sirius Mods object file before the name of any other object file in the load list.
The following is an example of the first few lines of an updated load list, where the Sirius Mods object file is called "SIR80074 TEXT".

<code>
* LOAD LIST FOR M204ONLN MODULE
* (&START IN MLNK)
&1 &2 SIR80074
&1 &2 MLNK
&1 &2 ACF2CMS
&1 &2 ANXV
&1 &2 APSY
&1 &2 APSZ
&1 &2 ARTH
. . . . .
</code>

Because the Sirius Mods dynamically adds hooks to the load module, Sirius recommends against using shared segments with the Sirius Mods.
If this is considered essential, contact Sirius Software technical support for help in building a load module with the Sirius Mods and shared segments.

An exec called LOADCONV is also available to automatically convert the loadlist, it can be <a href="download/loadconv.rex">downloaded here</a>.
Note that LOADCONV requires that the filename of the Sirius Mods object file be "SIROBJ" followed by the Model 204 release to which it
applies, as in "SIROBJ74".

If the M204GEN exec is being used, M204CCA PARMS needs to be edited.
First, in the M204GEN/DEFAULTS section, the ldrtbls value might need to be increased:

<code>
M204GEN:
DEFAULTS:
ldrtbls = 50
</code>

Also, the load module start needs to include the Sirius Mods so in the ONLINE/ONLN section the line

<code>
start.mod = MLNK$
</code>

needs to be changed to

<code>
start.mod = SLNK$
</code>

If you want to be able to generate a load module both with and without the Sirius Mods, you could copy the whole ONLINE section in M204CCA PARMS and call it something else, for example, SIRIUS, and change start.mod in that section.
Then, when you want to generate a load module with the Sirius Mods in it you'd simply type

<code>
M204GEN SIRIUS
</code>

===How should the Sirius Mods object file be linked under VSE?===
The Sirius Mods object file should be linked ahead of the Model 204 object files from Rocket. The example below shows an excerpt of the standard Rocket link JCL for an ONLINE.
To linkedit the online with the Sirius Mods, you must insert the include statement for the object module immediately after the PHASE statement.
In this example, the Sirius Mods object is named SIR80074.
If the Sirius Mods object module is in a separate library, the JCL should be modified to include that library in the SEARCH= paramter of the LIBDEF OBJ statement.
If you include any other object modules, they also must appear after the Sirius Mods object.

<code>
...
// LIBDEF PHASE,CATALOG=M204LIB.V7R4
// LIBDEF OBJ,SEARCH=M204LIB.V7R4
// OPTION CATAL
PHASE ONLINE,* REPLACE=YES
INCLUDE SIR80074
INCLUDE LKONLN
INCLUDE
ENTRY MAINTASK
/*
// EXEC LNKEDT
/*
/&
...
</code>

===How should the Fast/Unload object file be linked?===
The following z/OS JCL is an example of how one would link the Fast/Unload object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of FUN400.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FUN400)
ENTRY FUNLOAD
NAME FUNLOAD(R)
/*
</code>

Under CMS, the Fast/Unload object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a FUNLOAD load module.
In this example, it is assumed that the Fast/Unload object file has a filename of FUN400.

<code>
LOAD FUN400 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET FUNLOAD RLDSAVE
GENMOD FUNLOAD (FROM FUNL
</code>

===Why were there three object files for SirTune?===
Beginning with Version 7.0 of the Sirius Mods, all SirTune functionality has been merged into the Sirius Mods and so the standalone SirTune load modules are obsolete.

Prior to Version 7.0 of the Sirius Mods, however, SirTune consisted of three components.
The first component was called the SirTune Data Collector or simply SirTune.
This load module runs in the same address space as the Model 204 load module and collects data to be analyzed later.

The second component is called the SirTune Report Generator.
This load module is run independently of Model 204 and summarizes the data collected by SirTune into a report.

The third component is used only under CMS and is called the SirTune Data Logger.
It communicates with SirTune via IUCV and asynchronously logs SirTune data on a separate virtual machine.
It is used to get around some of the difficulties of doing asynchronous I/O under CMS.

In general, it is a good idea to be using the same versions of all three SirTune components though Sirius makes every effort to allow a newer SirTune Report Generator to produce reports from sample datasets created by older releases of SirTune.

===How should the SirTune object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNE104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNE104)
ENTRY COLLECT
NAME SIRTUNE(R)
/*
</code>

Under CMS, the SirTune object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNE load module.
In this example, it is assumed that the SirTune object file has a filename of TUNE104.

<code>
LOAD TUNE104 (FULLMAP NODUP ORIGIN 400000 AMODE 31 RESET COLLECT
GENMOD SIRTUNE (FROM COLL
</code>

===How should the SirTune Report Generator object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune Report Generator object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNR104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNR104)
ENTRY ANALYZE
NAME SIRTUNER(R)
/*
</code>

Under CMS, the SirTune Report Renerator object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNER load module.
In this example, it is assumed that the SirTune Report Generator object file has a filename of TUNR103.

<code>
LOAD TUNR103 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET ANALYZE
GENMOD SIRTUNER (FROM ANAL
</code>

===How should the SirTune Data Logger object file be linked?===
The SirTune data Logger is not used under z/OS.

Under CMS, the SirTune Data Logger object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNED load module.
In this example, it is assumed that the SirTune Data Logger object file has a filename of TUND104.

<code>
LOAD TUND104 (FULLMAP NODUP ORIGIN 30000 AMODE 24 RESET OUTCMS
GENMOD SIRTUNED (FROM OUTC
</code>

===How should the RockZap object file be linked?===
The following z/OS JCL is an example of how one would link the RockZap object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of ZAP106.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(ZAP106)
ENTRY SIRZAP
NAME SIRZAP(R)
/*
</code>

Under CMS, the SirZap object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRZAP load module.
In this example, it is assumed that the SirZap object file has a filename of ZAP106.

<code>
LOAD ZAP106 (FULLMAP NODUP ORIGIN 20000 AMODE 31 RESET SIRZAP
GENMOD SIRZAP (FROM APPL
</code>

===How should the SirAud object file be linked?===
The following z/OS JCL is an example of how one would link the SirAud object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of AUD102.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(AUD102)
ENTRY JMAIN
NAME SIRAUD(R)
/*
</code>

Under CMS, the SirAud object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRAUD load module.
In this example, it is assumed that the SirAud object file has a filename of AUD102.

<code>
LOAD AUD102 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET JMAIN
GENMOD SIRAUD (FROM JCONF
</code>

===How should the Fast/Cram object files be installed?===
Most of the documentation for Fast/Cram installation can be found in the <a href="https://m204.rocketsoftware.com/maint/download/CRAMR.PDF">
Fast/Cram Installation Guide</a>.
That manual is currently not updated to reflect web downloads, so a few things must be kept in mind.
The first is that the first four characters of the download file indicate the module being downloaded, and they correspond to a specific member in SIRIUS.LOAD,
as described in the Fast/Cram Installation Guide.
The correspondences between the first four characters in the downloaded object files and the members in SIRIUS.LOAD are:

<table cellpadding=6>
<tr><td>FCRM</td><td>FASTSVC</td></tr>
<tr><td>FCRI</td><td>IGCLM244</td></tr>
<tr><td>FCRR</td><td>FASTREP</td></tr>
<tr><td>FCRS</td><td>SNAPFAST</td></tr>
</table>

The following example JCL would create SIRIUS.LOAD load modules as described in the Fast/Cram Installation Guide.
This example assumes you uploaded the object files into library SIRIUS.LIB with member names of FCR*27.
If you uploaded to non-library datasets (that is, sequential datasets, not Partitioned Data Sets), then you will need a separate DD statement for each object file as well as appropriate INCLUDE statements for them, omitting the parentheses and member names.

Note: The Fast/CRAM modules must be linked using the RENT option.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FCRM27)
ENTRY FASTSVC
NAME FASTSVC(R)
INCLUDE LIB(FCRI27)
ENTRY FASTRLD
NAME IGCLM244(R)
INCLUDE LIB(FCRR27)
ENTRY FASTREP
NAME FASTREP(R)
INCLUDE LIB(FCRS27)
ENTRY SNAPFAST
NAME SNAPFAST(R)
/*
</code>

Unfortunately, the customization job is currently Fast/Cram release specific.
The following job is a sample customization job for Fast/Cram V2.7:

<code>
//FASTCUST JOB ,'Fast/CRAM',CLASS=A,MSGCLASS=A
//*
//* Customize FASTCRAM Version 2.7
//*
//* Install FASTCRAM in SYS1.LPALIB,
//* as a Type 3 or type 4 SVC, using an SVC
//* number of 250 and a subsystem name of SIRI.
//*
//ZAPS EXEC PGM=SIRZAP,PARM=NOVER
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DISP=SHR,DSN=SIRIUS.LOAD
//SYSIN DD *
* *********************************************************************
* ZAP THE SVC NUMBER INTO FASTRLD. *
* *********************************************************************
NAME FASTRLD FASTRLD
VER 0184 0A0D
REP 0184 0AFA * NEW SVC=250
* *********************************************************************
* ZAP THE SUBSYSTEM NAME AND SVC NUMBER INTO FASTSVC. *
* *********************************************************************
NAME FASTSVC FASTSVC
VER 1678 00007FFF
VER 167C C6C1E2E3 * CURRENT SUBSYSTEM=FAST
REP 167C E2C9D9C9 * NEW SUBSYSTEM=SIRI
VER 1688 0A0D
REP 1688 0AFA * NEW SVC=250
/*
</code>

No matter which subsystem name you choose, this subsystem name must be defined in IEFSSNxx in SYS1.PARMLIB.
It is strongly recommended that subsystem name "M204" not be used because that subsystem name is used for Model 204's standard CRAM implementations.
The subsystem can also be defined dynamically with the SETSSI command:

<code>
SETSSI ADD,SUBNAME=FAST
</code>

If you are downloading a release for which no sample customization job is listed here, or if you need more help with the installation, contact Rocket M204 support at +1.800.755.4222, or e-mail us at [mailto:m204support@rocketsoftware.com m204support@rocketsoftware.com].

===Where can more documentation be found?===
The primary source of documentation for Rocket M204 products is this wiki.

Web help download authorization keys

2014-09-04T21:27:31Z

Gary: Redirected page to Downloading and installing Rocket M204 products

#REDIRECT [[Downloading and installing Rocket M204 products]]

Downloading and installing Rocket M204 products

2014-09-04T21:24:20Z

Gary: /* How should the Fast/Cram object files be installed? */

==How can the above object files be downloaded?==
The object files can be downloaded by clicking on the link for the object file with the right mouse button.
This will (on most browsers) bring up a pop-up menu that will have an option Save Link As, Save target As, Save As, or something similar.
Select this option, and then set the appropriate target directory (and name if desired) for the file.
The object file will then be downloaded to the indicated location.

Alternatively, click the left mouse button on the link for an object file. This will result in the browser prompting the user whether the file should be saved, where it should be saved, and under what name.
Some browsers prompt for this information before the object file is actually downloaded; others prompt for it after.
Obviously, those that prompt after will present a considerable delay before the prompt.
Opera actually prompts as soon as it receives the file header but continues downloading while waiting for the user response.

Object files are customized for a particular site, simplifying the installation process.
Because of this, there may be a noticeable delay in processing a download request.
In addition, the downloaded object files can range in size from hundreds of kilobytes to perhaps 10 megabytes.

If an e-mail transfer is selected, the object deck will be e-mailed to the indicated e-mail address as an attachment.
The attachment should be saved to a local file and then uploaded to the mainframe exactly as if it had been downloaded directly.
Receiving the object deck via e-mail might take a little longer than downloading it directly, but it allows you to schedule a set of object to be sent to a different person in your organization.

==How can the object files be uploaded to the mainframe?==
Once the object files are downloaded to the workstation they must be uploaded to the z/OS, VM, or VSE system on the IBM mainframe.
Any file transfer mechanism can be used including FTP and IND$FILE, but regardless of the transfer mechanism some rules must be observed.

First, the object files contain binary data and hence must be transferred as binary.
That is, no translation from ASCII to EBCDIC must occur as a result of the upload.

Second, the format and LRECL of the file must be specified during the upload.
This is because most workstation systems (including Windows, Mac OS and Unix) do not have a concept of file formats and LRECL's.
This information would be lost if it were not specified during the upload.
The format of the uploaded file must be F under VM systems and FB under z/OS and VSE systems. The LRECL must be
80 on all systems and under z/OS and VSE the blocksize can be any multiple of 80 though 3120 is a common blocksize for object libraries.

When using FTP, the characteristics (RECFM, LRECL, and BLOCKSIZE) of the uploaded file can be set with the SITE and LOCSITE FTP commands.
The SITE command should be used if the FTP client is on the workstation and the server is on the mainframe.
In this case the SITE command might have to be sent as a "quote" to the mainframe.
How this is done depends on your workstation's FTP client.
The LOCSITE command should be used if the FTP client is on the mainframe and the server is on the workstation.

===Model 204 object library===
The Model 204 installation process entails creating a library (in z/OS, a Partitioned Data Set, or PDS), which is then used in subsequent steps to link the various Model 204 load modules.
The file which you have uploaded to the mainframe, typically as a sequential dataset (DSORG=PS in z/OS), is used as the <code>INP=</code> parameter to the following JCL PROC for a z/OS installation:

<pre>
//NEWOBJLB PROC TRK='320,50',BLK=6400
//*
//* Usage: //BLD EXEC NEWOBJLB,LIB=objectLibDsn,INP=inputStreamDsn
//*
//* Important note: The output object library (LIB=) is first deleted
//*
//* This proc creates an object library, using the input stream which
//* was downloaded from the Rocket Model 204 web site. After the
//* download, it must be un-zipped, and then FTP'd (BINARY, 80 byte
//* fixed length records) to a z/OS dataset.
//*
//* The FTP'd z/OS dataset is specified by the INP= parameter
//*
//* Note: If you thought you might want to, it's best not to try
//* to over-ride SYSIN with a DD *, because the input stream
//* contains JCL.
//*
//DEL EXEC PGM=IEFBR14
//DEL DD DSN=&LIB,DISP=(MOD,DELETE),UNIT=SYSDA,SPACE=(TRK,1)
//*
//BLDOBJLB EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD SYSOUT=A << Note: this output will contain on the order
//* of 160K lines or more
//SYSUT2 DD DISP=(NEW,CATLG),SPACE=(TRK,(&TRK,60),RLSE),
// UNIT=SYSDA,DCB=(DSORG=PO,LRECL=80,RECFM=FB,BLKSIZE=&BLK),
// DSN=&LIB
//SYSIN DD DISP=SHR,DSN=&INP
//*
// PEND
</pre>
For example, if you downloaded the input stream and then FTP'd it into <code>M204.V75.DOWNLOAD.OBJ</code>,
and the object library dataset is to be <code>M204.V75.OBJLIB</code>:
<pre>
//BLDOBJLB EXEC NEWOBJLB,
// INP=M204.V75.DOWNLOAD,
// LIB=M204.V75.OBJLIB

</pre>

The space allocation and block size are PROC parameters, but their defaults will work.
You can, of course, use any dataset name you want for the object library after <code>INP=</code> — note that in our documentation, we refer to the object library as ROKOB204.

===Other object files===
For products other than Model 204, the downloaded file is a single object file.
Under z/OS, you can upload an object file either as a member of a Partitioned Data Set (PDS) or as an individual sequential file.
A PDS is recommended as a good way to collect all your Rocket M204 object file uploads in one dataset, using the member name to show the product and version.

==Should maintenance be applied to the uploaded object files?==
When Rocket M204 products are downloaded, they will contain all of the current maintenance as well as all applicable authorization keys.
Thus no additional additional installation steps steps are required to install maintenance or authorization keys.
Subsequent fixes can be applied by downloading ZAPs and applying them, or by downloading a replacement object file and re-linking the appropriate load modules.

==How should the Model 204 load modules be linked under z/OS?==
The Model 204 object library you created contains object files, JCL, and link-edit control statements so that you can link the Model 204 load modules.
(This library, of course, has the DSNAME you chose — but in our documentation, we refer to the object library as ROKOB204).

One of the members of ROKOB204 is a text file named README, which includes a list of the Model 204 load modules, and, individual instructions for linking them.

For example, to link the ONLINE load module, there is a member named JZLONLN.
This basic JCL has simple instructions for using it.
One of the comments in the JCL is a link which you may follow for more [[M204_install#zOS_link_onl|detailed instructions]].

==What are the Sirius Mods?==
The Sirius Mods is a collection of functions and enhancements to the core Model 204 load module.
These enhancements are either products in and of themselves, or they are prerequisites for products which are written in User Language.
A site is authorized to download all of the Sirus Mods if it is licensed for any of the products that require these enhancements.
Your authorization key will then enable the appropriate set of products.

Products that require the Sirius Mods are:

* Fast/Backup
* Fast/Reload
* Fast/Unload User Language Interface
* Janus Network Security
* Janus Open Server
* Janus Open Client
* Janus SOAP
* Janus Specialty Data Store
* Janus TCP/IP Base
* Janus Web Server
* Japanese Functions
* SirDBA
* SirFact
* SirFile
* Sirius Performance Enhancements
* Sirius Performance Enhancements V2
* SirLib
* SirMon
* SirPro
* SirSafe
* SirScan
* SirTune
* SirXref
* Sir2000 Field Migration Facility
* Sir2000 User Language Tools
* Trusted Login Facility

You can determine which of these products your site is authorized for by examining <a href="https://m204.rocketsoftware.com/dlist">your customer profile</a>. After the Sirius Mods are installed, you can verify product authorizations by issuing the SIRIUS command in an Online running a load module that includes the Sirius&npsp;Mods.

==How should the Sirius Mods object file be linked under z/OS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
Under z/OS, an object deck can be re-linked with a load module.
In theory, this load module can already contain the Sirius Mods.
While this is generally OK if linking over the same release of the Sirius Mods, it is almost certainly a bad idea otherwise.
As such, it is a good idea to keep a load module without the Sirius Mods available for rebuilding a load module with the Sirius Mods.
The non-Sirius Mods load module should have all Rocket ZAPs applied, or these ZAPs should be applied after the re-link with the Sirius Mods object file.

Should Rocket provide replacement object files as part of their maintenance, these object files must never be linked ahead of the Sirius Mods object file.
This also means that replacement Rocket object files cannot simply be linked ahead of a load module containing the Sirius Mods without also linking the Sirius Mods object file ahead of the replacement object files from Rocket.

Both of the next two examples assume you uploaded the object file into library SIRIUS.LIB with a member name of SIR80074.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB. The module is linked into library SIRIUS.LOAD.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</code>

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB, along with replacement object decks for EVNU and SBFM, which were provided with Rocket maintenance and are in library M204.V7R4.FIXOBJ.
The module is linked into library SIRIUS.LOAD.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//M204FIX DD DSN=M204.V7R4.FIXOBJ,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204FIX(EVFM,SBFM)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</code>

==How should the Sirius Mods object file be linked under CMS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
This means, first, that the object file's filetype must conform to CMS conventions for object files.
The simplest way to ensure this is to use a filetype of TEXT for the object file under CMS.

To link with the Rocket-supplied M204GEN utility, the Model 204 load list must be modified to include the Sirius Mods object file.
This can be done by simply inserting a line with an "&1 &2" followed by the filename of the Sirius Mods object file before the name of any other object file in the load list.
The following is an example of the first few lines of an updated load list, where the Sirius Mods object file is called "SIR80074 TEXT".

<code>
* LOAD LIST FOR M204ONLN MODULE
* (&START IN MLNK)
&1 &2 SIR80074
&1 &2 MLNK
&1 &2 ACF2CMS
&1 &2 ANXV
&1 &2 APSY
&1 &2 APSZ
&1 &2 ARTH
. . . . .
</code>

Because the Sirius Mods dynamically adds hooks to the load module, Sirius recommends against using shared segments with the Sirius Mods.
If this is considered essential, contact Sirius Software technical support for help in building a load module with the Sirius Mods and shared segments.

An exec called LOADCONV is also available to automatically convert the loadlist, it can be <a href="download/loadconv.rex">downloaded here</a>.
Note that LOADCONV requires that the filename of the Sirius Mods object file be "SIROBJ" followed by the Model 204 release to which it
applies, as in "SIROBJ74".

If the M204GEN exec is being used, M204CCA PARMS needs to be edited.
First, in the M204GEN/DEFAULTS section, the ldrtbls value might need to be increased:

<code>
M204GEN:
DEFAULTS:
ldrtbls = 50
</code>

Also, the load module start needs to include the Sirius Mods so in the ONLINE/ONLN section the line

<code>
start.mod = MLNK$
</code>

needs to be changed to

<code>
start.mod = SLNK$
</code>

If you want to be able to generate a load module both with and without the Sirius Mods, you could copy the whole ONLINE section in M204CCA PARMS and call it something else, for example, SIRIUS, and change start.mod in that section.
Then, when you want to generate a load module with the Sirius Mods in it you'd simply type

<code>
M204GEN SIRIUS
</code>

===How should the Sirius Mods object file be linked under VSE?===
The Sirius Mods object file should be linked ahead of the Model 204 object files from Rocket. The example below shows an excerpt of the standard Rocket link JCL for an ONLINE.
To linkedit the online with the Sirius Mods, you must insert the include statement for the object module immediately after the PHASE statement.
In this example, the Sirius Mods object is named SIR80074.
If the Sirius Mods object module is in a separate library, the JCL should be modified to include that library in the SEARCH= paramter of the LIBDEF OBJ statement.
If you include any other object modules, they also must appear after the Sirius Mods object.

<code>
...
// LIBDEF PHASE,CATALOG=M204LIB.V7R4
// LIBDEF OBJ,SEARCH=M204LIB.V7R4
// OPTION CATAL
PHASE ONLINE,* REPLACE=YES
INCLUDE SIR80074
INCLUDE LKONLN
INCLUDE
ENTRY MAINTASK
/*
// EXEC LNKEDT
/*
/&
...
</code>

===How should the Fast/Unload object file be linked?===
The following z/OS JCL is an example of how one would link the Fast/Unload object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of FUN400.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FUN400)
ENTRY FUNLOAD
NAME FUNLOAD(R)
/*
</code>

Under CMS, the Fast/Unload object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a FUNLOAD load module.
In this example, it is assumed that the Fast/Unload object file has a filename of FUN400.

<code>
LOAD FUN400 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET FUNLOAD RLDSAVE
GENMOD FUNLOAD (FROM FUNL
</code>

===Why were there three object files for SirTune?===
Beginning with Version 7.0 of the Sirius Mods, all SirTune functionality has been merged into the Sirius Mods and so the standalone SirTune load modules are obsolete.

Prior to Version 7.0 of the Sirius Mods, however, SirTune consisted of three components.
The first component was called the SirTune Data Collector or simply SirTune.
This load module runs in the same address space as the Model 204 load module and collects data to be analyzed later.

The second component is called the SirTune Report Generator.
This load module is run independently of Model 204 and summarizes the data collected by SirTune into a report.

The third component is used only under CMS and is called the SirTune Data Logger.
It communicates with SirTune via IUCV and asynchronously logs SirTune data on a separate virtual machine.
It is used to get around some of the difficulties of doing asynchronous I/O under CMS.

In general, it is a good idea to be using the same versions of all three SirTune components though Sirius makes every effort to allow a newer SirTune Report Generator to produce reports from sample datasets created by older releases of SirTune.

===How should the SirTune object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNE104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNE104)
ENTRY COLLECT
NAME SIRTUNE(R)
/*
</code>

Under CMS, the SirTune object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNE load module.
In this example, it is assumed that the SirTune object file has a filename of TUNE104.

<code>
LOAD TUNE104 (FULLMAP NODUP ORIGIN 400000 AMODE 31 RESET COLLECT
GENMOD SIRTUNE (FROM COLL
</code>

===How should the SirTune Report Generator object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune Report Generator object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNR104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNR104)
ENTRY ANALYZE
NAME SIRTUNER(R)
/*
</code>

Under CMS, the SirTune Report Renerator object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNER load module.
In this example, it is assumed that the SirTune Report Generator object file has a filename of TUNR103.

<code>
LOAD TUNR103 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET ANALYZE
GENMOD SIRTUNER (FROM ANAL
</code>

===How should the SirTune Data Logger object file be linked?===
The SirTune data Logger is not used under z/OS.

Under CMS, the SirTune Data Logger object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNED load module.
In this example, it is assumed that the SirTune Data Logger object file has a filename of TUND104.

<code>
LOAD TUND104 (FULLMAP NODUP ORIGIN 30000 AMODE 24 RESET OUTCMS
GENMOD SIRTUNED (FROM OUTC
</code>

===How should the RockZap object file be linked?===
The following z/OS JCL is an example of how one would link the RockZap object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of ZAP106.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(ZAP106)
ENTRY SIRZAP
NAME SIRZAP(R)
/*
</code>

Under CMS, the SirZap object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRZAP load module.
In this example, it is assumed that the SirZap object file has a filename of ZAP106.

<code>
LOAD ZAP106 (FULLMAP NODUP ORIGIN 20000 AMODE 31 RESET SIRZAP
GENMOD SIRZAP (FROM APPL
</code>

===How should the SirAud object file be linked?===
The following z/OS JCL is an example of how one would link the SirAud object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of AUD102.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(AUD102)
ENTRY JMAIN
NAME SIRAUD(R)
/*
</code>

Under CMS, the SirAud object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRAUD load module.
In this example, it is assumed that the SirAud object file has a filename of AUD102.

<code>
LOAD AUD102 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET JMAIN
GENMOD SIRAUD (FROM JCONF
</code>

===How should the Fast/Cram object files be installed?===
Most of the documentation for Fast/Cram installation can be found in the <a href="https://m204.rocketsoftware.com/maint/download/CRAMR.PDF">
Fast/Cram Installation Guide</a>.
That manual is currently not updated to reflect web downloads, so a few things must be kept in mind.
The first is that the first four characters of the download file indicate the module being downloaded, and they correspond to a specific member in SIRIUS.LOAD,
as described in the Fast/Cram Installation Guide.
The correspondences between the first four characters in the downloaded object files and the members in SIRIUS.LOAD are:

<table cellpadding=6>
<tr><td>FCRM</td><td>FASTSVC</td></tr>
<tr><td>FCRI</td><td>IGCLM244</td></tr>
<tr><td>FCRR</td><td>FASTREP</td></tr>
<tr><td>FCRS</td><td>SNAPFAST</td></tr>
</table>

The following example JCL would create SIRIUS.LOAD load modules as described in the Fast/Cram Installation Guide.
This example assumes you uploaded the object files into library SIRIUS.LIB with member names of FCR*27.
If you uploaded to non-library datasets (that is, sequential datasets, not Partitioned Data Sets), then you will need a separate DD statement for each object file as well as appropriate INCLUDE statements for them, omitting the parentheses and member names.

Note: The Fast/CRAM modules must be linked using the RENT option.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FCRM27)
ENTRY FASTSVC
NAME FASTSVC(R)
INCLUDE LIB(FCRI27)
ENTRY FASTRLD
NAME IGCLM244(R)
INCLUDE LIB(FCRR27)
ENTRY FASTREP
NAME FASTREP(R)
INCLUDE LIB(FCRS27)
ENTRY SNAPFAST
NAME SNAPFAST(R)
/*
</code>

Unfortunately, the customization job is currently Fast/Cram release specific.
The following job is a sample customization job for Fast/Cram V2.7:

<code>
//FASTCUST JOB ,'Fast/CRAM',CLASS=A,MSGCLASS=A
//*
//* Customize FASTCRAM Version 2.7
//*
//* Install FASTCRAM in SYS1.LPALIB,
//* as a Type 3 or type 4 SVC, using an SVC
//* number of 250 and a subsystem name of SIRI.
//*
//ZAPS EXEC PGM=SIRZAP,PARM=NOVER
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DISP=SHR,DSN=SIRIUS.LOAD
//SYSIN DD *
* *********************************************************************
* ZAP THE SVC NUMBER INTO FASTRLD. *
* *********************************************************************
NAME FASTRLD FASTRLD
VER 0184 0A0D
REP 0184 0AFA * NEW SVC=250
* *********************************************************************
* ZAP THE SUBSYSTEM NAME AND SVC NUMBER INTO FASTSVC. *
* *********************************************************************
NAME FASTSVC FASTSVC
VER 1678 00007FFF
VER 167C C6C1E2E3 * CURRENT SUBSYSTEM=FAST
REP 167C E2C9D9C9 * NEW SUBSYSTEM=SIRI
VER 1688 0A0D
REP 1688 0AFA * NEW SVC=250
/*
</code>

No matter which subsystem name you choose, this subsystem name must be defined in IEFSSNxx in SYS1.PARMLIB.
It is strongly recommended that subsystem name "M204" not be used because that subsystem name is used for Model 204's standard CRAM implementations.
The subsystem can also be defined dynamically with the SETSSI command:

<code>
SETSSI ADD,SUBNAME=FAST
</code>

If you are downloading a release for which no sample customization job is listed here, or if you need more help with the installation, contact Rocket M204 support at +1.800.755.4222, or e-mail us at [mailto:m204support@rocketsoftware.com m204support@rocketsoftware.com].

===Where can more documentation be found?===
The primary source of documentation for Rocket M204 products is this wiki.

Downloading and installing Rocket M204 products

2014-09-04T21:21:40Z

Gary: /* How should the Sirius Mods object file be linked under CMS? */

==How can the above object files be downloaded?==
The object files can be downloaded by clicking on the link for the object file with the right mouse button.
This will (on most browsers) bring up a pop-up menu that will have an option Save Link As, Save target As, Save As, or something similar.
Select this option, and then set the appropriate target directory (and name if desired) for the file.
The object file will then be downloaded to the indicated location.

Alternatively, click the left mouse button on the link for an object file. This will result in the browser prompting the user whether the file should be saved, where it should be saved, and under what name.
Some browsers prompt for this information before the object file is actually downloaded; others prompt for it after.
Obviously, those that prompt after will present a considerable delay before the prompt.
Opera actually prompts as soon as it receives the file header but continues downloading while waiting for the user response.

Object files are customized for a particular site, simplifying the installation process.
Because of this, there may be a noticeable delay in processing a download request.
In addition, the downloaded object files can range in size from hundreds of kilobytes to perhaps 10 megabytes.

If an e-mail transfer is selected, the object deck will be e-mailed to the indicated e-mail address as an attachment.
The attachment should be saved to a local file and then uploaded to the mainframe exactly as if it had been downloaded directly.
Receiving the object deck via e-mail might take a little longer than downloading it directly, but it allows you to schedule a set of object to be sent to a different person in your organization.

==How can the object files be uploaded to the mainframe?==
Once the object files are downloaded to the workstation they must be uploaded to the z/OS, VM, or VSE system on the IBM mainframe.
Any file transfer mechanism can be used including FTP and IND$FILE, but regardless of the transfer mechanism some rules must be observed.

First, the object files contain binary data and hence must be transferred as binary.
That is, no translation from ASCII to EBCDIC must occur as a result of the upload.

Second, the format and LRECL of the file must be specified during the upload.
This is because most workstation systems (including Windows, Mac OS and Unix) do not have a concept of file formats and LRECL's.
This information would be lost if it were not specified during the upload.
The format of the uploaded file must be F under VM systems and FB under z/OS and VSE systems. The LRECL must be
80 on all systems and under z/OS and VSE the blocksize can be any multiple of 80 though 3120 is a common blocksize for object libraries.

When using FTP, the characteristics (RECFM, LRECL, and BLOCKSIZE) of the uploaded file can be set with the SITE and LOCSITE FTP commands.
The SITE command should be used if the FTP client is on the workstation and the server is on the mainframe.
In this case the SITE command might have to be sent as a "quote" to the mainframe.
How this is done depends on your workstation's FTP client.
The LOCSITE command should be used if the FTP client is on the mainframe and the server is on the workstation.

===Model 204 object library===
The Model 204 installation process entails creating a library (in z/OS, a Partitioned Data Set, or PDS), which is then used in subsequent steps to link the various Model 204 load modules.
The file which you have uploaded to the mainframe, typically as a sequential dataset (DSORG=PS in z/OS), is used as the <code>INP=</code> parameter to the following JCL PROC for a z/OS installation:

<pre>
//NEWOBJLB PROC TRK='320,50',BLK=6400
//*
//* Usage: //BLD EXEC NEWOBJLB,LIB=objectLibDsn,INP=inputStreamDsn
//*
//* Important note: The output object library (LIB=) is first deleted
//*
//* This proc creates an object library, using the input stream which
//* was downloaded from the Rocket Model 204 web site. After the
//* download, it must be un-zipped, and then FTP'd (BINARY, 80 byte
//* fixed length records) to a z/OS dataset.
//*
//* The FTP'd z/OS dataset is specified by the INP= parameter
//*
//* Note: If you thought you might want to, it's best not to try
//* to over-ride SYSIN with a DD *, because the input stream
//* contains JCL.
//*
//DEL EXEC PGM=IEFBR14
//DEL DD DSN=&LIB,DISP=(MOD,DELETE),UNIT=SYSDA,SPACE=(TRK,1)
//*
//BLDOBJLB EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD SYSOUT=A << Note: this output will contain on the order
//* of 160K lines or more
//SYSUT2 DD DISP=(NEW,CATLG),SPACE=(TRK,(&TRK,60),RLSE),
// UNIT=SYSDA,DCB=(DSORG=PO,LRECL=80,RECFM=FB,BLKSIZE=&BLK),
// DSN=&LIB
//SYSIN DD DISP=SHR,DSN=&INP
//*
// PEND
</pre>
For example, if you downloaded the input stream and then FTP'd it into <code>M204.V75.DOWNLOAD.OBJ</code>,
and the object library dataset is to be <code>M204.V75.OBJLIB</code>:
<pre>
//BLDOBJLB EXEC NEWOBJLB,
// INP=M204.V75.DOWNLOAD,
// LIB=M204.V75.OBJLIB

</pre>

The space allocation and block size are PROC parameters, but their defaults will work.
You can, of course, use any dataset name you want for the object library after <code>INP=</code> — note that in our documentation, we refer to the object library as ROKOB204.

===Other object files===
For products other than Model 204, the downloaded file is a single object file.
Under z/OS, you can upload an object file either as a member of a Partitioned Data Set (PDS) or as an individual sequential file.
A PDS is recommended as a good way to collect all your Rocket M204 object file uploads in one dataset, using the member name to show the product and version.

==Should maintenance be applied to the uploaded object files?==
When Rocket M204 products are downloaded, they will contain all of the current maintenance as well as all applicable authorization keys.
Thus no additional additional installation steps steps are required to install maintenance or authorization keys.
Subsequent fixes can be applied by downloading ZAPs and applying them, or by downloading a replacement object file and re-linking the appropriate load modules.

==How should the Model 204 load modules be linked under z/OS?==
The Model 204 object library you created contains object files, JCL, and link-edit control statements so that you can link the Model 204 load modules.
(This library, of course, has the DSNAME you chose — but in our documentation, we refer to the object library as ROKOB204).

One of the members of ROKOB204 is a text file named README, which includes a list of the Model 204 load modules, and, individual instructions for linking them.

For example, to link the ONLINE load module, there is a member named JZLONLN.
This basic JCL has simple instructions for using it.
One of the comments in the JCL is a link which you may follow for more [[M204_install#zOS_link_onl|detailed instructions]].

==What are the Sirius Mods?==
The Sirius Mods is a collection of functions and enhancements to the core Model 204 load module.
These enhancements are either products in and of themselves, or they are prerequisites for products which are written in User Language.
A site is authorized to download all of the Sirus Mods if it is licensed for any of the products that require these enhancements.
Your authorization key will then enable the appropriate set of products.

Products that require the Sirius Mods are:

* Fast/Backup
* Fast/Reload
* Fast/Unload User Language Interface
* Janus Network Security
* Janus Open Server
* Janus Open Client
* Janus SOAP
* Janus Specialty Data Store
* Janus TCP/IP Base
* Janus Web Server
* Japanese Functions
* SirDBA
* SirFact
* SirFile
* Sirius Performance Enhancements
* Sirius Performance Enhancements V2
* SirLib
* SirMon
* SirPro
* SirSafe
* SirScan
* SirTune
* SirXref
* Sir2000 Field Migration Facility
* Sir2000 User Language Tools
* Trusted Login Facility

You can determine which of these products your site is authorized for by examining <a href="https://m204.rocketsoftware.com/dlist">your customer profile</a>. After the Sirius Mods are installed, you can verify product authorizations by issuing the SIRIUS command in an Online running a load module that includes the Sirius&npsp;Mods.

==How should the Sirius Mods object file be linked under z/OS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
Under z/OS, an object deck can be re-linked with a load module.
In theory, this load module can already contain the Sirius Mods.
While this is generally OK if linking over the same release of the Sirius Mods, it is almost certainly a bad idea otherwise.
As such, it is a good idea to keep a load module without the Sirius Mods available for rebuilding a load module with the Sirius Mods.
The non-Sirius Mods load module should have all Rocket ZAPs applied, or these ZAPs should be applied after the re-link with the Sirius Mods object file.

Should Rocket provide replacement object files as part of their maintenance, these object files must never be linked ahead of the Sirius Mods object file.
This also means that replacement Rocket object files cannot simply be linked ahead of a load module containing the Sirius Mods without also linking the Sirius Mods object file ahead of the replacement object files from Rocket.

Both of the next two examples assume you uploaded the object file into library SIRIUS.LIB with a member name of SIR80074.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB. The module is linked into library SIRIUS.LOAD.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</code>

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB, along with replacement object decks for EVNU and SBFM, which were provided with Rocket maintenance and are in library M204.V7R4.FIXOBJ.
The module is linked into library SIRIUS.LOAD.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//M204FIX DD DSN=M204.V7R4.FIXOBJ,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204FIX(EVFM,SBFM)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</code>

==How should the Sirius Mods object file be linked under CMS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
This means, first, that the object file's filetype must conform to CMS conventions for object files.
The simplest way to ensure this is to use a filetype of TEXT for the object file under CMS.

To link with the Rocket-supplied M204GEN utility, the Model 204 load list must be modified to include the Sirius Mods object file.
This can be done by simply inserting a line with an "&1 &2" followed by the filename of the Sirius Mods object file before the name of any other object file in the load list.
The following is an example of the first few lines of an updated load list, where the Sirius Mods object file is called "SIR80074 TEXT".

<code>
* LOAD LIST FOR M204ONLN MODULE
* (&START IN MLNK)
&1 &2 SIR80074
&1 &2 MLNK
&1 &2 ACF2CMS
&1 &2 ANXV
&1 &2 APSY
&1 &2 APSZ
&1 &2 ARTH
. . . . .
</code>

Because the Sirius Mods dynamically adds hooks to the load module, Sirius recommends against using shared segments with the Sirius Mods.
If this is considered essential, contact Sirius Software technical support for help in building a load module with the Sirius Mods and shared segments.

An exec called LOADCONV is also available to automatically convert the loadlist, it can be <a href="download/loadconv.rex">downloaded here</a>.
Note that LOADCONV requires that the filename of the Sirius Mods object file be "SIROBJ" followed by the Model 204 release to which it
applies, as in "SIROBJ74".

If the M204GEN exec is being used, M204CCA PARMS needs to be edited.
First, in the M204GEN/DEFAULTS section, the ldrtbls value might need to be increased:

<code>
M204GEN:
DEFAULTS:
ldrtbls = 50
</code>

Also, the load module start needs to include the Sirius Mods so in the ONLINE/ONLN section the line

<code>
start.mod = MLNK$
</code>

needs to be changed to

<code>
start.mod = SLNK$
</code>

If you want to be able to generate a load module both with and without the Sirius Mods, you could copy the whole ONLINE section in M204CCA PARMS and call it something else, for example, SIRIUS, and change start.mod in that section.
Then, when you want to generate a load module with the Sirius Mods in it you'd simply type

<code>
M204GEN SIRIUS
</code>

===How should the Sirius Mods object file be linked under VSE?===
The Sirius Mods object file should be linked ahead of the Model 204 object files from Rocket. The example below shows an excerpt of the standard Rocket link JCL for an ONLINE.
To linkedit the online with the Sirius Mods, you must insert the include statement for the object module immediately after the PHASE statement.
In this example, the Sirius Mods object is named SIR80074.
If the Sirius Mods object module is in a separate library, the JCL should be modified to include that library in the SEARCH= paramter of the LIBDEF OBJ statement.
If you include any other object modules, they also must appear after the Sirius Mods object.

<code>
...
// LIBDEF PHASE,CATALOG=M204LIB.V7R4
// LIBDEF OBJ,SEARCH=M204LIB.V7R4
// OPTION CATAL
PHASE ONLINE,* REPLACE=YES
INCLUDE SIR80074
INCLUDE LKONLN
INCLUDE
ENTRY MAINTASK
/*
// EXEC LNKEDT
/*
/&
...
</code>

===How should the Fast/Unload object file be linked?===
The following z/OS JCL is an example of how one would link the Fast/Unload object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of FUN400.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FUN400)
ENTRY FUNLOAD
NAME FUNLOAD(R)
/*
</code>

Under CMS, the Fast/Unload object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a FUNLOAD load module.
In this example, it is assumed that the Fast/Unload object file has a filename of FUN400.

<code>
LOAD FUN400 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET FUNLOAD RLDSAVE
GENMOD FUNLOAD (FROM FUNL
</code>

===Why were there three object files for SirTune?===
Beginning with Version 7.0 of the Sirius Mods, all SirTune functionality has been merged into the Sirius Mods and so the standalone SirTune load modules are obsolete.

Prior to Version 7.0 of the Sirius Mods, however, SirTune consisted of three components.
The first component was called the SirTune Data Collector or simply SirTune.
This load module runs in the same address space as the Model 204 load module and collects data to be analyzed later.

The second component is called the SirTune Report Generator.
This load module is run independently of Model 204 and summarizes the data collected by SirTune into a report.

The third component is used only under CMS and is called the SirTune Data Logger.
It communicates with SirTune via IUCV and asynchronously logs SirTune data on a separate virtual machine.
It is used to get around some of the difficulties of doing asynchronous I/O under CMS.

In general, it is a good idea to be using the same versions of all three SirTune components though Sirius makes every effort to allow a newer SirTune Report Generator to produce reports from sample datasets created by older releases of SirTune.

===How should the SirTune object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNE104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNE104)
ENTRY COLLECT
NAME SIRTUNE(R)
/*
</code>

Under CMS, the SirTune object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNE load module.
In this example, it is assumed that the SirTune object file has a filename of TUNE104.

<code>
LOAD TUNE104 (FULLMAP NODUP ORIGIN 400000 AMODE 31 RESET COLLECT
GENMOD SIRTUNE (FROM COLL
</code>

===How should the SirTune Report Generator object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune Report Generator object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNR104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNR104)
ENTRY ANALYZE
NAME SIRTUNER(R)
/*
</code>

Under CMS, the SirTune Report Renerator object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNER load module.
In this example, it is assumed that the SirTune Report Generator object file has a filename of TUNR103.

<code>
LOAD TUNR103 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET ANALYZE
GENMOD SIRTUNER (FROM ANAL
</code>

===How should the SirTune Data Logger object file be linked?===
The SirTune data Logger is not used under z/OS.

Under CMS, the SirTune Data Logger object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNED load module.
In this example, it is assumed that the SirTune Data Logger object file has a filename of TUND104.

<code>
LOAD TUND104 (FULLMAP NODUP ORIGIN 30000 AMODE 24 RESET OUTCMS
GENMOD SIRTUNED (FROM OUTC
</code>

===How should the RockZap object file be linked?===
The following z/OS JCL is an example of how one would link the RockZap object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of ZAP106.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(ZAP106)
ENTRY SIRZAP
NAME SIRZAP(R)
/*
</code>

Under CMS, the SirZap object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRZAP load module.
In this example, it is assumed that the SirZap object file has a filename of ZAP106.

<code>
LOAD ZAP106 (FULLMAP NODUP ORIGIN 20000 AMODE 31 RESET SIRZAP
GENMOD SIRZAP (FROM APPL
</code>

===How should the SirAud object file be linked?===
The following z/OS JCL is an example of how one would link the SirAud object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of AUD102.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(AUD102)
ENTRY JMAIN
NAME SIRAUD(R)
/*
</code>

Under CMS, the SirAud object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRAUD load module.
In this example, it is assumed that the SirAud object file has a filename of AUD102.

<code>
LOAD AUD102 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET JMAIN
GENMOD SIRAUD (FROM JCONF
</code>

===How should the Fast/Cram object files be installed?===
Most of the documentation for Fast/Cram installation can be found in the <a href="https://m204.rocketsoftware.com/maint/download/CRAMR.PDF">
Fast/Cram Installation Guide</a>.
That manual is currently not updated to reflect web downloads, so a few things must be kept in mind.
The first is that the first four characters of the download file indicate the module being downloaded, and they correspond to a specific member in SIRIUS.LOAD,
as described in the Fast/Cram Installation Guide.
The correspondences between the first four characters in the downloaded object files and the members in SIRIUS.LOAD are:

<table cellpadding=6>
<tr><td>FCRM</td><td>FASTSVC</td></tr>
<tr><td>FCRI</td><td>IGCLM244</td></tr>
<tr><td>FCRR</td><td>FASTREP</td></tr>
<tr><td>FCRS</td><td>SNAPFAST</td></tr>
</table>

The following example JCL would create SIRIUS.LOAD load modules as described in the Fast/Cram Installation Guide.
This example assumes you uploaded the object files into library SIRIUS.LIB with member names of FCR*27.
If you uploaded to non-library datasets (that is, sequential datasets, not Partitioned Data Sets), then you will need a separate DD statement for each object file as well as appropriate INCLUDE statements for them, omitting the parentheses and member names.

Note: The Fast/CRAM modules must be linked using the RENT option.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FCRM27)
ENTRY FASTSVC
NAME FASTSVC(R)
INCLUDE LIB(FCRI27)
ENTRY FASTRLD
NAME IGCLM244(R)
INCLUDE LIB(FCRR27)
ENTRY FASTREP
NAME FASTREP(R)
INCLUDE LIB(FCRS27)
ENTRY SNAPFAST
NAME SNAPFAST(R)
/*
</code>

Unfortunately, the customization job is currently Fast/Cram release specific.
The following job is a sample customization job for Fast/Cram V2.7:

<code>
//FASTCUST JOB ,'Fast/CRAM',CLASS=A,MSGCLASS=A
//*
//* Customize FASTCRAM Version 2.7
//*
//* Install FASTCRAM in SYS1.LPALIB,
//* as a Type 3 or type 4 SVC, using an SVC
//* number of 250 and a subsystem name of SIRI.
//*
//ZAPS EXEC PGM=SIRZAP,PARM=NOVER
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DISP=SHR,DSN=SIRIUS.LOAD
//SYSIN DD *
* *********************************************************************
* ZAP THE SVC NUMBER INTO FASTRLD. *
* *********************************************************************
NAME FASTRLD FASTRLD
VER 0184 0A0D
REP 0184 0AFA * NEW SVC=250
* *********************************************************************
* ZAP THE SUBSYSTEM NAME AND SVC NUMBER INTO FASTSVC. *
* *********************************************************************
NAME FASTSVC FASTSVC
VER 1678 00007FFF
VER 167C C6C1E2E3 * CURRENT SUBSYSTEM=FAST
REP 167C E2C9D9C9 * NEW SUBSYSTEM=SIRI
VER 1688 0A0D
REP 1688 0AFA * NEW SVC=250
/*
</code>

No matter which subsystem name you choose, this subsystem name must be defined in IEFSSNxx in SYS1.PARMLIB.
It is strongly recommended that subsystem name "M204" not be used because that subsystem name is used for Model 204's standard CRAM implementations.
The subsystem can also be defined dynamically with the SETSSI command:

<code>
SETSSI ADD,SUBNAME=FAST
</code>

If you are downloading a release for which no sample customization job is listed here, or if you need more help with the installation, contact Rocket M204 support at +1.800.755.4222, or e-mail us at <a href="mailto:m204support@rocketsoftware.com">m204support@rocketsoftware.com</a>.

===Where can more documentation be found?===
The primary source of documentation for Rocket M204 products is this wiki.

Downloading and installing Rocket M204 products

2014-09-04T21:15:48Z

Gary: /* How should the Sirius Mods object file be linked under z/OS? */

==How can the above object files be downloaded?==
The object files can be downloaded by clicking on the link for the object file with the right mouse button.
This will (on most browsers) bring up a pop-up menu that will have an option Save Link As, Save target As, Save As, or something similar.
Select this option, and then set the appropriate target directory (and name if desired) for the file.
The object file will then be downloaded to the indicated location.

Alternatively, click the left mouse button on the link for an object file. This will result in the browser prompting the user whether the file should be saved, where it should be saved, and under what name.
Some browsers prompt for this information before the object file is actually downloaded; others prompt for it after.
Obviously, those that prompt after will present a considerable delay before the prompt.
Opera actually prompts as soon as it receives the file header but continues downloading while waiting for the user response.

Object files are customized for a particular site, simplifying the installation process.
Because of this, there may be a noticeable delay in processing a download request.
In addition, the downloaded object files can range in size from hundreds of kilobytes to perhaps 10 megabytes.

If an e-mail transfer is selected, the object deck will be e-mailed to the indicated e-mail address as an attachment.
The attachment should be saved to a local file and then uploaded to the mainframe exactly as if it had been downloaded directly.
Receiving the object deck via e-mail might take a little longer than downloading it directly, but it allows you to schedule a set of object to be sent to a different person in your organization.

==How can the object files be uploaded to the mainframe?==
Once the object files are downloaded to the workstation they must be uploaded to the z/OS, VM, or VSE system on the IBM mainframe.
Any file transfer mechanism can be used including FTP and IND$FILE, but regardless of the transfer mechanism some rules must be observed.

First, the object files contain binary data and hence must be transferred as binary.
That is, no translation from ASCII to EBCDIC must occur as a result of the upload.

Second, the format and LRECL of the file must be specified during the upload.
This is because most workstation systems (including Windows, Mac OS and Unix) do not have a concept of file formats and LRECL's.
This information would be lost if it were not specified during the upload.
The format of the uploaded file must be F under VM systems and FB under z/OS and VSE systems. The LRECL must be
80 on all systems and under z/OS and VSE the blocksize can be any multiple of 80 though 3120 is a common blocksize for object libraries.

When using FTP, the characteristics (RECFM, LRECL, and BLOCKSIZE) of the uploaded file can be set with the SITE and LOCSITE FTP commands.
The SITE command should be used if the FTP client is on the workstation and the server is on the mainframe.
In this case the SITE command might have to be sent as a "quote" to the mainframe.
How this is done depends on your workstation's FTP client.
The LOCSITE command should be used if the FTP client is on the mainframe and the server is on the workstation.

===Model 204 object library===
The Model 204 installation process entails creating a library (in z/OS, a Partitioned Data Set, or PDS), which is then used in subsequent steps to link the various Model 204 load modules.
The file which you have uploaded to the mainframe, typically as a sequential dataset (DSORG=PS in z/OS), is used as the <code>INP=</code> parameter to the following JCL PROC for a z/OS installation:

<pre>
//NEWOBJLB PROC TRK='320,50',BLK=6400
//*
//* Usage: //BLD EXEC NEWOBJLB,LIB=objectLibDsn,INP=inputStreamDsn
//*
//* Important note: The output object library (LIB=) is first deleted
//*
//* This proc creates an object library, using the input stream which
//* was downloaded from the Rocket Model 204 web site. After the
//* download, it must be un-zipped, and then FTP'd (BINARY, 80 byte
//* fixed length records) to a z/OS dataset.
//*
//* The FTP'd z/OS dataset is specified by the INP= parameter
//*
//* Note: If you thought you might want to, it's best not to try
//* to over-ride SYSIN with a DD *, because the input stream
//* contains JCL.
//*
//DEL EXEC PGM=IEFBR14
//DEL DD DSN=&LIB,DISP=(MOD,DELETE),UNIT=SYSDA,SPACE=(TRK,1)
//*
//BLDOBJLB EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD SYSOUT=A << Note: this output will contain on the order
//* of 160K lines or more
//SYSUT2 DD DISP=(NEW,CATLG),SPACE=(TRK,(&TRK,60),RLSE),
// UNIT=SYSDA,DCB=(DSORG=PO,LRECL=80,RECFM=FB,BLKSIZE=&BLK),
// DSN=&LIB
//SYSIN DD DISP=SHR,DSN=&INP
//*
// PEND
</pre>
For example, if you downloaded the input stream and then FTP'd it into <code>M204.V75.DOWNLOAD.OBJ</code>,
and the object library dataset is to be <code>M204.V75.OBJLIB</code>:
<pre>
//BLDOBJLB EXEC NEWOBJLB,
// INP=M204.V75.DOWNLOAD,
// LIB=M204.V75.OBJLIB

</pre>

The space allocation and block size are PROC parameters, but their defaults will work.
You can, of course, use any dataset name you want for the object library after <code>INP=</code> — note that in our documentation, we refer to the object library as ROKOB204.

===Other object files===
For products other than Model 204, the downloaded file is a single object file.
Under z/OS, you can upload an object file either as a member of a Partitioned Data Set (PDS) or as an individual sequential file.
A PDS is recommended as a good way to collect all your Rocket M204 object file uploads in one dataset, using the member name to show the product and version.

==Should maintenance be applied to the uploaded object files?==
When Rocket M204 products are downloaded, they will contain all of the current maintenance as well as all applicable authorization keys.
Thus no additional additional installation steps steps are required to install maintenance or authorization keys.
Subsequent fixes can be applied by downloading ZAPs and applying them, or by downloading a replacement object file and re-linking the appropriate load modules.

==How should the Model 204 load modules be linked under z/OS?==
The Model 204 object library you created contains object files, JCL, and link-edit control statements so that you can link the Model 204 load modules.
(This library, of course, has the DSNAME you chose — but in our documentation, we refer to the object library as ROKOB204).

One of the members of ROKOB204 is a text file named README, which includes a list of the Model 204 load modules, and, individual instructions for linking them.

For example, to link the ONLINE load module, there is a member named JZLONLN.
This basic JCL has simple instructions for using it.
One of the comments in the JCL is a link which you may follow for more [[M204_install#zOS_link_onl|detailed instructions]].

==What are the Sirius Mods?==
The Sirius Mods is a collection of functions and enhancements to the core Model 204 load module.
These enhancements are either products in and of themselves, or they are prerequisites for products which are written in User Language.
A site is authorized to download all of the Sirus Mods if it is licensed for any of the products that require these enhancements.
Your authorization key will then enable the appropriate set of products.

Products that require the Sirius Mods are:

* Fast/Backup
* Fast/Reload
* Fast/Unload User Language Interface
* Janus Network Security
* Janus Open Server
* Janus Open Client
* Janus SOAP
* Janus Specialty Data Store
* Janus TCP/IP Base
* Janus Web Server
* Japanese Functions
* SirDBA
* SirFact
* SirFile
* Sirius Performance Enhancements
* Sirius Performance Enhancements V2
* SirLib
* SirMon
* SirPro
* SirSafe
* SirScan
* SirTune
* SirXref
* Sir2000 Field Migration Facility
* Sir2000 User Language Tools
* Trusted Login Facility

You can determine which of these products your site is authorized for by examining <a href="https://m204.rocketsoftware.com/dlist">your customer profile</a>. After the Sirius Mods are installed, you can verify product authorizations by issuing the SIRIUS command in an Online running a load module that includes the Sirius&npsp;Mods.

==How should the Sirius Mods object file be linked under z/OS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
Under z/OS, an object deck can be re-linked with a load module.
In theory, this load module can already contain the Sirius Mods.
While this is generally OK if linking over the same release of the Sirius Mods, it is almost certainly a bad idea otherwise.
As such, it is a good idea to keep a load module without the Sirius Mods available for rebuilding a load module with the Sirius Mods.
The non-Sirius Mods load module should have all Rocket ZAPs applied, or these ZAPs should be applied after the re-link with the Sirius Mods object file.

Should Rocket provide replacement object files as part of their maintenance, these object files must never be linked ahead of the Sirius Mods object file.
This also means that replacement Rocket object files cannot simply be linked ahead of a load module containing the Sirius Mods without also linking the Sirius Mods object file ahead of the replacement object files from Rocket.

Both of the next two examples assume you uploaded the object file into library SIRIUS.LIB with a member name of SIR80074.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB. The module is linked into library SIRIUS.LOAD.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</code>

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB, along with replacement object decks for EVNU and SBFM, which were provided with Rocket maintenance and are in library M204.V7R4.FIXOBJ.
The module is linked into library SIRIUS.LOAD.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//M204FIX DD DSN=M204.V7R4.FIXOBJ,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204FIX(EVFM,SBFM)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</code>

==How should the Sirius Mods object file be linked under CMS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
This means, first, that the object file's filetype must conform to CMS conventions for object files.
The simplest way to ensure this is to use a filetype of TEXT for the object file under CMS.

To link with the Rocket-supplied M204GEN utility, the Model 204 load list must be modified to include the Sirius Mods object file.
This can be done by simply inserting a line with an "&1 &2" followed by the filename of the Sirius Mods object file before the name of any other object file in the load list.
The following is an example of the first few lines of an updated load list, where the Sirius Mods object file is called "SIR80074 TEXT".

<xmp>
* LOAD LIST FOR M204ONLN MODULE
* (&START IN MLNK)
&1 &2 SIR80074
&1 &2 MLNK
&1 &2 ACF2CMS
&1 &2 ANXV
&1 &2 APSY
&1 &2 APSZ
&1 &2 ARTH
. . . . .
</xmp>

Because the Sirius Mods dynamically adds hooks to the load module, Sirius recommends against using shared segments with the Sirius Mods.
If this is considered essential, contact Sirius Software technical support for help in building a load module with the Sirius Mods and shared segments.

An exec called LOADCONV is also available to automatically convert the loadlist, it can be <a href="download/loadconv.rex">downloaded here</a>.
Note that LOADCONV requires that the filename of the Sirius Mods object file be "SIROBJ" followed by the Model 204 release to which it
applies, as in "SIROBJ74".

If the M204GEN exec is being used, M204CCA PARMS needs to be edited.
First, in the M204GEN/DEFAULTS section, the ldrtbls value might need to be increased:

<xmp>
M204GEN:
DEFAULTS:
ldrtbls = 50
</xmp>

Also, the load module start needs to include the Sirius Mods so in the ONLINE/ONLN section the line

<xmp>
start.mod = MLNK$
</xmp>

needs to be changed to

<xmp>
start.mod = SLNK$
</xmp>

If you want to be able to generate a load module both with and without the Sirius Mods, you could copy the whole ONLINE section in M204CCA PARMS and call it something else, for example, SIRIUS, and change start.mod in that section.
Then, when you want to generate a load module with the Sirius Mods in it you'd simply type

<xmp>
M204GEN SIRIUS
</xmp>

===How should the Sirius Mods object file be linked under VSE?===
The Sirius Mods object file should be linked ahead of the Model 204 object files from Rocket. The example below shows an excerpt of the standard Rocket link JCL for an ONLINE.
To linkedit the online with the Sirius Mods, you must insert the include statement for the object module immediately after the PHASE statement.
In this example, the Sirius Mods object is named SIR80074.
If the Sirius Mods object module is in a separate library, the JCL should be modified to include that library in the SEARCH= paramter of the LIBDEF OBJ statement.
If you include any other object modules, they also must appear after the Sirius Mods object.

<xmp>
...
// LIBDEF PHASE,CATALOG=M204LIB.V7R4
// LIBDEF OBJ,SEARCH=M204LIB.V7R4
// OPTION CATAL
PHASE ONLINE,* REPLACE=YES
INCLUDE SIR80074
INCLUDE LKONLN
INCLUDE
ENTRY MAINTASK
/*
// EXEC LNKEDT
/*
/&
...
</xmp>

===How should the Fast/Unload object file be linked?===
The following z/OS JCL is an example of how one would link the Fast/Unload object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of FUN400.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FUN400)
ENTRY FUNLOAD
NAME FUNLOAD(R)
/*
</xmp>

Under CMS, the Fast/Unload object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a FUNLOAD load module.
In this example, it is assumed that the Fast/Unload object file has a filename of FUN400.

<xmp>
LOAD FUN400 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET FUNLOAD RLDSAVE
GENMOD FUNLOAD (FROM FUNL
</xmp>

===Why were there three object files for SirTune?===
Beginning with Version 7.0 of the Sirius Mods, all SirTune functionality has been merged into the Sirius Mods and so the standalone SirTune load modules are obsolete.

Prior to Version 7.0 of the Sirius Mods, however, SirTune consisted of three components.
The first component was called the SirTune Data Collector or simply SirTune.
This load module runs in the same address space as the Model 204 load module and collects data to be analyzed later.

The second component is called the SirTune Report Generator.
This load module is run independently of Model 204 and summarizes the data collected by SirTune into a report.

The third component is used only under CMS and is called the SirTune Data Logger.
It communicates with SirTune via IUCV and asynchronously logs SirTune data on a separate virtual machine.
It is used to get around some of the difficulties of doing asynchronous I/O under CMS.

In general, it is a good idea to be using the same versions of all three SirTune components though Sirius makes every effort to allow a newer SirTune Report Generator to produce reports from sample datasets created by older releases of SirTune.

===How should the SirTune object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNE104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNE104)
ENTRY COLLECT
NAME SIRTUNE(R)
/*
</xmp>

Under CMS, the SirTune object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNE load module.
In this example, it is assumed that the SirTune object file has a filename of TUNE104.

<xmp>
LOAD TUNE104 (FULLMAP NODUP ORIGIN 400000 AMODE 31 RESET COLLECT
GENMOD SIRTUNE (FROM COLL
</xmp>

===How should the SirTune Report Generator object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune Report Generator object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNR104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNR104)
ENTRY ANALYZE
NAME SIRTUNER(R)
/*
</xmp>

Under CMS, the SirTune Report Renerator object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNER load module.
In this example, it is assumed that the SirTune Report Generator object file has a filename of TUNR103.

<xmp>
LOAD TUNR103 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET ANALYZE
GENMOD SIRTUNER (FROM ANAL
</xmp>

===How should the SirTune Data Logger object file be linked?===
The SirTune data Logger is not used under z/OS.

Under CMS, the SirTune Data Logger object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNED load module.
In this example, it is assumed that the SirTune Data Logger object file has a filename of TUND104.

<xmp>
LOAD TUND104 (FULLMAP NODUP ORIGIN 30000 AMODE 24 RESET OUTCMS
GENMOD SIRTUNED (FROM OUTC
</xmp>

===How should the RockZap object file be linked?===
The following z/OS JCL is an example of how one would link the RockZap object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of ZAP106.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(ZAP106)
ENTRY SIRZAP
NAME SIRZAP(R)
/*
</xmp>

Under CMS, the SirZap object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRZAP load module.
In this example, it is assumed that the SirZap object file has a filename of ZAP106.

<xmp>
LOAD ZAP106 (FULLMAP NODUP ORIGIN 20000 AMODE 31 RESET SIRZAP
GENMOD SIRZAP (FROM APPL
</xmp>

===How should the SirAud object file be linked?===
The following z/OS JCL is an example of how one would link the SirAud object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of AUD102.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(AUD102)
ENTRY JMAIN
NAME SIRAUD(R)
/*
</xmp>

Under CMS, the SirAud object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRAUD load module.
In this example, it is assumed that the SirAud object file has a filename of AUD102.

<xmp>
LOAD AUD102 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET JMAIN
GENMOD SIRAUD (FROM JCONF
</xmp>

===How should the Fast/Cram object files be installed?===
Most of the documentation for Fast/Cram installation can be found in the <a href="https://m204.rocketsoftware.com/maint/download/CRAMR.PDF">
Fast/Cram Installation Guide</a>.
That manual is currently not updated to reflect web downloads, so a few things must be kept in mind.
The first is that the first four characters of the download file indicate the module being downloaded, and they correspond to a specific member in SIRIUS.LOAD,
as described in the Fast/Cram Installation Guide.
The correspondences between the first four characters in the downloaded object files and the members in SIRIUS.LOAD are:

<table cellpadding=6>
<tr><td>FCRM</td><td>FASTSVC</td></tr>
<tr><td>FCRI</td><td>IGCLM244</td></tr>
<tr><td>FCRR</td><td>FASTREP</td></tr>
<tr><td>FCRS</td><td>SNAPFAST</td></tr>
</table>

The following example JCL would create SIRIUS.LOAD load modules as described in the Fast/Cram Installation Guide.
This example assumes you uploaded the object files into library SIRIUS.LIB with member names of FCR*27.
If you uploaded to non-library datasets (that is, sequential datasets, not Partitioned Data Sets), then you will need a separate DD statement for each object file as well as appropriate INCLUDE statements for them, omitting the parentheses and member names.

Note: The Fast/CRAM modules must be linked using the RENT option.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FCRM27)
ENTRY FASTSVC
NAME FASTSVC(R)
INCLUDE LIB(FCRI27)
ENTRY FASTRLD
NAME IGCLM244(R)
INCLUDE LIB(FCRR27)
ENTRY FASTREP
NAME FASTREP(R)
INCLUDE LIB(FCRS27)
ENTRY SNAPFAST
NAME SNAPFAST(R)
/*
</xmp>

Unfortunately, the customization job is currently Fast/Cram release specific.
The following job is a sample customization job for Fast/Cram V2.7:

<xmp>
//FASTCUST JOB ,'Fast/CRAM',CLASS=A,MSGCLASS=A
//*
//* Customize FASTCRAM Version 2.7
//*
//* Install FASTCRAM in SYS1.LPALIB,
//* as a Type 3 or type 4 SVC, using an SVC
//* number of 250 and a subsystem name of SIRI.
//*
//ZAPS EXEC PGM=SIRZAP,PARM=NOVER
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DISP=SHR,DSN=SIRIUS.LOAD
//SYSIN DD *
* *********************************************************************
* ZAP THE SVC NUMBER INTO FASTRLD. *
* *********************************************************************
NAME FASTRLD FASTRLD
VER 0184 0A0D
REP 0184 0AFA * NEW SVC=250
* *********************************************************************
* ZAP THE SUBSYSTEM NAME AND SVC NUMBER INTO FASTSVC. *
* *********************************************************************
NAME FASTSVC FASTSVC
VER 1678 00007FFF
VER 167C C6C1E2E3 * CURRENT SUBSYSTEM=FAST
REP 167C E2C9D9C9 * NEW SUBSYSTEM=SIRI
VER 1688 0A0D
REP 1688 0AFA * NEW SVC=250
/*
</xmp>

No matter which subsystem name you choose, this subsystem name must be defined in IEFSSNxx in SYS1.PARMLIB.
It is strongly recommended that subsystem name "M204" not be used because that subsystem name is used for Model 204's standard CRAM implementations.
The subsystem can also be defined dynamically with the SETSSI command:

<xmp>
SETSSI ADD,SUBNAME=FAST
</xmp>

If you are downloading a release for which no sample customization job is listed here, or if you need more help with the installation, contact Rocket M204 support at +1.800.755.4222, or e-mail us at <a href="mailto:m204support@rocketsoftware.com">m204support@rocketsoftware.com</a>.

===Where can more documentation be found?===
The primary source of documentation for Rocket M204 products is this wiki.

Downloading and installing Rocket M204 products

2014-09-04T21:13:18Z

Gary: /* How should the Sirius Mods object file be linked under z/OS? */

==How can the above object files be downloaded?==
The object files can be downloaded by clicking on the link for the object file with the right mouse button.
This will (on most browsers) bring up a pop-up menu that will have an option Save Link As, Save target As, Save As, or something similar.
Select this option, and then set the appropriate target directory (and name if desired) for the file.
The object file will then be downloaded to the indicated location.

Alternatively, click the left mouse button on the link for an object file. This will result in the browser prompting the user whether the file should be saved, where it should be saved, and under what name.
Some browsers prompt for this information before the object file is actually downloaded; others prompt for it after.
Obviously, those that prompt after will present a considerable delay before the prompt.
Opera actually prompts as soon as it receives the file header but continues downloading while waiting for the user response.

Object files are customized for a particular site, simplifying the installation process.
Because of this, there may be a noticeable delay in processing a download request.
In addition, the downloaded object files can range in size from hundreds of kilobytes to perhaps 10 megabytes.

If an e-mail transfer is selected, the object deck will be e-mailed to the indicated e-mail address as an attachment.
The attachment should be saved to a local file and then uploaded to the mainframe exactly as if it had been downloaded directly.
Receiving the object deck via e-mail might take a little longer than downloading it directly, but it allows you to schedule a set of object to be sent to a different person in your organization.

==How can the object files be uploaded to the mainframe?==
Once the object files are downloaded to the workstation they must be uploaded to the z/OS, VM, or VSE system on the IBM mainframe.
Any file transfer mechanism can be used including FTP and IND$FILE, but regardless of the transfer mechanism some rules must be observed.

First, the object files contain binary data and hence must be transferred as binary.
That is, no translation from ASCII to EBCDIC must occur as a result of the upload.

Second, the format and LRECL of the file must be specified during the upload.
This is because most workstation systems (including Windows, Mac OS and Unix) do not have a concept of file formats and LRECL's.
This information would be lost if it were not specified during the upload.
The format of the uploaded file must be F under VM systems and FB under z/OS and VSE systems. The LRECL must be
80 on all systems and under z/OS and VSE the blocksize can be any multiple of 80 though 3120 is a common blocksize for object libraries.

When using FTP, the characteristics (RECFM, LRECL, and BLOCKSIZE) of the uploaded file can be set with the SITE and LOCSITE FTP commands.
The SITE command should be used if the FTP client is on the workstation and the server is on the mainframe.
In this case the SITE command might have to be sent as a "quote" to the mainframe.
How this is done depends on your workstation's FTP client.
The LOCSITE command should be used if the FTP client is on the mainframe and the server is on the workstation.

===Model 204 object library===
The Model 204 installation process entails creating a library (in z/OS, a Partitioned Data Set, or PDS), which is then used in subsequent steps to link the various Model 204 load modules.
The file which you have uploaded to the mainframe, typically as a sequential dataset (DSORG=PS in z/OS), is used as the <code>INP=</code> parameter to the following JCL PROC for a z/OS installation:

<pre>
//NEWOBJLB PROC TRK='320,50',BLK=6400
//*
//* Usage: //BLD EXEC NEWOBJLB,LIB=objectLibDsn,INP=inputStreamDsn
//*
//* Important note: The output object library (LIB=) is first deleted
//*
//* This proc creates an object library, using the input stream which
//* was downloaded from the Rocket Model 204 web site. After the
//* download, it must be un-zipped, and then FTP'd (BINARY, 80 byte
//* fixed length records) to a z/OS dataset.
//*
//* The FTP'd z/OS dataset is specified by the INP= parameter
//*
//* Note: If you thought you might want to, it's best not to try
//* to over-ride SYSIN with a DD *, because the input stream
//* contains JCL.
//*
//DEL EXEC PGM=IEFBR14
//DEL DD DSN=&LIB,DISP=(MOD,DELETE),UNIT=SYSDA,SPACE=(TRK,1)
//*
//BLDOBJLB EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD SYSOUT=A << Note: this output will contain on the order
//* of 160K lines or more
//SYSUT2 DD DISP=(NEW,CATLG),SPACE=(TRK,(&TRK,60),RLSE),
// UNIT=SYSDA,DCB=(DSORG=PO,LRECL=80,RECFM=FB,BLKSIZE=&BLK),
// DSN=&LIB
//SYSIN DD DISP=SHR,DSN=&INP
//*
// PEND
</pre>
For example, if you downloaded the input stream and then FTP'd it into <code>M204.V75.DOWNLOAD.OBJ</code>,
and the object library dataset is to be <code>M204.V75.OBJLIB</code>:
<pre>
//BLDOBJLB EXEC NEWOBJLB,
// INP=M204.V75.DOWNLOAD,
// LIB=M204.V75.OBJLIB

</pre>

The space allocation and block size are PROC parameters, but their defaults will work.
You can, of course, use any dataset name you want for the object library after <code>INP=</code> — note that in our documentation, we refer to the object library as ROKOB204.

===Other object files===
For products other than Model 204, the downloaded file is a single object file.
Under z/OS, you can upload an object file either as a member of a Partitioned Data Set (PDS) or as an individual sequential file.
A PDS is recommended as a good way to collect all your Rocket M204 object file uploads in one dataset, using the member name to show the product and version.

==Should maintenance be applied to the uploaded object files?==
When Rocket M204 products are downloaded, they will contain all of the current maintenance as well as all applicable authorization keys.
Thus no additional additional installation steps steps are required to install maintenance or authorization keys.
Subsequent fixes can be applied by downloading ZAPs and applying them, or by downloading a replacement object file and re-linking the appropriate load modules.

==How should the Model 204 load modules be linked under z/OS?==
The Model 204 object library you created contains object files, JCL, and link-edit control statements so that you can link the Model 204 load modules.
(This library, of course, has the DSNAME you chose — but in our documentation, we refer to the object library as ROKOB204).

One of the members of ROKOB204 is a text file named README, which includes a list of the Model 204 load modules, and, individual instructions for linking them.

For example, to link the ONLINE load module, there is a member named JZLONLN.
This basic JCL has simple instructions for using it.
One of the comments in the JCL is a link which you may follow for more [[M204_install#zOS_link_onl|detailed instructions]].

==What are the Sirius Mods?==
The Sirius Mods is a collection of functions and enhancements to the core Model 204 load module.
These enhancements are either products in and of themselves, or they are prerequisites for products which are written in User Language.
A site is authorized to download all of the Sirus Mods if it is licensed for any of the products that require these enhancements.
Your authorization key will then enable the appropriate set of products.

Products that require the Sirius Mods are:

* Fast/Backup
* Fast/Reload
* Fast/Unload User Language Interface
* Janus Network Security
* Janus Open Server
* Janus Open Client
* Janus SOAP
* Janus Specialty Data Store
* Janus TCP/IP Base
* Janus Web Server
* Japanese Functions
* SirDBA
* SirFact
* SirFile
* Sirius Performance Enhancements
* Sirius Performance Enhancements V2
* SirLib
* SirMon
* SirPro
* SirSafe
* SirScan
* SirTune
* SirXref
* Sir2000 Field Migration Facility
* Sir2000 User Language Tools
* Trusted Login Facility

You can determine which of these products your site is authorized for by examining <a href="https://m204.rocketsoftware.com/dlist">your customer profile</a>. After the Sirius Mods are installed, you can verify product authorizations by issuing the SIRIUS command in an Online running a load module that includes the Sirius&npsp;Mods.

==How should the Sirius Mods object file be linked under z/OS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
Under z/OS, an object deck can be re-linked with a load module.
In theory, this load module can already contain the Sirius Mods.
While this is generally OK if linking over the same release of the Sirius Mods, it is almost certainly a bad idea otherwise.
As such, it is a good idea to keep a load module without the Sirius Mods available for rebuilding a load module with the Sirius Mods.
The non-Sirius Mods load module should have all Rocket ZAPs applied, or these ZAPs should be applied after the re-link with the Sirius Mods object file.

Should Rocket provide replacement object files as part of their maintenance, these object files must never be linked ahead of the Sirius Mods object file.
This also means that replacement Rocket object files cannot simply be linked ahead of a load module containing the Sirius Mods without also linking the Sirius Mods object file ahead of the replacement object files from Rocket.

Both of the next two examples assume you uploaded the object file into library SIRIUS.LIB with a member name of SIR80074.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB. The module is linked into library SIRIUS.LOAD.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</code>

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB, along with replacement object decks for EVNU and SBFM, which were provided with Rocket maintenance and are in library M204.V7R4.FIXOBJ.
The module is linked into library SIRIUS.LOAD.

<code>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//M204FIX DD DSN=M204.V7R4.FIXOBJ,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204FIX(EVFM,SBFM)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</code>

==How should the Sirius Mods object file be linked under CMS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
This means, first, that the object file's filetype must conform to CMS conventions for object files.
The simplest way to ensure this is to use a filetype of TEXT for the object file under CMS.

To link with the Rocket-supplied M204GEN utility, the Model 204 load list must be modified to include the Sirius Mods object file.
This can be done by simply inserting a line with an "&1 &2" followed by the filename of the Sirius Mods object file before the name of any other object file in the load list.
The following is an example of the first few lines of an updated load list, where the Sirius Mods object file is called "SIR80074 TEXT".

<xmp>
* LOAD LIST FOR M204ONLN MODULE
* (&START IN MLNK)
&1 &2 SIR80074
&1 &2 MLNK
&1 &2 ACF2CMS
&1 &2 ANXV
&1 &2 APSY
&1 &2 APSZ
&1 &2 ARTH
. . . . .
</xmp>

Because the Sirius Mods dynamically adds hooks to the load module, Sirius recommends against using shared segments with the Sirius Mods.
If this is considered essential, contact Sirius Software technical support for help in building a load module with the Sirius Mods and shared segments.

An exec called LOADCONV is also available to automatically convert the loadlist, it can be <a href="download/loadconv.rex">downloaded here</a>.
Note that LOADCONV requires that the filename of the Sirius Mods object file be "SIROBJ" followed by the Model 204 release to which it
applies, as in "SIROBJ74".

If the M204GEN exec is being used, M204CCA PARMS needs to be edited.
First, in the M204GEN/DEFAULTS section, the ldrtbls value might need to be increased:

<xmp>
M204GEN:
DEFAULTS:
ldrtbls = 50
</xmp>

Also, the load module start needs to include the Sirius Mods so in the ONLINE/ONLN section the line

<xmp>
start.mod = MLNK$
</xmp>

needs to be changed to

<xmp>
start.mod = SLNK$
</xmp>

If you want to be able to generate a load module both with and without the Sirius Mods, you could copy the whole ONLINE section in M204CCA PARMS and call it something else, for example, SIRIUS, and change start.mod in that section.
Then, when you want to generate a load module with the Sirius Mods in it you'd simply type

<xmp>
M204GEN SIRIUS
</xmp>

===How should the Sirius Mods object file be linked under VSE?===
The Sirius Mods object file should be linked ahead of the Model 204 object files from Rocket. The example below shows an excerpt of the standard Rocket link JCL for an ONLINE.
To linkedit the online with the Sirius Mods, you must insert the include statement for the object module immediately after the PHASE statement.
In this example, the Sirius Mods object is named SIR80074.
If the Sirius Mods object module is in a separate library, the JCL should be modified to include that library in the SEARCH= paramter of the LIBDEF OBJ statement.
If you include any other object modules, they also must appear after the Sirius Mods object.

<xmp>
...
// LIBDEF PHASE,CATALOG=M204LIB.V7R4
// LIBDEF OBJ,SEARCH=M204LIB.V7R4
// OPTION CATAL
PHASE ONLINE,* REPLACE=YES
INCLUDE SIR80074
INCLUDE LKONLN
INCLUDE
ENTRY MAINTASK
/*
// EXEC LNKEDT
/*
/&
...
</xmp>

===How should the Fast/Unload object file be linked?===
The following z/OS JCL is an example of how one would link the Fast/Unload object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of FUN400.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FUN400)
ENTRY FUNLOAD
NAME FUNLOAD(R)
/*
</xmp>

Under CMS, the Fast/Unload object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a FUNLOAD load module.
In this example, it is assumed that the Fast/Unload object file has a filename of FUN400.

<xmp>
LOAD FUN400 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET FUNLOAD RLDSAVE
GENMOD FUNLOAD (FROM FUNL
</xmp>

===Why were there three object files for SirTune?===
Beginning with Version 7.0 of the Sirius Mods, all SirTune functionality has been merged into the Sirius Mods and so the standalone SirTune load modules are obsolete.

Prior to Version 7.0 of the Sirius Mods, however, SirTune consisted of three components.
The first component was called the SirTune Data Collector or simply SirTune.
This load module runs in the same address space as the Model 204 load module and collects data to be analyzed later.

The second component is called the SirTune Report Generator.
This load module is run independently of Model 204 and summarizes the data collected by SirTune into a report.

The third component is used only under CMS and is called the SirTune Data Logger.
It communicates with SirTune via IUCV and asynchronously logs SirTune data on a separate virtual machine.
It is used to get around some of the difficulties of doing asynchronous I/O under CMS.

In general, it is a good idea to be using the same versions of all three SirTune components though Sirius makes every effort to allow a newer SirTune Report Generator to produce reports from sample datasets created by older releases of SirTune.

===How should the SirTune object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNE104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNE104)
ENTRY COLLECT
NAME SIRTUNE(R)
/*
</xmp>

Under CMS, the SirTune object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNE load module.
In this example, it is assumed that the SirTune object file has a filename of TUNE104.

<xmp>
LOAD TUNE104 (FULLMAP NODUP ORIGIN 400000 AMODE 31 RESET COLLECT
GENMOD SIRTUNE (FROM COLL
</xmp>

===How should the SirTune Report Generator object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune Report Generator object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNR104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNR104)
ENTRY ANALYZE
NAME SIRTUNER(R)
/*
</xmp>

Under CMS, the SirTune Report Renerator object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNER load module.
In this example, it is assumed that the SirTune Report Generator object file has a filename of TUNR103.

<xmp>
LOAD TUNR103 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET ANALYZE
GENMOD SIRTUNER (FROM ANAL
</xmp>

===How should the SirTune Data Logger object file be linked?===
The SirTune data Logger is not used under z/OS.

Under CMS, the SirTune Data Logger object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNED load module.
In this example, it is assumed that the SirTune Data Logger object file has a filename of TUND104.

<xmp>
LOAD TUND104 (FULLMAP NODUP ORIGIN 30000 AMODE 24 RESET OUTCMS
GENMOD SIRTUNED (FROM OUTC
</xmp>

===How should the RockZap object file be linked?===
The following z/OS JCL is an example of how one would link the RockZap object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of ZAP106.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(ZAP106)
ENTRY SIRZAP
NAME SIRZAP(R)
/*
</xmp>

Under CMS, the SirZap object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRZAP load module.
In this example, it is assumed that the SirZap object file has a filename of ZAP106.

<xmp>
LOAD ZAP106 (FULLMAP NODUP ORIGIN 20000 AMODE 31 RESET SIRZAP
GENMOD SIRZAP (FROM APPL
</xmp>

===How should the SirAud object file be linked?===
The following z/OS JCL is an example of how one would link the SirAud object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of AUD102.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(AUD102)
ENTRY JMAIN
NAME SIRAUD(R)
/*
</xmp>

Under CMS, the SirAud object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRAUD load module.
In this example, it is assumed that the SirAud object file has a filename of AUD102.

<xmp>
LOAD AUD102 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET JMAIN
GENMOD SIRAUD (FROM JCONF
</xmp>

===How should the Fast/Cram object files be installed?===
Most of the documentation for Fast/Cram installation can be found in the <a href="https://m204.rocketsoftware.com/maint/download/CRAMR.PDF">
Fast/Cram Installation Guide</a>.
That manual is currently not updated to reflect web downloads, so a few things must be kept in mind.
The first is that the first four characters of the download file indicate the module being downloaded, and they correspond to a specific member in SIRIUS.LOAD,
as described in the Fast/Cram Installation Guide.
The correspondences between the first four characters in the downloaded object files and the members in SIRIUS.LOAD are:

<table cellpadding=6>
<tr><td>FCRM</td><td>FASTSVC</td></tr>
<tr><td>FCRI</td><td>IGCLM244</td></tr>
<tr><td>FCRR</td><td>FASTREP</td></tr>
<tr><td>FCRS</td><td>SNAPFAST</td></tr>
</table>

The following example JCL would create SIRIUS.LOAD load modules as described in the Fast/Cram Installation Guide.
This example assumes you uploaded the object files into library SIRIUS.LIB with member names of FCR*27.
If you uploaded to non-library datasets (that is, sequential datasets, not Partitioned Data Sets), then you will need a separate DD statement for each object file as well as appropriate INCLUDE statements for them, omitting the parentheses and member names.

Note: The Fast/CRAM modules must be linked using the RENT option.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FCRM27)
ENTRY FASTSVC
NAME FASTSVC(R)
INCLUDE LIB(FCRI27)
ENTRY FASTRLD
NAME IGCLM244(R)
INCLUDE LIB(FCRR27)
ENTRY FASTREP
NAME FASTREP(R)
INCLUDE LIB(FCRS27)
ENTRY SNAPFAST
NAME SNAPFAST(R)
/*
</xmp>

Unfortunately, the customization job is currently Fast/Cram release specific.
The following job is a sample customization job for Fast/Cram V2.7:

<xmp>
//FASTCUST JOB ,'Fast/CRAM',CLASS=A,MSGCLASS=A
//*
//* Customize FASTCRAM Version 2.7
//*
//* Install FASTCRAM in SYS1.LPALIB,
//* as a Type 3 or type 4 SVC, using an SVC
//* number of 250 and a subsystem name of SIRI.
//*
//ZAPS EXEC PGM=SIRZAP,PARM=NOVER
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DISP=SHR,DSN=SIRIUS.LOAD
//SYSIN DD *
* *********************************************************************
* ZAP THE SVC NUMBER INTO FASTRLD. *
* *********************************************************************
NAME FASTRLD FASTRLD
VER 0184 0A0D
REP 0184 0AFA * NEW SVC=250
* *********************************************************************
* ZAP THE SUBSYSTEM NAME AND SVC NUMBER INTO FASTSVC. *
* *********************************************************************
NAME FASTSVC FASTSVC
VER 1678 00007FFF
VER 167C C6C1E2E3 * CURRENT SUBSYSTEM=FAST
REP 167C E2C9D9C9 * NEW SUBSYSTEM=SIRI
VER 1688 0A0D
REP 1688 0AFA * NEW SVC=250
/*
</xmp>

No matter which subsystem name you choose, this subsystem name must be defined in IEFSSNxx in SYS1.PARMLIB.
It is strongly recommended that subsystem name "M204" not be used because that subsystem name is used for Model 204's standard CRAM implementations.
The subsystem can also be defined dynamically with the SETSSI command:

<xmp>
SETSSI ADD,SUBNAME=FAST
</xmp>

If you are downloading a release for which no sample customization job is listed here, or if you need more help with the installation, contact Rocket M204 support at +1.800.755.4222, or e-mail us at <a href="mailto:m204support@rocketsoftware.com">m204support@rocketsoftware.com</a>.

===Where can more documentation be found?===
The primary source of documentation for Rocket M204 products is this wiki.

Downloading and installing Rocket M204 products

2014-09-04T20:39:58Z

Gary: Created page with "==How can the above object files be downloaded?== The object files can be downloaded by clicking on the link for the object file with the right mouse button. This will..."

==How can the above object files be downloaded?==
The object files can be downloaded by clicking on the link for the object file with the right mouse button.
This will (on most browsers) bring up a pop-up menu that will have an option Save Link As, Save target As, Save As, or something similar.
Select this option, and then set the appropriate target directory (and name if desired) for the file.
The object file will then be downloaded to the indicated location.

Alternatively, click the left mouse button on the link for an object file. This will result in the browser prompting the user whether the file should be saved, where it should be saved, and under what name.
Some browsers prompt for this information before the object file is actually downloaded; others prompt for it after.
Obviously, those that prompt after will present a considerable delay before the prompt.
Opera actually prompts as soon as it receives the file header but continues downloading while waiting for the user response.

Object files are customized for a particular site, simplifying the installation process.
Because of this, there may be a noticeable delay in processing a download request.
In addition, the downloaded object files can range in size from hundreds of kilobytes to perhaps 10 megabytes.

If an e-mail transfer is selected, the object deck will be e-mailed to the indicated e-mail address as an attachment.
The attachment should be saved to a local file and then uploaded to the mainframe exactly as if it had been downloaded directly.
Receiving the object deck via e-mail might take a little longer than downloading it directly, but it allows you to schedule a set of object to be sent to a different person in your organization.

==How can the object files be uploaded to the mainframe?==
Once the object files are downloaded to the workstation they must be uploaded to the z/OS, VM, or VSE system on the IBM mainframe.
Any file transfer mechanism can be used including FTP and IND$FILE, but regardless of the transfer mechanism some rules must be observed.

First, the object files contain binary data and hence must be transferred as binary.
That is, no translation from ASCII to EBCDIC must occur as a result of the upload.

Second, the format and LRECL of the file must be specified during the upload.
This is because most workstation systems (including Windows, Mac OS and Unix) do not have a concept of file formats and LRECL's.
This information would be lost if it were not specified during the upload.
The format of the uploaded file must be F under VM systems and FB under z/OS and VSE systems. The LRECL must be
80 on all systems and under z/OS and VSE the blocksize can be any multiple of 80 though 3120 is a common blocksize for object libraries.

When using FTP, the characteristics (RECFM, LRECL, and BLOCKSIZE) of the uploaded file can be set with the SITE and LOCSITE FTP commands.
The SITE command should be used if the FTP client is on the workstation and the server is on the mainframe.
In this case the SITE command might have to be sent as a "quote" to the mainframe.
How this is done depends on your workstation's FTP client.
The LOCSITE command should be used if the FTP client is on the mainframe and the server is on the workstation.

===Model 204 object library===
The Model 204 installation process entails creating a library (in z/OS, a Partitioned Data Set, or PDS), which is then used in subsequent steps to link the various Model 204 load modules.
The file which you have uploaded to the mainframe, typically as a sequential dataset (DSORG=PS in z/OS), is used as the <code>INP=</code> parameter to the following JCL PROC for a z/OS installation:

<pre>
//NEWOBJLB PROC TRK='320,50',BLK=6400
//*
//* Usage: //BLD EXEC NEWOBJLB,LIB=objectLibDsn,INP=inputStreamDsn
//*
//* Important note: The output object library (LIB=) is first deleted
//*
//* This proc creates an object library, using the input stream which
//* was downloaded from the Rocket Model 204 web site. After the
//* download, it must be un-zipped, and then FTP'd (BINARY, 80 byte
//* fixed length records) to a z/OS dataset.
//*
//* The FTP'd z/OS dataset is specified by the INP= parameter
//*
//* Note: If you thought you might want to, it's best not to try
//* to over-ride SYSIN with a DD *, because the input stream
//* contains JCL.
//*
//DEL EXEC PGM=IEFBR14
//DEL DD DSN=&LIB,DISP=(MOD,DELETE),UNIT=SYSDA,SPACE=(TRK,1)
//*
//BLDOBJLB EXEC PGM=IEBUPDTE,PARM=NEW
//SYSPRINT DD SYSOUT=A << Note: this output will contain on the order
//* of 160K lines or more
//SYSUT2 DD DISP=(NEW,CATLG),SPACE=(TRK,(&TRK,60),RLSE),
// UNIT=SYSDA,DCB=(DSORG=PO,LRECL=80,RECFM=FB,BLKSIZE=&BLK),
// DSN=&LIB
//SYSIN DD DISP=SHR,DSN=&INP
//*
// PEND
</pre>
For example, if you downloaded the input stream and then FTP'd it into <code>M204.V75.DOWNLOAD.OBJ</code>,
and the object library dataset is to be <code>M204.V75.OBJLIB</code>:
<pre>
//BLDOBJLB EXEC NEWOBJLB,
// INP=M204.V75.DOWNLOAD,
// LIB=M204.V75.OBJLIB

</pre>

The space allocation and block size are PROC parameters, but their defaults will work.
You can, of course, use any dataset name you want for the object library after <code>INP=</code> — note that in our documentation, we refer to the object library as ROKOB204.

===Other object files===
For products other than Model 204, the downloaded file is a single object file.
Under z/OS, you can upload an object file either as a member of a Partitioned Data Set (PDS) or as an individual sequential file.
A PDS is recommended as a good way to collect all your Rocket M204 object file uploads in one dataset, using the member name to show the product and version.

==Should maintenance be applied to the uploaded object files?==
When Rocket M204 products are downloaded, they will contain all of the current maintenance as well as all applicable authorization keys.
Thus no additional additional installation steps steps are required to install maintenance or authorization keys.
Subsequent fixes can be applied by downloading ZAPs and applying them, or by downloading a replacement object file and re-linking the appropriate load modules.

==How should the Model 204 load modules be linked under z/OS?==
The Model 204 object library you created contains object files, JCL, and link-edit control statements so that you can link the Model 204 load modules.
(This library, of course, has the DSNAME you chose — but in our documentation, we refer to the object library as ROKOB204).

One of the members of ROKOB204 is a text file named README, which includes a list of the Model 204 load modules, and, individual instructions for linking them.

For example, to link the ONLINE load module, there is a member named JZLONLN.
This basic JCL has simple instructions for using it.
One of the comments in the JCL is a link which you may follow for more [[M204_install#zOS_link_onl|detailed instructions]].

==What are the Sirius Mods?==
The Sirius Mods is a collection of functions and enhancements to the core Model 204 load module.
These enhancements are either products in and of themselves, or they are prerequisites for products which are written in User Language.
A site is authorized to download all of the Sirus Mods if it is licensed for any of the products that require these enhancements.
Your authorization key will then enable the appropriate set of products.

Products that require the Sirius Mods are:

* Fast/Backup
* Fast/Reload
* Fast/Unload User Language Interface
* Janus Network Security
* Janus Open Server
* Janus Open Client
* Janus SOAP
* Janus Specialty Data Store
* Janus TCP/IP Base
* Janus Web Server
* Japanese Functions
* SirDBA
* SirFact
* SirFile
* Sirius Performance Enhancements
* Sirius Performance Enhancements V2
* SirLib
* SirMon
* SirPro
* SirSafe
* SirScan
* SirTune
* SirXref
* Sir2000 Field Migration Facility
* Sir2000 User Language Tools
* Trusted Login Facility

You can determine which of these products your site is authorized for by examining <a href="https://m204.rocketsoftware.com/dlist">your customer profile</a>. After the Sirius Mods are installed, you can verify product authorizations by issuing the SIRIUS command in an Online running a load module that includes the Sirius&npsp;Mods.

==How should the Sirius Mods object file be linked under z/OS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
Under z/OS, an object deck can be re-linked with a load module.
In theory, this load module can already contain the Sirius Mods.
While this is generally OK if linking over the same release of the Sirius Mods, it is almost certainly a bad idea otherwise.
As such, it is a good idea to keep a load module without the Sirius Mods available for rebuilding a load module with the Sirius Mods.
The non-Sirius Mods load module should have all Rocket ZAPs applied, or these ZAPs should be applied after the re-link with the Sirius Mods object file.

Should Rocket provide replacement object files as part of their maintenance, these object files must never be linked ahead of the Sirius Mods object file.
This also means that replacement Rocket object files cannot simply be linked ahead of a load module containing the Sirius Mods without also linking the Sirius Mods object file ahead of the replacement object files from Rocket.

Both of the next two examples assume you uploaded the object file into library SIRIUS.LIB with a member name of SIR80074.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB. The module is linked into library SIRIUS.LOAD.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</xmp>

The following JCL is an example of how you would link the Sirius Mods object file with a standard Model 204 load module called ONLINE in
library M204.V7R4.LOADLIB, along with replacement object decks for EVNU and SBFM, which were provided with Rocket maintenance and are in library M204.V7R4.FIXOBJ.
The module is linked into library SIRIUS.LOAD.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='LIST,LET,MAP,SIZE=(2048K,512K),RMODE=ANY,AC=1'
//SYSPRINT DD SYSOUT=*
//M204LOAD DD DSN=M204.V7R4.LOADLIB,DISP=SHR
//M204FIX DD DSN=M204.V7R4.FIXOBJ,DISP=SHR
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(SIR80074)
INCLUDE M204FIX(EVFM,SBFM)
INCLUDE M204LOAD(ONLINE)
ENTRY MAINTASK
NAME ONLINE(R)
/*
</xmp>

==How should the Sirius Mods object file be linked under CMS?==
The Sirius Mods object file should be linked ahead of the Model 204 object modules from Rocket.
This means, first, that the object file's filetype must conform to CMS conventions for object files.
The simplest way to ensure this is to use a filetype of TEXT for the object file under CMS.

To link with the Rocket-supplied M204GEN utility, the Model 204 load list must be modified to include the Sirius Mods object file.
This can be done by simply inserting a line with an "&1 &2" followed by the filename of the Sirius Mods object file before the name of any other object file in the load list.
The following is an example of the first few lines of an updated load list, where the Sirius Mods object file is called "SIR80074 TEXT".

<xmp>
* LOAD LIST FOR M204ONLN MODULE
* (&START IN MLNK)
&1 &2 SIR80074
&1 &2 MLNK
&1 &2 ACF2CMS
&1 &2 ANXV
&1 &2 APSY
&1 &2 APSZ
&1 &2 ARTH
. . . . .
</xmp>

Because the Sirius Mods dynamically adds hooks to the load module, Sirius recommends against using shared segments with the Sirius Mods.
If this is considered essential, contact Sirius Software technical support for help in building a load module with the Sirius Mods and shared segments.

An exec called LOADCONV is also available to automatically convert the loadlist, it can be <a href="download/loadconv.rex">downloaded here</a>.
Note that LOADCONV requires that the filename of the Sirius Mods object file be "SIROBJ" followed by the Model 204 release to which it
applies, as in "SIROBJ74".

If the M204GEN exec is being used, M204CCA PARMS needs to be edited.
First, in the M204GEN/DEFAULTS section, the ldrtbls value might need to be increased:

<xmp>
M204GEN:
DEFAULTS:
ldrtbls = 50
</xmp>

Also, the load module start needs to include the Sirius Mods so in the ONLINE/ONLN section the line

<xmp>
start.mod = MLNK$
</xmp>

needs to be changed to

<xmp>
start.mod = SLNK$
</xmp>

If you want to be able to generate a load module both with and without the Sirius Mods, you could copy the whole ONLINE section in M204CCA PARMS and call it something else, for example, SIRIUS, and change start.mod in that section.
Then, when you want to generate a load module with the Sirius Mods in it you'd simply type

<xmp>
M204GEN SIRIUS
</xmp>

===How should the Sirius Mods object file be linked under VSE?===
The Sirius Mods object file should be linked ahead of the Model 204 object files from Rocket. The example below shows an excerpt of the standard Rocket link JCL for an ONLINE.
To linkedit the online with the Sirius Mods, you must insert the include statement for the object module immediately after the PHASE statement.
In this example, the Sirius Mods object is named SIR80074.
If the Sirius Mods object module is in a separate library, the JCL should be modified to include that library in the SEARCH= paramter of the LIBDEF OBJ statement.
If you include any other object modules, they also must appear after the Sirius Mods object.

<xmp>
...
// LIBDEF PHASE,CATALOG=M204LIB.V7R4
// LIBDEF OBJ,SEARCH=M204LIB.V7R4
// OPTION CATAL
PHASE ONLINE,* REPLACE=YES
INCLUDE SIR80074
INCLUDE LKONLN
INCLUDE
ENTRY MAINTASK
/*
// EXEC LNKEDT
/*
/&
...
</xmp>

===How should the Fast/Unload object file be linked?===
The following z/OS JCL is an example of how one would link the Fast/Unload object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of FUN400.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FUN400)
ENTRY FUNLOAD
NAME FUNLOAD(R)
/*
</xmp>

Under CMS, the Fast/Unload object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a FUNLOAD load module.
In this example, it is assumed that the Fast/Unload object file has a filename of FUN400.

<xmp>
LOAD FUN400 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET FUNLOAD RLDSAVE
GENMOD FUNLOAD (FROM FUNL
</xmp>

===Why were there three object files for SirTune?===
Beginning with Version 7.0 of the Sirius Mods, all SirTune functionality has been merged into the Sirius Mods and so the standalone SirTune load modules are obsolete.

Prior to Version 7.0 of the Sirius Mods, however, SirTune consisted of three components.
The first component was called the SirTune Data Collector or simply SirTune.
This load module runs in the same address space as the Model 204 load module and collects data to be analyzed later.

The second component is called the SirTune Report Generator.
This load module is run independently of Model 204 and summarizes the data collected by SirTune into a report.

The third component is used only under CMS and is called the SirTune Data Logger.
It communicates with SirTune via IUCV and asynchronously logs SirTune data on a separate virtual machine.
It is used to get around some of the difficulties of doing asynchronous I/O under CMS.

In general, it is a good idea to be using the same versions of all three SirTune components though Sirius makes every effort to allow a newer SirTune Report Generator to produce reports from sample datasets created by older releases of SirTune.

===How should the SirTune object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNE104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNE104)
ENTRY COLLECT
NAME SIRTUNE(R)
/*
</xmp>

Under CMS, the SirTune object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNE load module.
In this example, it is assumed that the SirTune object file has a filename of TUNE104.

<xmp>
LOAD TUNE104 (FULLMAP NODUP ORIGIN 400000 AMODE 31 RESET COLLECT
GENMOD SIRTUNE (FROM COLL
</xmp>

===How should the SirTune Report Generator object file be linked?===
The following z/OS JCL is an example of how one would link the SirTune Report Generator object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of TUNR104.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(TUNR104)
ENTRY ANALYZE
NAME SIRTUNER(R)
/*
</xmp>

Under CMS, the SirTune Report Renerator object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNER load module.
In this example, it is assumed that the SirTune Report Generator object file has a filename of TUNR103.

<xmp>
LOAD TUNR103 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET ANALYZE
GENMOD SIRTUNER (FROM ANAL
</xmp>

===How should the SirTune Data Logger object file be linked?===
The SirTune data Logger is not used under z/OS.

Under CMS, the SirTune Data Logger object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRTUNED load module.
In this example, it is assumed that the SirTune Data Logger object file has a filename of TUND104.

<xmp>
LOAD TUND104 (FULLMAP NODUP ORIGIN 30000 AMODE 24 RESET OUTCMS
GENMOD SIRTUNED (FROM OUTC
</xmp>

===How should the RockZap object file be linked?===
The following z/OS JCL is an example of how one would link the RockZap object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of ZAP106.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(ZAP106)
ENTRY SIRZAP
NAME SIRZAP(R)
/*
</xmp>

Under CMS, the SirZap object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRZAP load module.
In this example, it is assumed that the SirZap object file has a filename of ZAP106.

<xmp>
LOAD ZAP106 (FULLMAP NODUP ORIGIN 20000 AMODE 31 RESET SIRZAP
GENMOD SIRZAP (FROM APPL
</xmp>

===How should the SirAud object file be linked?===
The following z/OS JCL is an example of how one would link the SirAud object file.
The module is linked into library SIRIUS.LOAD.
This example assumes you <a href='#objup'>uploaded</a> the object file into library SIRIUS.LIB with a member name of AUD102.
If you uploaded to a non-library dataset (that is, a sequential dataset, not a Partitioned Data Set), then you should omit the parentheses and member name after INCLUDE LIB.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=0'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(AUD102)
ENTRY JMAIN
NAME SIRAUD(R)
/*
</xmp>

Under CMS, the SirAud object file should be given a filetype of "TEXT".
The following commands can then be issued either directly or in an EXEC to build a SIRAUD load module.
In this example, it is assumed that the SirAud object file has a filename of AUD102.

<xmp>
LOAD AUD102 (FULLMAP NODUP ORIGIN 30000 AMODE 31 RESET JMAIN
GENMOD SIRAUD (FROM JCONF
</xmp>

===How should the Fast/Cram object files be installed?===
Most of the documentation for Fast/Cram installation can be found in the <a href="https://m204.rocketsoftware.com/maint/download/CRAMR.PDF">
Fast/Cram Installation Guide</a>.
That manual is currently not updated to reflect web downloads, so a few things must be kept in mind.
The first is that the first four characters of the download file indicate the module being downloaded, and they correspond to a specific member in SIRIUS.LOAD,
as described in the Fast/Cram Installation Guide.
The correspondences between the first four characters in the downloaded object files and the members in SIRIUS.LOAD are:

<table cellpadding=6>
<tr><td>FCRM</td><td>FASTSVC</td></tr>
<tr><td>FCRI</td><td>IGCLM244</td></tr>
<tr><td>FCRR</td><td>FASTREP</td></tr>
<tr><td>FCRS</td><td>SNAPFAST</td></tr>
</table>

The following example JCL would create SIRIUS.LOAD load modules as described in the Fast/Cram Installation Guide.
This example assumes you uploaded the object files into library SIRIUS.LIB with member names of FCR*27.
If you uploaded to non-library datasets (that is, sequential datasets, not Partitioned Data Sets), then you will need a separate DD statement for each object file as well as appropriate INCLUDE statements for them, omitting the parentheses and member names.

Note: The Fast/CRAM modules must be linked using the RENT option.

<xmp>
//JOB whatever
//LINK EXEC PGM=IEWL,REGION=0M,
// PARM='RENT,LIST,MAP,NCAL,SIZE=(2048K,512K),AMODE=31,RMODE=24,AC=1'
//SYSPRINT DD SYSOUT=*
//SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(2,1))
//LIB DD DSN=SIRIUS.LIB,DISP=SHR
//SYSLMOD DD DSN=SIRIUS.LOAD,DISP=SHR
//SYSLIN DD *
INCLUDE LIB(FCRM27)
ENTRY FASTSVC
NAME FASTSVC(R)
INCLUDE LIB(FCRI27)
ENTRY FASTRLD
NAME IGCLM244(R)
INCLUDE LIB(FCRR27)
ENTRY FASTREP
NAME FASTREP(R)
INCLUDE LIB(FCRS27)
ENTRY SNAPFAST
NAME SNAPFAST(R)
/*
</xmp>

Unfortunately, the customization job is currently Fast/Cram release specific.
The following job is a sample customization job for Fast/Cram V2.7:

<xmp>
//FASTCUST JOB ,'Fast/CRAM',CLASS=A,MSGCLASS=A
//*
//* Customize FASTCRAM Version 2.7
//*
//* Install FASTCRAM in SYS1.LPALIB,
//* as a Type 3 or type 4 SVC, using an SVC
//* number of 250 and a subsystem name of SIRI.
//*
//ZAPS EXEC PGM=SIRZAP,PARM=NOVER
//SYSPRINT DD SYSOUT=*
//SYSLIB DD DISP=SHR,DSN=SIRIUS.LOAD
//SYSIN DD *
* *********************************************************************
* ZAP THE SVC NUMBER INTO FASTRLD. *
* *********************************************************************
NAME FASTRLD FASTRLD
VER 0184 0A0D
REP 0184 0AFA * NEW SVC=250
* *********************************************************************
* ZAP THE SUBSYSTEM NAME AND SVC NUMBER INTO FASTSVC. *
* *********************************************************************
NAME FASTSVC FASTSVC
VER 1678 00007FFF
VER 167C C6C1E2E3 * CURRENT SUBSYSTEM=FAST
REP 167C E2C9D9C9 * NEW SUBSYSTEM=SIRI
VER 1688 0A0D
REP 1688 0AFA * NEW SVC=250
/*
</xmp>

No matter which subsystem name you choose, this subsystem name must be defined in IEFSSNxx in SYS1.PARMLIB.
It is strongly recommended that subsystem name "M204" not be used because that subsystem name is used for Model 204's standard CRAM implementations.
The subsystem can also be defined dynamically with the SETSSI command:

<xmp>
SETSSI ADD,SUBNAME=FAST
</xmp>

If you are downloading a release for which no sample customization job is listed here, or if you need more help with the installation, contact Rocket M204 support at +1.800.755.4222, or e-mail us at <a href="mailto:m204support@rocketsoftware.com">m204support@rocketsoftware.com</a>.

===Where can more documentation be found?===
The primary source of documentation for Rocket M204 products is this wiki.

Gary: /* Limitation of liability */

M204wiki provides users with online access to M204 product documentation and a
procedure to collaboratively contribute and edit product documentation content.
M204wiki is owned and operated by Rocket Software, Inc. and its affiliates ("Rocket" or "we").
These Terms of Use ("Agreement") between you and Rocket set
forth the terms on which we make M204wiki available to you, "You" meaning any
person or entity who uses M204wiki and/or posts User Content to M204wiki.
By using M204wiki and/or posting [[M204wiki:Terms of use#User Content|User Content]] you agree to be bound by the terms and
conditions of this Agreement.

==Proprietary materials and ownership==
M204wiki is the property of Rocket. Without limitation of the foregoing, all the text,
images, sound, music, marks, logos, compilations (meaning the collection,
arrangement and assembly of information) and other content on this website
other than User Content as defined below (collectively, the "Site Content"), and
all software embodied in M204wiki ("Software") is proprietary to us or to third
parties and are protected by copyright and other intellectual property laws.
Except as otherwise expressly permitted by this Agreement, any use, copying,
making derivative works, transmitting, posting, linking, deep linking, redistribution,
sale, decompilation, modification, reverse engineering, translation or disassembly
of the Software or Site Content (collectively, the "Rocket Property") is prohibited.
You may be subject to criminal or civil penalties for violation of this paragraph.

The marks Rocket and the Rocket Software logos are registered trademarks of Rocket Software, Inc.
Other products and service names might be registered or unregistered trademarks of Rocket,
and they may not be
used in connection with any service or products other than those provided by
Rocket, in any manner that is likely to cause confusion among Users, or in any
manner that disparages or discredits Rocket. M204wiki may also feature the
trademarks, service marks, and logos of Rocket or third parties, and each owner
retains all rights in such marks. Any use of such marks, or any others displayed
on M204wiki, will inure solely to the benefit of their respective owners.

==License to use M204wiki==
Rocket authorizes you to access, view and use M204wiki to further your
understanding of Rocket products. You may not remove any copyright, trademark
or other proprietary notices that have been placed on the Rocket Property.
Changing, copying, redistributing, republishing, uploading, posting, transmitting,
distributing or otherwise exploiting in any way the Rocket Property, or any portion
of the Rocket Property, is strictly prohibited without the prior written permission of
Rocket, unless this Agreement otherwise expressly allows you to do so.

You warrant and agree that your use of M204wiki will be consistent with this
Agreement and will not infringe or violate the rights of any other party or breach
any contract or legal duty to any other parties. You will comply with all applicable
laws, regulations and ordinances relating to M204wiki, the Rocket Property or your
use of them, and in using M204wiki you will not engage in any conduct that restricts
or inhibits any other person from using or enjoying M204wiki.

==User Content==
In connection with using M204wiki, you may be authorized to upload, post, or submit to M204wiki
screenshots, text, graphics, and other materials and information (collectively,
"User Content") pertinent to the purpose of M204wiki. The User Content remains
your property, and Rocket does not claim any ownership of the copyright or other
proprietary rights in such User Content. Notwithstanding the foregoing, you
agree to all of these:
<ul>
<li>You are publishing and making your User Content publicly available for viewing
by third parties on a non-confidential basis, your User Content may be
associated with your username and so will be attributable to you, third parties will
gain access to your User Content through M204wiki, and Rocket shall in no event be
liable to you for any use or misuse of your User Content by any third party;
<li>You grant Rocket a worldwide, non-exclusive, perpetual, irrevocable, royalty-free,
transferable license, with right to sublicense through multiple tiers, to copy,
edit, modify, use, publish, distribute, prepare derivative works, publicly perform,
publicly display and otherwise exploit the User Content in connection with
operation of M204wiki, promotion of Rocket products and services, and any other
purposes reasonably related to using M204wiki and participation in promotions and
advertising of Rocket and its partners.
<li>All users of M204wiki have the right to access your User Content, and to copy,
modify, use, publish, distribute, prepare derivative works, publicly perform,
publicly display and otherwise exploit the User Content for personal, non-commercial use.
</ul>

==Restrictions==
You agree to not use M204wiki to do any of the following:
<ol class="low-al">
<li>Upload, post, email, transmit or otherwise make available any User Content
that is unlawful, harmful, threatening, abusive, harassing, tortious, defamatory,
vulgar, obscene, libelous, invasive of another's privacy, hateful, or racially,
ethnically or otherwise objectionable;
<li>Upload, post, email, transmit or otherwise make available any User Content
that you do not have a right to make available under any law or under contractual
or fiduciary relationships (such as inside information, proprietary and confidential
information learned or disclosed as part of employment relationships or under
nondisclosure agreements);
<li>Upload, post, email, transmit or otherwise make available any User Content
that infringes any patent, trademark, trade secret, copyright or other proprietary
rights ("Rights") of any party;
<li>Upload, post, email, transmit or otherwise make available any unsolicited or
unauthorized advertising, promotional materials, "junk mail," "spam," "chain
letters," "pyramid schemes," or any other form of solicitation;
<li>Harm minors in any way;
<li>Upload, post, email, transmit or otherwise make available any material that
contains software viruses or any other computer code, files or programs
designed to interrupt, destroy or limit the functionality of any computer software
or hardware or telecommunications equipment;
<li>Interfere with or disrupt M204wiki or servers or networks connected to M204wiki, or
disobey any requirements, procedures, policies or regulations of networks
connected to M204wiki;
<li>Intentionally or unintentionally violate any applicable local, state, national or
international law;
<li>Provide material support or resources (or to conceal or disguise the nature,
location, source, or ownership of material support or resources) to any
organization(s) designated by the United States government as a foreign terrorist
organization pursuant to section 219 of the Immigration and Nationality Act; or
<li>Collect or store personal data about other users.
</ol>

You acknowledge that Rocket may or may not pre-screen User Content, but that
Rocket shall have the right (but not the obligation) in its sole discretion for any
reason to pre-screen, refuse, delete, or move any User Content that is available
via M204wiki. Without limiting the foregoing, Rocket shall have the right to remove
any User Content that violates this Agreement or is otherwise objectionable. You
agree that you must evaluate, and bear all risks associated with, the use of any
User Content, including any reliance on the accuracy, completeness, or
usefulness of such User Content.

==Limitation of content accuracy==
Insofar as M204wiki is a collaborative environment for documentation of Rocket
products that contains edits and contributions of content by users of
M204wiki other than Rocket, Rocket does not guarantee the accuracy, integrity or
quality of M204wiki Content. Under no circumstances will Rocket be liable in any way
for any User Content, including, but not limited to, for any errors or omissions in
any User Content, or for any loss or damage of any kind incurred as a result of
the use of any User Content posted, emailed, transmitted or otherwise made
available via M204wiki.

==Indemnity==
You agree to indemnify and hold Rocket, and its subsidiaries, affiliates, officers,
agents, co-branders or other partners, and employees, harmless from any claim,
demand, action, suit, proceeding, liability, losses, damages, costs and expenses,
including reasonable attorneys' fees, arising out of User Content you submit, post,
transmit or make available through M204wiki, your use of M204wiki, your connection
to M204wiki, your violation of this Agreement, or your violation of any rights of
another.

==DISCLAIMER OF WARRANTIES==
YOU EXPRESSLY UNDERSTAND AND AGREE THAT:
<ol class="low-al">
<li>YOUR USE OF M204WIKI IS AT YOUR SOLE RISK. M204WIKI IS PROVIDED
ON AN "AS IS" AND "AS AVAILABLE" BASIS. ROCKET EXPRESSLY
DISCLAIMS ALL WARRANTIES OF ANY KIND, WHETHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NON-INFRINGEMENT.

<li>ROCKET MAKES NO WARRANTY THAT (i) M204WIKI WILL MEET YOUR
REQUIREMENTS, (ii) M204WIKI WILL BE UNINTERRUPTED, TIMELY, SECURE,
OR ERROR-FREE, (iii) THE RESULTS THAT MAY BE OBTAINED FROM THE
USE OF M204WIKI WILL BE ACCURATE OR RELIABLE, (iv) THE QUALITY OF
ANY PRODUCTS, SERVICES, INFORMATION, OR OTHER MATERIAL
PURCHASED OR OBTAINED BY YOU THROUGH M204WIKI WILL MEET YOUR
EXPECTATIONS, (v) ANY ERRORS IN THE SOFTWARE WILL BE
CORRECTED, (vi) OR THAT THIS WEB SITE, ITS CONTENT, AND THE
SERVERS ON WHICH THE WEB SITE AND CONTENT ARE AVAILABLE ARE
FREE OF VIRUSES OR OTHER HARMFUL COMPONENTS.

<li>ANY MATERIAL DOWNLOADED OR OTHERWISE OBTAINED THROUGH
THE USE OF M204WIKI IS DONE AT YOUR OWN DISCRETION AND RISK AND
THAT YOU WILL BE SOLELY RESPONSIBLE FOR ANY DAMAGE TO YOUR
COMPUTER SYSTEM OR LOSS OF DATA THAT RESULTS FROM THE
DOWNLOAD OF ANY SUCH MATERIAL.

<li>NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN,
OBTAINED BY YOU FROM ROCKET OR THROUGH OR FROM M204WIKI SHALL
CREATE ANY WARRANTY NOT EXPRESSLY STATED IN THIS AGREEMENT.

<li>INFORMATION CREATED BY THIRD PARTIES THAT YOU MAY ACCESS
ON THE SITE OR THROUGH LINKS IS NOT ADOPTED OR ENDORSED BY
ROCKET AND REMAINS THE RESPONSIBILITY OF SUCH THIRD PARTIES.
</ol>

==LIMITATION OF LIABILITY==
YOU EXPRESSLY UNDERSTAND AND AGREE THAT ROCKET SHALL NOT BE
LIABLE TO YOU FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
CONSEQUENTIAL OR EXEMPLARY DAMAGES, INCLUDING BUT NOT
LIMITED TO, DAMAGES FOR LOSS OF PROFITS, GOODWILL, USE, DATA
OR OTHER INTANGIBLE LOSSES (EVEN IF ROCKET HAS BEEN ADVISED OF
THE POSSIBILITY OF SUCH DAMAGES), RESULTING FROM: (i) THE USE
OR THE INABILITY TO USE M204WIKI; (ii) THE COST OF PROCUREMENT OF
SUBSTITUTE GOODS AND SERVICES RESULTING FROM ANY GOODS,
DATA, INFORMATION OR SERVICES PURCHASED OR OBTAINED OR
MESSAGES RECEIVED OR TRANSACTIONS ENTERED INTO THROUGH OR
FROM M204WIKI; (iii) UNAUTHORIZED ACCESS TO OR ALTERATION OF
YOUR TRANSMISSIONS OR DATA; (iv) STATEMENTS OR CONDUCT OF
ANY THIRD PARTY ON M204WIKI; OR (v) ANY OTHER MATTER RELATING TO
M204WIKI.

==Digital Millennium Copyright Act==
Rocket complies with the provisions of the Digital Millennium Copyright Act
applicable to internet service providers (17 U.S.C. '512, as amended). If you
have any complaints or objections to material posted on M204wiki you may contact
our Designated Agent at the following address:
James Lapierre
Rocket Software, Inc.
77 Fourth Avenue, Suite 100
Waltham, MA 02451
Telephone: 781 684 2267
Email: JLapierre@rocketsoftware.com

Any notice alleging that materials hosted by or distributed through M204wiki infringe
intellectual property rights must include the following information:
<ol class="low-al">
<li>An electronic or physical signature of the person authorized to act on
behalf of the owner of the copyright or other right being infringed;
<li>A description of the copyrighted work or other intellectual property that you
claim has been infringed;
<li>A description of the material that you claim is infringing and where it is
located on M204wiki;
<li>Your address, telephone number, and email address;
<li>A statement by you that you have a good faith belief that the use of the
materials on M204wiki of which you are complaining is not authorized by the
copyright owner, its agent, or the law; and
<li>A statement by you that the above information in your notice is accurate
and that, under penalty of perjury, you are the copyright or intellectual property
owner or authorized to act on the copyright or intellectual property owner's behalf.

Counter notices

If material that you have posted to M204wiki has been removed or disabled, you
may file a counter notice pursuant to 17 U.S.C. '512 (g). To be effective, the
counter notice must be a written communication sent to the designated agent
address listed above that includes the following:
<li>A physical or electronic signature of the subscriber;
<li>Identification of the material that has been removed or to which access
has been disabled and the location at which the material appeared before it was
removed or access to it was disabled;
<li>A statement under penalty of perjury that you have a good faith belief that
the material was removed or disabled as a result of mistake or misidentification
of the material to be removed or disabled; and
<li>Your name, address, and telephone number, and a statement that you
consent to the jurisdiction of Federal District Court for the judicial district in which
the address is located or, if your address is outside of the United States, for any
judicial district in which Rocket may be found, and that you will accept service of
process from the person who provided notification under subsection 17 U.S.C.
'512 (c)(1)(C) or an agent of such person.
</ol>

==Modification and termination==
Rocket reserves the right at any time and from time to time to modify or
discontinue, temporarily or permanently, M204wiki (or any part thereof) with or
without notice. You agree that Rocket shall not be liable to you or to any third party
for any modification, suspension or discontinuance of M204wiki.

Rocket may change, add or remove any part of this Agreement, or any other terms
associated with the use of the site, at any time, by posting a notice of such
changes to the Terms of Use page of the web site. Any changes shall become
part of the Agreement and shall apply as soon as such a notice is posted. By
continuing to use M204wiki after the notice is posted, you are indicating your
acceptance of those changes.

Rocket reserves the right to refuse or discontinue access to M204wiki by any user for
non-compliance with this Agreement.

==General==
Except as otherwise expressly provided herein, this Agreement, including the
[[M204wiki:Privacy policy|Privacy policy]] and all other operating rules, policies and procedures that may be
published on M204wiki from time to time, sets forth the entire agreement between
you and Rocket regarding the use of M204wiki, and supersedes all prior promises,
agreements or representations, whether written or oral, regarding such subject
matter. This Agreement will be governed by and construed and enforced in
accordance with the substantive law of the Commonwealth of Massachusetts,
USA, without regard to its principles of conflicts of law.

No delay or omission by Rocket in exercising any of its rights occurring upon any
noncompliance or default by you with respect to any of the terms and conditions
of this Agreement will impair any such right or be construed to be a waiver
thereof, and a waiver by Rocket of any of the covenants, conditions or agreements
to be performed by you will not be construed to be a waiver of any succeeding
breach thereof or of any other covenant, condition or agreement hereof
contained. Any waiver of any right of Rocket under this Agreement must be given
in writing and signed on behalf of Rocket to be enforceable. If any provision of this
Agreement is found by a court of competent jurisdiction to be invalid or
unenforceable, then this Agreement will remain in full force and effect and will be
reformed to be valid and enforceable while reflecting the intent of the parties to
the greatest extent permitted by law.

Your registration, this Agreement and your rights and obligations hereunder are
not assignable or transferable by you to any third party without the prior written
consent of Rocket. We may assign this Agreement to any purchaser of the Rocket
business. This Agreement may be executed electronically, and your electronic
assent or use of the Service shall constitute execution of this Agreement. You
agree that the electronic text of this Agreement constitutes a writing and your
assent to the terms and conditions hereof constitutes a "signing" for all purposes.
Email to your registered email address shall constitute effective notice by Rocket
to you for all purposes under or in connection with this Agreement.

[[Category:Legal]]