m204wiki - User contributions [en]

IBM z/OS 2.2 PTF requirement

2018-06-05T14:36:13Z

Mlarocca:

If you use Horizon TCP/IP for sending and receiving between Model 204 applications, you will need to apply [http://www-01.ibm.com/support/docview.wss?uid=swg1PI52347 IBM PTF UI34846]. Without this fix, TCP/IP client connections for Model 204 cannot be initiated.

The above PTF only affects customers using our Horizon to Horizon TCP/IP communications product. For more detail on this product see [https://m204wiki.rocketsoftware.com/index.php/Model_204_intersystem_processing#TCP.2FIP_support Horizon TCP/IP support].

CREATE command: File

2018-04-24T19:16:24Z

Mlarocca: /* Usage notes */

==Summary==
<dl>
<dt>Privileges
<dd>Superuser
<dt>Function
<dd>Creates a <var class="product">Model 204</var> file
</dl>

==Syntax==
CREATE [FILE] [(FORMAT) | (NOFORMAT)] <var class="term">filename</var>
[FROM <var class="term">ddname</var> [,<var class="term">ddname</var>]...]
[PARAMETER <var class="term">parameter</var>=<var class="term">value</var> [,<var class="term">parameter</var>=<var class="term">value</var>]...]
[PARAMETER <var class="term">parameter</var>=<var class="term">value</var> [,<var class="term">parameter</var>=<var class="term">value</var>]...]
.
.
.
END


Where:
<table>
<tr>
<th>filename</th>
<td>The name of the <var class="product">Model 204</var> file that is being created (1 to 8 characters; 1 to 7 on DOS systems).
The file name cannot be FILE or GROUP and cannot start with CCA, SYS, OUT, TAPE, or a number. The only exception is CCASYS: it can be created in a single user run with the <var>[[SYSOPT parameter|SYSOPT]]</var> X’01’ bit turned off to prevent Model 204 from opening CCASYS to make it available for APSY.
Otherwise, <var class="term">filename</var> can contain only uppercase letters, numbers, and the following special characters:
<table>

<tr class="head"> <th>Special character name</th> <th>Keyboard symbol</th> </tr>

<tr> <th><var>At sign </var></th> <td>(@)</td> </tr>

<tr> <th><var>Pound sign </var></th> <td>(#)</td> </tr>

<tr> <th><var>Dollar sign </var></th> <td>($) (alternately displayed as £)</td> </tr>
</table>


The file name must be the ddname of the first or only data set in the file.
</td></tr>

<tr>
<th>ddname</th>
<td>The name of a data set from which to create the file; it is required when the file is being created from more than one data set. The first <var class="term">ddname</var> specified must match <var class="term">filename</var>.

<var class="term">ddname</var> cannot be longer than eight characters; if it is, the command is rejected and the following message is issued: 
M204.1903: %C EXCEEDS 8 CHARACTERS IN LENGTH


To allow a name of more than eight characters (although only the first eight characters will be used), set the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter to <code>10</code>.
</td>
</tr>

<tr>
<th>parameter=value</th>
<td><var class="product">Model 204</var> file parameters. Any number of PARAMETER statements can immediately follow the command, and each statement can contain as many parameters in any order as will fit on one input line. File parameters are optional. If you specify no values for the BSIZE, CSIZE, and DSIZE parameters, defaults are used. However, you can calculate and set values for parameters as described in [[Managing file and table sizes]].</td>
</tr>
</table>

===Syntax notes===
<ul>
<li>The <var>FROM</var> clause is optional for files containing a single data set.</li>

<li>If specified, the <var class="term">ddname</var> of the first data set must match <var class="term">filename</var>. You can use a continuation character to enter long data set lists in the <var>FROM</var> statement.</li>

<li><var>NO FORMAT</var> is a synonym for <var>NOFORMAT</var>.</li>

<li>A <var>CREATE</var> command must be concluded by an <var>END</var> statement.</li>
</ul>

==Example==
CREATE FILE PEOPLE
PARAMETER ATRPG=1, FVFPG=10, MVFPG=10
PARAMETER ASTRPPG=345
PARAMETER BSIZE=704, BRECPPG=23, BRESERVE=268
PARAMETER CSIZE=78, DSIZE=470
END


==Usage notes==

<var>CREATE FILE</var> creates a <var class="product">Model 204</var> file. It sets the file parameters and builds the File Control Table (FCT). It should be issued after the values for file parameters are calculated and data sets are allocated. After a file is created, it must be opened and initialized (see the [[OPEN FILE command]] and the [[INITIALIZE command]]). 

The default <var>FORMAT</var> option causes the <var>CREATE</var> command to physically format the disk space. <var>NOFORMAT</var> suppresses physical formatting of the disk. If one or more of the data sets in the file are new, use <var>FORMAT</var>.

If <var>NOFORMAT</var> is used and the disk space is unformatted, we will force formatting anyway and issue the following message. 

M204.0793: I/O ERROR FORCED FORMATTING


In the case of a multi-dataset file, we may not be able to detect that one of the datasets is unformatted. In this case, the initialize will fail with the message:

M204.2369: DKUPDT DISK WRITE FAILURE: 

<var>CREATE</var> establishes the file name and ddnames for all data sets in the file. Once a file is created, you can change the file name and ddname only by recreating the file or by running the [[RESTORE command]]. However, you can add new data sets to the file with the [[INCREASE command]].

When it processes <var>CREATE FILE</var>, <var class="product">Model 204</var> ends any update unit in progress and begins a [[File integrity and recovery#Model 204 update units|non-backoutable update unit]].


See [[Creating a file]] for more information about file creation and file parameters.

[[Category: Superuser commands]]
[[Category:Commands]]

Runtime environment for SQL processing

2017-11-09T19:17:35Z

Mlarocca: /* CCAIN parameters to support Model 204 SQL processing */

==Overview==
This topic discusses changes to the job or EXEC that brings up your Model 204 Online. These changes are required or recommended to support Model 204 SQL and Remote Command Line (RCL) processing. This topic also provides information about sizing SQL buffers.
You also need to specify DEFINE commands for Model 204 TCP/IP (Horizon). For more information, see:
[[DEFINE LINK command: Horizon for TCP/IP]]
[[DEFINE PROCESS command: Horizon for TCP/IP and VTAM]]
[[DEFINE PROCESSGROUP command: Horizon for TCP/IP]]

==SQL processing files==
The following table lists SQL-specific files you need to include in your Online environment.

Add DD statements or FILEDEFs for these files to the job that brings up your Model 204 Online. Model 204 installation or reinstallation allocates the files.

SQL files for Online environment
<table>
<tr class="head">
<th>File</th>
<th>Contents</th>
</tr>
<tr>
<td>CATPROC</td>
<td>Procedures and data: SOUL procedures to run [[SQL catalog reporting and querying|CCACATREPT]] subsystem and to create the CCACAT file for initial installation and reorganizations; and Help files for CCACATREPT.
Note: As of Model 204 version 7.5, these procedures and data are contained in M204PROC, and CATPROC is no longer a valid file.</td>
</tr>
<tr>
<td>CCACAT</td>
<td>Required file. Model 204 [[SQL catalog]] for storage of all SQL DDL definitions.
</td>
</tr>
<tr>
<td>TSFDATA</td>
<td>Model 204 file for work records that permit you to retain TSF ([[SQL DDL from the Table Specification Facility|CCATSF]] subsystem) working data across sessions.</td>
</tr>
<tr>
<td>TSFPROC</td>
<td>Procedures and data: SOUL procedures to run the CCATSF subsystem, and Help files for the TSF.
Note: As of Model 204 version 7.5, these procedures and data are contained in M204PROC, and TSFPROC is no longer a valid file.</td>
</tr>
</table>

==CCAIN parameters to support Model 204 SQL processing==
The following table summarizes the recommended values for CCAIN parameters that support Model 204 SQL processing. For complete details on what these parameters support and how to adjust their values, see the [[List of Model 204 parameters|list of Model 204 parameters]].


When any of these parameters are required for RCL processing, the SQL settings are used as defaults.
CCAIN parameters affected by SQL processing
<table>
<tr class="head">
<th>Parameter</th>
<th>Recommendation</th></tr>

<tr>
<td><var>[[CUSTOM parameter|CUSTOM]]</var> </td>
<td>Set to 8 to allow RCL clients to issue the <var>LOGIN</var> command. This allows users to logout and login without closing the current connection and opening a new one.</td></tr>

<tr><td><var>[[LCPDLST parameter|LCPDLST]]</var></td>
<td>Use the default, 2176</td></tr>

<tr><td><var>[[LHEAP parameter|LHEAP]]</var></td>
<td>Set to 200000, then monitor and adjust</td></tr>

<tr><td><var>[[LIBUFF parameter|LIBUFF]]</var></td>
<td>Set to 5000; adjust to match <var>SQLIQBSZ</var></td></tr>

<tr><td><var>[[LNTBL parameter|LNTBL]]</var></td>
<td>Monitor NTBL and adjust</td></tr>

<tr><td><var>[[LOBUFF parameter|LOBUFF]]</var></td>
<td>Set to 5000</td></tr>

<tr>
<td><var>[[LPDLST parameter|LPDLST]]</var></td>
<td>Set to 32760</td></tr>

<tr><td><var>[[LQTBL parameter|LQTBL]]</var></td>
<td>Monitor QTBL and adjust</td></tr>

<tr>
<td><var>[[LSTBL parameter|LSTBL]]</var></td>
<td>Monitor STBL and adjust</td></tr>

<tr>
<td><var>[[LTTBL parameter|LTTBL]]</var></td>
<td>Set to 2000, then monitor TTBL, then adjust</td></tr>

<tr>
<td><var>[[LVTBL parameter|LVTBL]]</var> </td>
<td>Monitor VTBL and adjust</td></tr>

<tr>
<td><var>[[MAXBUF parameter|MAXBUF]]</var>
</td>
<td>Minimum value is 18</td></tr>

<tr>
<td><var>[[MINBUF parameter|MINBUF]]</var> </td>
<td>Minimum value is 18. See <var>[[MINBUF parameter|MINBUF]]</var> for the formula used to calculate the appropriate value for <var>MINBUF</var> in SQL processing.</td></tr>

<tr>
<td><var>[[NSUBTKS parameter|NSUBTKS]]</var></td>
<td>Increase by 3 for first open Model 204 TCP/IP (Horizon) link; by 2 for each subsequent link</td></tr>

<tr>
<td><var>[[SERVSIZE parameter|SERVSIZE]]</var> </td>
<td>Initially set this to at least 350K and adjust. For processing SQL statements that are unusually large, the recommended value is between 600K and 700K.</td></tr>

<tr><td><var>[[SQLBSCAN parameter|SQLBSCAN]]</var> </td>
<td>Use default, then adjust</td></tr>

<tr><td><var>[[SQLBUFSZ parameter|SQLBUFSZ]]</var></td>
<td>Set to 100000 on first SQL IODEV line. RCL IODEV uses SQL IODEV setting (default).</td>
</tr><tr>

<td><var>[[SQLCNVER parameter|SQLCNVER]]</var> </td>
<td>Review the <var>SQLCNVER</var> 0 and 1 settings to choose what is best for your application.</td></tr>

<tr>
<td><var>[[SQLFILE parameter|SQLFILE]]</var></td>
<td>Set to 1 to have Model 204 SQL processing generate a unique file name for the file to which your <var>CREATE TABLE</var> table is mapped in the SQL catalog</td></tr>

<tr><td><var>[[SQLIQBSZ parameter|SQLIQBSZ]]</var></td>
<td>Set to 32752, then adjust</td></tr>

<tr><td><var>[[SQLLPLIM parameter|SQLLPLIM]]</var> </td>
<td>Use default, then adjust</td></tr>
</table>

===Handling SQL statements greater than 32K bytes===
When handling an SQL statement that is greater than 32K, you must consider the following parameters:
<ul>
<li>The <var>[[LCPDLST parameter|LCPDLST]]</var> is the length of the C pushdown list. If its value is not large enough, the error message invoked includes the name of the relevant parameter.</li>

<li>The <var>[[SQLBUFSZ parameter|SQLBUFSZ]]</var> is the buffer to collect the entire SQL statement. It must be slightly greater than the maximum size of the largest SQL statement, which is the value of SQLI in the audit trail. For example, set SQLBUFSZ=100000 to run a DDL statement that is 52K.</li>

<li>The <var>[[SQLIQBSZ parameter|SQLIQBSZ]]</var> is the buffer for the interface with IFAM. For example, set SQLIQBSZ=32752 to run an IFGET result that requires a buffer greater than 31K.</li>

<li>Other pertinent parameters to review are <var>[[LVTBL parameter|LVTBL]]</var>, <var>[[LHEAP parameter|LHEAP]]</var>, and <var>[[SERVSIZE parameter|SERVSIZE]]</var>. If their values are not large enough, the error message invoked includes the name of the relevant parameter.

To allow <var>LHEAP</var> and <var>LVTBL</var> to be as large as possible, conserve address space by setting the buffer size parameters as low as possible. Alternatively, you can place CCASERVR in memory to eliminate size restrictions on <var>SERVSIZE</var>.</li>
</ul>

==CCATEMP file size==

SQL query processing uses CCATEMP space for sorting rows and for storing subquery results. 

Depending on the amount of data being accessed, your typical CCATEMP requirements might increase. You can set CCATEMP as high as 16 million pages. Overallocating CCATEMP wastes disk space and uses excessive memory, so only allocate additional pages if necessary. 

==Defining SQL and RCL IODEV threads==

Model 204 requires a pool of threads to support server control of SQL connections. The system manager must define these threads in the CCAIN stream as part of the Online startup configuration.

For more information about CCAIN and IODEV threads, see [[Defining the user environment (CCAIN)|defining the user environment]].


You must define <var>IODEV</var> threads for all Connect★ configurations:
<ul>
<li><code>IODEV=19</code> defines a Model 204 TCP/IP SQL thread for TCP/IP. </li>

<li><code>IODEV=49</code> defines a Model 204 TCP/IP RCL thread for TCP/IP. </li>
</ul>

===Coding the IODEV line===
Your definition of an IODEV 19 or 49 thread involves the specification or adjustment of the <var>NOTHREAD</var>, <var>SQLBUFSZ</var>, and <var>LHEAP</var> parameters described in this section. For examples, see [[#Runtime examples|Runtime examples]].

====RCL and SQL multithreaded environment====
When defining IODEV=49 (RCL) and IODEV=19 (SQL) threads:
<ul>
<li>In the IODEV=49 line and in the IODEV=19, set the total number of concurrent threads (<var>NOTHREAD</var>) and identify the number of each thread.</li>

<li>In the IODEV=19, set other IODEV parameters such as <var>SQLBUFSZ</var>, <var>LHEAP</var>, <var>LIBUFF</var>, and <var>SQLIQBSZ</var>. The RCL thread uses these SQL thread settings as defaults. </li>
</ul>

====NOTHREAD====
You can insert one or more IODEV=19 or 49 lines in the CCAIN stream. On the first line defining the SQL or RCL thread, include the <var>NOTHREAD</var> parameter to indicate the number of threads to be allocated. The number of threads of types 19 and 49 is controlled by the CPUID zap, and <var>NOTHREAD</var> must be less than the number of threads defined against the CPUID zap for your site.

Set <var>NOTHREAD</var> to the maximum number of concurrent Connect★ conversations to be supported. Make sure that your Model 204 <var>NUSERS</var> parameter setting accommodates these additional SQL and RCL threads.

====SQLBUFSZ====
<var>SQLBUFSZ</var> is a required user parameter that defines the maximum incoming SQL message length that can be presented to the SQL Server. The recommended initial value for this parameter is 100000. Specify it on the first IODEV 19 line.

For more information about sizing SQL buffers, see <var>[[SQLBUFSZ parameter|SQLBUFSZ]]</var>.

====LHEAP====
<var>LHEAP</var> specifies the size of HEAP, a dynamic storage area required for the processing of SQL C routines. HEAP is in the variable portion of the server area allocated to each user, and its size is added to the variable size calculation of the server area. An overall working space of 200,000 bytes is usually sufficient for SQL operations.

The recommended initial value is 200000 for SQL threads. Specify it on the first IODEV 19 line. Do not specify it with the User 0 parameters, because this wastes space. For non-SQL threads, which do not require HEAP space, you can set or reset <var>LHEAP</var> to zero, the default. 

You can monitor the high-water mark for use of this storage area with the HEAP statistic, described in [[#HEAP and PDL high-water marks|HEAP and PDL high-water marks]].

As the query complexity increases, you must increase the <var>LHEAP</var> value accordingly, as you encounter SQL error messages. Many SQL error messages offer specific advice. However, if you continue to get SQL error messages after increasing the <var>LHEAP</var> value, your query is too complex for RSQL to handle. You should rewrite your query into smaller, less complex parts.

==Runtime examples==
Shown in these examples are sample settings of some of the CCAIN parameters described earlier in this topic, the first two IODEV lines for each SQL IODEV, and Model 204 SQL DEFINE commands.

====For all operating systems using TCP/IP RCL and SQL threads====
The following example is an excerpt from a job that brings up a Model 204 Online for SQL processing, using a TCP/IP connection.
<nowiki>...LIBUFF=3000,LNTBL=600,LOBUFF=5000,LPDLST=32760,
LQTBL=2000,LSTBL=12000,LTTBL=150,LVTBL=300,
MINBUF=18,MAXBUF=200,NSUBTKS=15,...
SERVSIZE=700000,...
.
.
.
IODEV=49,POLLNO=1,NOTHREAD=4
IODEV=49,POLLNO=2
IODEV=49,POLLNO=3
IODEV=49,POLLNO=4
IODEV=19,POLLNO=1,NOTHREAD=4,SQLBUFSZ=100000,LHEAP=200000, -
LIBUFF=6048,SQLIQBSZ=32752
IODEV=19,POLLNO=2
IODEV=19,POLLNO=3
IODEV=19,POLLNO=4
* above IODEV=49 is for RCL connections
* above IODEV=19 is for SQL CONNECT* connections
*-------------------------------------------------------* /
* DEFINE CONNECT* SQL AND RCL LINK ETC... * /
*-------------------------------------------------------* /
**********************************************
DEFINE LINK TCPSQL WITH SCOPE=SYSTEM TRANSPORT=TCPSE -
PROTOCOL=IP LOCALID=ANY INBUFSIZE=4096 CONNECTIONS=8 -
SERVPORT=2132
DEFINE PROCESSGROUP ANY192 WITH SCOPE=SYSTEM LINK=TCPSQL -
INLIMIT=8 OUTLIMIT=8 REMOTEID=192.0.0.0 LOGIN=NOTRUST -
GUESTUSER=REJECT MASK=255.0.0.0
DEFINE PROCESSGROUP ANY204 WITH SCOPE=SYSTEM LINK=TCPSQL -
INLIMIT=8 OUTLIMIT=8 REMOTEID=204.0.0.0 LOGIN=NOTRUST -
GUESTUDEFINE PROCESS CCARSQL WITH SCOPE = SYSTEM -
DATALEN = 32763 FROM = (ANY192, ANY204)
SER=REJECT MASK=255.0.0.0
********************************************************
</nowiki>

==Server area sizing==
Server areas are the internal work areas allocated to each user. The server area includes a fixed space portion and a variable space portion. This section lists the fixed and variable portions of the server area that are affected significantly by SQL Server processing.

The <var>SERVSIZE</var> system parameter specifies the size of the server area available for all users for the Online run or per IODEV thread. <var>SERVSIZE</var> is the sum of the fixed and variable portions of the server area. 

You can calculate <var>SERVSIZE</var> according to formulas provided in the [[Defining the runtime environment (CCAIN)#Server areas|server areas]] topic.


The fixed and variable portions of the server area are calculated separately. To help you estimate <var>SERVSIZE</var> for Model 204 SQL processing, the following sections list the server area parameters and tables that are affected by SQL processing. 

Adjust your typical estimates of these parameters and tables as recommended, and include them in your usual <var>SERVSIZE</var> calculation along with the parameters and tables not affected by SQL processing. 

The recommended minimum value of <var>SERVSIZE</var> for SQL processing is 350K. For processing SQL statements that are unusually large, the recommended value is between 600K and 700K.

===Fixed server area===
<var>LIBUFF</var> and <var>LOBUFF</var> are parameters that contribute to the fixed portion of the server area calculation. Their typical settings must be increased to accommodate SQL processing of certain kinds of long input statements or returned data. The maximum for both is 32K. Technical Support recommends that you set <var>LIBUFF</var> close to the value of <var>SQLBUFSZ</var>.

In addition to these parameters, the fixed portion of the server area includes an area (called <code>C PRV</code> in the audit trail) that is used internally by the SQL Engine for storage of C global variables. SQL IODEVs must allow 6K bytes of fixed server size for the C PRV; non-SQL IODEVs do not need to allocate server space for the C PRV. 

===Variable server area===
The variable portion of the server area includes server tables and a dynamic storage area for the processing of SQL C routines.

Server tables are sections of the server area used by the compiler and evaluator to store all the information necessary to run either SOUL or SQL requests. Some server tables are also used by the editor and Host Language Interface (HLI) functions.

[[#Variable server area sections affected by SQL|Variable server area sections affected by SQL]] lists the sections of the server area used for SQL processing. You might need to resize the controlling parameters to conform to SQL application requirements. Estimate as usual the sizes of the server tables not affected by SQL processing. 

For more information about monitoring server tables and the parameters with which you control their size, see the [[Defining the runtime environment (CCAIN)#Server areas|server areas]] topic. 


For more information about HEAP, see the discussion of SQL IODEV threads in [[#Defining SQL and RCL IODEV threads|Defining SQL and RCL IODEV threads]].
Variable server area sections affected by SQL
<table>
<tr class="head">
<th>Section</th>
<th>Contents</th>
<th>Controlling parameter</th>
</tr>

<tr>
<td>HEAP</td>
<td>C routine processing</td>
<td><var>[[LHEAP parameter|LHEAP]]</var></td>
</tr>

<tr>
<td>LPDLST</td>
<td>User pushdown list</td>
<td><var>[[LPDLST parameter|LPDLST]]</var></td></tr>

<tr>
<td>NTBL</td>
<td>Statement labels, list names, and variables</td>
<td><var>[[LNTBL parameter|LNTBL]]</var></td></tr>

<tr>
<td>QTBL</td>
<td>Statements in internal form (quadruples) </td>
<td><var>[[LQTBL parameter|LQTBL]]</var></td></tr>

<tr>
<td>STBL</td>
<td>Character strings</td>
<td><var>[[LSTBL parameter|LSTBL]]</var></td></tr>

<tr>
<td>TTBL</td>
<td>Temporary work pages</td>
<td><var>[[LTTBL parameter|LTTBL]]</var></td></tr>

<tr>
<td>VTBL</td>
<td>Compiler variables</td>
<td><var>[[LVTBL parameter|LVTBL]]</var></td></tr>
</table>

==Setting initial sizes for SQL buffers==
The system manager must set three SQL buffer parameters for Connect★, which are described in detail in the following topics:
<ul>
<li><var>INBUFSIZE</var> parameter of <var>[[DEFINE LINK command: Horizon for TCP/IP|DEFINE LINK]]</var></li>

<li><var>DATALEN</var> parameter of <var>[[DEFINE PROCESS command: Horizon for TCP/IP and VTAM|DEFINE PROCESS]]</var></li>

<li><var>[[SQLBUFSZ parameter|SQLBUFSZ]]</var> user parameter set in the IODEV line</li>
</ul>

===INBUFSIZE===

At the mainframe, Model 204 TCP/IP receives the TCP/IP request unit (TU) into a buffer whose size is set by the <var>DEFINE LINK</var> parameter <var>INBUFSIZE</var>. The buffer receives and passes one TU at a time. For Model 204 TCP/IP, set <var>INBUFSIZE</var> to 4096 or to the TCP/IP TU size in your network.

===DATALEN===

In Model 204, <var>DATALEN</var> has a maximum setting of 32K. It should be set to the average amount of data in any request in your network.

==See also==
{{Template:SQL connectivity topic list}}

[[Category: SQL connectivity]]

RKTools installation

2017-10-09T17:03:25Z

Mlarocca: /* Janus Web rules for RKWeb */

==Overview==
<var class="product">[[RKTools]]</var> (Rocket Tools for Model 204) is a set of [[Application Subsystem development|application subsystems]] (aka APSYs) running inside a <var class="product">Model 204</var> Online that provide TN3270 and web-based tools for programmers, database administrators, and system managers.

As of RKTools V7.7, all Rocket-provided, SOUL-based tools are consolidated in the <code>M204PROC</code> procedure file. <code>M204PROC</code> includes all components from RKTools 7.5 in addition to Dictionary/204 and the [[SQL catalog#Generating DDL with SQL utilities|SQL Server utilities]]. This means that all Model 204 SOUL tools provided by Rocket are in a single file.

Note: Since the RKTools 7.7 installation process modifies the application subsystem definitions to point to the <code>M204PROC</code> file, sites that are upgrading must perform a full installation and not merely an <code>M204PROC</code> file overlay. To allow for a switch back to RKTools 7.5, keep a backup of your current <code>SIRIUS</code> file and your current <code>CCASYS</code> file (though you can also change the subsystem definitions manually using [[SUBSYSMGMT]]).

Installing <var class="product">RKTools</var> requires downloading the <code>M204PROC</code> file from the <var class="product">Model 204</var> maintenance website, restoring it to your environment, setting up some subsidiary <var class="product">Model 204</var> files, and verifying that the Online environment has the appropriate parameter settings. Then you run a single procedure that installs or upgrades the RKTools subsystems.

Once the installation is complete, upgrades to <var class="product">RKTools</var> can almost always be handled by restoring a fresh copy of the <code>M204PROC</code> file.

==Download the installation file==
All <var class="product">RKTools</var> 7.7 code resides in the <code>M204PROC</code> <var class="product">Model 204</var> file. You need to download a dump version of this file from the Rocket Software Model 204 maintenance website. The procedure file for RKTools 7.5 is <code>SIRIUS</code>.

To download from the Rocket website:
<ol>
<li>On the "Rocket M204 Customer Care" page ([http://m204.rocketsoftware.com/ http://m204.rocketsoftware.com]), go to the "Downloads and Uploads" section and select the "Download SOUL files" link to access the "SOUL files for Rocket Software" page.

<li>Log in, and download the version of RKTools that is compatible with your version of Model 204. The procedure file contained in the "RKTools V7.7" link works for Model 204 versions 7.6 and above. For Model 204 version 7.5, use the download labeled "RKTools V7.5."

A "Click here" link in the text above the file list on the SOUL files download page brings up [[Downloading and restoring SOUL files]], which provides help about downloading and uploading files, file sizing, and more.
</li>
</ol>

You can bypass any step of the installation that applies only to an <var class="product">RKTools</var> component you are not installing.

==System requirements==
<ul>
<li>RKTools V7.7 was made specifically backward compatible to <var class="product">Model 204</var> version 7.6, though version 7.7 is recommended. Version 7.5 of <var class="product">RKTools</var> requires <var class="product">Model 204</var> version 7.5 or higher.

<li>Requirements for [[#Server size requirements|server sizes]] for each product and Model 204 [[#user0parms|User 0]] and [[#utableParms|UTABLE]] parameter settings are listed where appropriate in the installation steps in the next section.</li>

<li>To verify the products for which your Online is authorized, enter <code>ROCKET</code> at the <var class="product">Model 204</var> command line.</li>

<li>The installing user must have:
<ul>
<li>Update access to the JCL or EXECs that bring up the host Online</li>
<li>Model 204 System Manager privileges</li>
<li>Access to the [[SUBSYSMGMT]] facility and the JCL or EXEC that runs the Online <var class="product">Model 204</var> region.</li>
</ul></li>
</ul>

==Install RKTools==
<blockquote class="warn">
Attention: If you are upgrading from a previous version, keep your old copies of <code>SIRLOCAL</code>, <code>M204LOCL</code>, and most application-specific data files, such as <code>JANCAT</code>, <code>SIRLIBD</code>, and <code>SIRFILED</code>. The SirMon <code>SIRSTATS</code> file is replaced in version 7.7 by <code>MONDATA</code>. The <code>SIRIUS</code> file is no longer used as of RKTools 7.7, but there is no harm in keeping it in case you want to fall back to a previous RKTools version. 

The installation process uses your existing RKTools files to determine whether to perform upgrade actions or new-installation actions, so leave these files allocated and available, including <code>SIRLOCAL</code>.
</blockquote>

<ol>
<li>Allocate files.
The following table shows the RKTools files and their sizes: 
<table class="thJustBold">
<caption>RKTools file allocations</caption>
<tr><th>File</th><th>Size</th><th>Allocation is required...</th></tr>
<tr><th>M204PROC</th>
<td nowrap>9800 pages</td>
<td>Always.</td></tr>

<tr><th>SIRLOCAL
</th><td>1200 pages</td>
<td>Always.</td></tr>

<tr><th>M204LOCL
</th><td>3000 pages</td>
<td>If using RKWeb.</td></tr>

<tr><th nowrap>MONDATA</th>
<td>4000 pages</td>
<td>Only if installing <var class="product">SirMon</var>. Note: <code>MONDATA</code> replaces <code>SIRSTATS</code>, which is no longer needed as of RKTools V7.7. </td></tr>

<tr><th>SIRFILED</th>
<td>1200 pages</td>
<td>Only if installing <var class="product">SirFile.</var></td></tr>

<tr><th>SIRLIBD</th>
<td>1200 pages</td>
<td>Only if installing <var class="product">SirLib.</var></td></tr>

<tr><th>SIRLIBP</th>
<td>1200 pages</td>
<td>Only if installing <var class="product">SirLib</var>.</td></tr>

<tr><th>JANCAT</th>
<td>1200 pages</td>
<td>Only if installing Janus OMNI.</td></tr>

<tr><th>JANSSL</th>
<td>1200 pages</td>
<td>Only if installing [[Janus Network Security|Janus SSL]] or RKWeb.</td></tr>
</table>

The following table shows the [[Dictionary/204 overview|Dictionary/204]] supporting files (in addition to M204PROC):
<table class="thJustBold">
<tr><th>File</th><th>Size</th><th>Allocation is required...</th></tr>

<tr><th>DATALINK</th>
<td>400 pages</td>
<td>For Dictionary/204 or SQL Server.</td></tr>

<tr><th>METADATA</th>
<td>400 pages</td>
<td>For Dictionary/204 or SQL Server.</td></tr>

<tr><th>M204TEMP</th>
<td>400 pages</td>
<td>If installing Dictionary/204.</td></tr>

<tr><th>D204RPT</th>
<td>400 pages</td>
<td>If installing Dictionary/204.</td></tr>

<tr><th>D204SYS</th>
<td>400 pages</td>
<td>If installing Dictionary/204.</td></tr>

<tr><th>M204DCTL</th>
<td>400 pages</td>
<td>If installing Dictionary/204.</td></tr>
</table>

The following table shows the [[SQL Server overview|SQL Server]] supporting files (in addition to M204PROC): 
<table class="thJustBold" id="sqlfiles">
<caption>SQL Server file allocations</caption>
<tr><th>File</th><th>Size</th><th>Allocation is required...</th></tr>

<tr><th>CCACAT</th>
<td>700 pages</td>
<td>For RKWeb access to SQL Server. </td></tr>

<tr><th>DATALINK</th>
<td>400 pages</td>
<td>For Dictionary/204 or SQL Server.</td></tr>

<tr><th>METADATA</th>
<td>400 pages</td>
<td>For Dictionary/204 or SQL Server.</td></tr>

<tr><th>TSFDATA</th>
<td>200 pages</td>
<td>For RKWeb access to SQL Server. </td></tr>

<tr><th>TSFTEMP</th>
<td>300 pages</td>
<td>For RKWeb access to SQL Server. </td></tr>
</table>
</li>

<li><var>RESTORE</var> <code>M204PROC</code> from the DUMP file [[#Download the installation file|downloaded from the Rocket website]].
<blockquote class="note">
Note: If you are restoring into your existing <code>M204PROC</code> file, note that the <code>M204PROC</code> file has X'0221' privileges, which does not allow <var>RESTORE</var>. You will have to <var>CREATE</var> the file first (to wipe out existing content) before you execute the <var>RESTORE</var>. A sample command sequence is: 
CREATE FILE M204PROC
END CREATE
OPEN FILE M204PROC
IN M204PROC RESTORE 192 FROM <var class="term">dumpfile</var>

</blockquote>

To verify the <code>M204PROC</code> version, you can open <code>M204PROC</code> with [[SirPro]] and view the RKTOOLS_VERSION procedure. 

<li id="updateJCL">Update the Online JCL or EXEC:
<ol type="a">
<li>Add DD (MVS) cards or FILEDEFs (CMS) for the RKTools files.
The "RKTools file allocations" table above lists the files for which DD cards or FILEDEFs might be needed.</li>

<li>Verify that the Online environment allows the use of [[Storing and using file group definitions (CCAGRP)#File groups|file groups]] and [[System requirements for Application Subsystems|application subsystems]].
<ul>
<li>To use permanent file groups, the Online must have allocated a [[Storing and using file group definitions (CCAGRP)#Creating the CCAGRP data set|CCAGRP file]], and the <var>[[SYSOPT parameter|SYSOPT]]</var> parameter must include the <code>2</code> bit. </li>

<li>To use APSY subsystems, an Online must have allocated a [[System requirements for Application Subsystems#Overview of CCASYS|CCASYS file]], and the <var>SYSOPT</var> parameter must include the <code>1</code> bit. </li>
</ul></li>

<li id="Server size requirements">Review the RKTools, Dictionary/204, and Model 204 SQL Server tables below for the minimum server-size requirements of individual subsystem components.

Note: The actual server size requirements might vary slightly from the listings below because of table
settings in your <var class="product">Model 204</var> Online, and because of slight differences between <var>UTABLE</var> requirements in different versions of <var class="product">Model 204</var>.

Rocket recommends using one server size for the entire Online, making it at least 750,000 bytes to accommodate the largest RKTools component. For more information about server sizing, see [[Defining the runtime environment (CCAIN)#Sizing user server areas|Sizing user server areas]].

Note: CCATEMP usage might increase with RKTools. CCATEMP should be monitored (<code>VIEW TEMPSIZE</code>, <code>VIEW TEMPMAX</code>) to ensure that sufficient space is allocated to accommodate the additional activity. 

<table class="thJustBold">
<caption>RKTools server sizes</caption>
<tr class="head"><th>Subsystem name</th>
<th>Minimum server size</th></tr>

<tr><th>JANSSL</th>
<td>300K</td></tr>

<tr><th>RKTOOLS</th>
<td>135K</td></tr>

<tr><th>SIRADMIN</th>
<td>150K</td></tr>

<tr><th>SIRDBA</th>
<td>180K</td></tr>

<tr><th>SIRFILE</th>
<td>230K</td></tr>

<tr><th>SIRLIB</th>
<td>135K</td></tr>

<tr><th>SIRMON</th>
<td>220K</td></tr>

<tr><th>SIRPRO</th>
<td>750K</td></tr>

<tr><th>SIRSCAN</th>
<td>250K</td></tr>
</table>

<table class="thJustBold">
<caption>Dictionary server sizes</caption>
<tr class="head"><th>Subsystem name
</th><th>Minimum server size
</th></tr>

<tr><th>DICTADMIN
</th><td>455K</td></tr>

<tr><th>DICTIONARY
</th><td>455K</td></tr>

<tr><th>DICTREPORT
</th><td>455K</td></tr>

<tr><th>DOCUMENT
</th><td>455K</td></tr>

<tr><th>FILEMGMT
</th><td>455K</td></tr>

<tr><th>SUBSYSMGMT
</th><td>455K</td></tr>

<tr><th>XREF
</th><td>455K</td></tr>
</table>

<table class="thJustBold">
<caption>SQL Server server sizes</caption>
<tr class="head"><th>Subsystem name</th><th>Minimum server size</th></tr>

<tr><th>CCACATREPT</th>
<td>250000</td></tr>

<tr><th>CCATSF</th>
<td>165000</td></tr>
</table>
</li>
</ol> </li>

<li>Verify that the Online has a minimum of 10 [[Sdaemons|Sdaemon]] threads allocated. Each of these threads is typically defined as an <code>IODEV15</code> thread.

If using RKWeb or any of the web interfaces to other components, you may need more IODEV15s available.</li>

<li id="user0parms">Modify the User 0 stream.

Adjust these parameters: 
<table class="thJustBold">
<tr><th>Parameter</th>
<th>Adjustment</th></tr>

<tr><th>COMPOPT</th>
<td>RKTools requires the <var>COMPOPT</var> X'03' bit, which enables mixed-case SOUL. RKTools makes extensive use of mixed-case coding, and the tools fail to compile if support is not enabled. If [[SirLib change control#Applying updates in batch mode|batch SirLib]] or other batch features are used, ensure that <var>COMPOPT</var> is set to X'03' in those jobs as well.</td></tr>

<tr><th>CUSTOM</th>
<td>RKWeb must include the 18 setting to enable a larger <var>[[SSLIBSIZE]]</var> on the Janus Web port, which must be secured.</td></tr><tr><th>MAXBG</th>
<td>Minimum setting is 4.</td></tr>

<tr><th>MAXDAEM</th>
<td>Minimum setting is 10.</td></tr>

<tr><th>MAXINCL</th>
<td>Minimum setting is 10.</td></tr>

<tr><th>NDCBS</th>
<td>Increase by the number of <var class="product">RKTools</var> files.</td></tr>

<tr><th>NDIR</th>
<td>Increase by the number of <var class="product">RKTools</var> files.</td></tr>

<tr><th>NFILES</th>
<td>Increase by the number of <var class="product">RKTools</var> files.</td></tr>

<tr><th>NORQS</th>
<td>Minimum setting is 5.</td></tr>

<tr><th>SESNPUB</th>
<td>Minimum setting is 40. The right setting for your site might be higher, based on RKWeb usage (number of users).</td></tr>

<tr><th>SESUMAX</th>
<td>Minimum setting is 10. The right setting for your site might be higher, based on RKWeb usage (number of users).</td></tr>
</table> </li>

<li id="utableParms">Verify you have adequate <var>[[UTABLE command|UTABLE]]</var> settings.

Initial problems with <var class="product">RKTools</var> subsystems are usually associated with one or two extremely small default <var>UTABLE</var> settings.
Running the failing subsystem in <code>TEST DEBUG</code> mode will highlight <var>UTABLE</var> parameters that need to be increased. 

These are the recommended settings: 
<table class="thJustBold">
<tr class="head"><th>UTABLE parameter</th>
<th>Value</th>
<th>Description</th></tr>

<tr><th>HTLEN </th>
<td style="text-align:right">220 </td>
<td>Max length of each header or trailer</td></tr>

<tr><th>LFTBL</th>
<td style="text-align:right">1000</td>
<td>Length of FTBL</td></tr>

<tr><th>LFSCB</th>
<td style="text-align:right">21400</td>
<td>Length of full screen buffer</td></tr>

<tr><th>LGTBL</th>
<td style="text-align:right">2000</td>
<td>Length of global variable table</td></tr>

<tr><th>LIBUFF</th>
<td style="text-align:right">2000</td>
<td>Length of input buffer</td></tr>

<tr><th>LITBL</th>
<td style="text-align:right">104</td>
<td>Length of ITBL</td></tr>

<tr><th>LNTBL</th>
<td style="text-align:right">450</td>
<td>Length of NTBL</td></tr>

<tr><th>LOBUFF</th>
<td style="text-align:right">960</td>
<td>Length of output buffer</td></tr>

<tr><th>LOUTPB</th>
<td style="text-align:right">10000</td>
<td>Length of output page buffer</td></tr>

<tr><th>LPDLST</th>
<td style="text-align:right">10000</td>
<td>Length of user push down list</td></tr>

<tr><th>LQTBL</th>
<td style="text-align:right">2200</td>
<td>Length of QTBL</td></tr>

<tr><th>LSTBL</th>
<td style="text-align:right">60000</td>
<td>Length of STBL</td></tr>

<tr><th>LTTBL</th>
<td style="text-align:right">2000</td>
<td>Length of TTBL</td></tr>

<tr><th>LVTBL</th>
<td style="text-align:right">1300</td>
<td>Length of VTBL</td></tr>

<tr><th>LXTBL</th>
<td style="text-align:right">1000</td>
<td>Length of XTBL</td></tr>

<tr><th>MAXHDR</th>
<td style="text-align:right">7</td>
<td>Max number of headers</td></tr>

<tr><th>MAXTRL</th>
<td style="text-align:right">7 </td>
<td>Max number of trailers</td></tr>

<tr><th>NORQS</th>
<td style="text-align:right">10</td>
<td>Number of requests preserved</td></tr>

<tr><th>SCRNSTBL </th>
<td style="text-align:right">12000 </td>
<td>STBL size for screen objects; this must be set for <code>SIRMON</code>, <code>SIRPRO</code>, and <code>SIRSCAN</code>.

A setting of 18000 is recommended for shops that use Mod 6 terminals with very large screen sizes (Rocket regularly tests with 3270 screen sizes of 50x150 characters). 
Note:
Either 12000 or 18000 is both a recommended minimum and maximum. Unless you have very large servers at your site (1 megabyte or larger), or you have very large screen objects in your own application code, a very large <var>SCRNSTBL</var> will cause table-size resets to fail.</td></tr>

<tr><th>SEQPDL</th>
<td style="text-align:right">4096</td>
<td>Minimum PDL available for sequencer</td></tr>
</table></li>

<li>Bring up the Online and install all the RKTools components except Dictionary/204 and SQL Server; then install or reinstall Dictionary/204 and SQL utilities as needed:
<ol type="a">
<li>RKTools 7.5 components
Issue these commands:
OPEN FILE CCASYS
OPEN FILE M204PROC
INCLUDE RKTOOLS_INSTALL 

RKTOOLS_INSTALL creates or updates the dozen or so RKTools application subsystems and sets up their supporting files. It performs all installation functions for new sites and all upgrade functions for reinstalling sites. No existing user profiles or other site-specific customization will be lost, as long as your existing SIRLOCAL file is left in place. 

The procedure produces a screen that lists all of the subsystems and whether they have loaded. It may be necessary to troubleshoot why expected subsystems did not load, then re-execute the procedure. You are encouraged to use the installation program's F1-key Help for detailed explanation of how the program is working with the subsystems. 

During APSY subsystem execution, error messages are not suppressed, which aids in diagnosing any installation problems. For example, you will be able to see if an installation failed because a file was enqueued in a different Online, and so on. 

The procedure <code>RKTOOLS_INSTALL</code> also builds a subsystem called <code>RKINSTALL</code>. If the installation needs to be re-run, you can invoke the subsystem (from command line or later with option 9 in the [[RKTools#mainmenu|RKTools main menu]]) rather than the procedure. 

Once the installation completes successfully, start the component subsystems (<var>[[START command: Starting an application subsystem|START SUBSYSTEM]]</var> command, invoke by name, or both) before using the RKTools 3270 or RKWeb interface. 

To verify that the subsystems are correctly installed, enter <code>RKTOOLS</code> at the command line, and use the main menu to test the individual RKTools components. You may also want to use SUBSYSMGMT to check that the component subsystem definitions are viewable, and use [[SirPro]] to display the newly restored M204PROC file to ensure its availability. </li>

<li>Dictionary/204
Though the [[Dictionary/204 overview|Dictionary/204]] components are delivered in <code>M204PROC</code> and accessible from RKWeb as of version 7.7, they are not installed and set up by <code>RKTOOLS_INSTALL</code>. For example, on z/OS, an initial Dictionary/204 installation uses the <code>DDINST</code> JCL from the Model 204 RKOBJLIB; for an upgrade, the <code>DDRINST</code> job.

Though the Dictionary/204 installation steps are largely included in the the RKTools installation process, you may want to review the [[Dictionary/204 installation guide]] for any additional actions you might need to take. </li>

<li>SQL Server
The [[SQL Server overview|Model 204 SQL Server]] components are delivered in <code>M204PROC</code>, and the SQL Server tools (CCACATREPT, CCATSF) are accessible from RKWeb. Support for this use of RKWeb requires the availability of the [[#sqlfiles|SQL Server supporting files]].

For an initial installation of the SQL Server subsystems, open <code>M204PROC</code> and execute the following command: 
INCLUDE SQLINST 

For a reinstallation: 
INCLUDE SQLRINST 

If you are installing and using SQL Server independently apart from RKTools and RKWeb, or you have additional questions about SQL Server installation, see [[Model 204 SQL Server installation]]. </li>
</ol>
</li>

<li>Use SUBSYSMGMT to add users to the appropriate [[SCLASS]] classes for any private or semi-public RKTools subsystems.

For authority to do this, you need System Administrator log in privileges, and you need SUBSYSMGMT privileges authorized via the [[Dictionary/204 administration#Security administration|DICTADMIN facility]] of Dictionary/204. The ID of the user that runs the INSTALL_RKTOOLS procedure is automatically added to the ADMIN or to the highest-level administration SCLASS in each of the RKTools subsystems (though not necessarily to the Dictionary and SQL Server subsystems).

Each component application of <var class="product">RKTools</var> has its own APSY subsystem definition and privileges associated with SCLASS specifications.
If you have a good reason for doing so, you can redefine any of the <var class="product">RKTools</var> subsystems as <var>PUBLIC</var>,
<var>SEMI-PUBLIC</var>, or <var>PRIVATE</var>.
[[Contacting Rocket Software Technical Support|Contact Rocket Software]] if you are unsure of the effect of a proposed change. 

RKTools components are typically installed as ''auto-start''. Use SUBSYSMGMT to disable this feature if you prefer that the subsystems not start automatically at each user request. 

The RKWeb interface, described further below in [[#Additional setup for RKWeb|Additional setup for RKWeb]], is controlled by the RKWEB subsystem, and you need to update the subsystem definition with the names of eligible users. Some of the RKWeb options require system administrator login privileges just as those options do when accessed with the RKTools TN3270 interface. To use these options in RKWeb requires system administrator login privileges and ADMIN SCLASS membership in the RKWEB subsystem, as well as a [[RKWeb#RKWeb security|suitable product license]]. </li>

<li>See the "Additional setup" sections below for the components you use at your site. </li>
</ol>

==Additional setup==

===Additional setup for SirLib===
Read and follow the instructions in the [[SirLib "getting started" steps]].

===Additional setup for SirScan===
The <var class="product">SirScan</var> administrator can use SIRADMIN to set default I/O and record maximums for users in the various <var class="product">SirScan</var> SCLASSes. See [[SirScan setup#Updating the SirScan SCLASS maximums in SIRADMIN|SirScan setup]] for details.

===Additional setup for SirMon===
When users are added to SCLASSes, note that there is a special <var>BUMP</var> SCLASS.
Any user added to this SCLASS gains the ability to <var>BUMP</var> other users.
This class does not provide access to customizing options in <var class="product">SirMon</var>.
Only users in the ADMIN SCLASS are able to add custom screen definitions to <var class="product">SirMon</var>.

If the <var class="product">SirMon</var> [[SirMon background monitor|background monitor]] is to be used, add the following line to the User 0 input stream:
SIRMON BACKGROUND

The background monitor may also be started automatically in a BATCH2 thread or an sdaemon thread.

You can customize statistic thresholds or use the supplied defaults to establish problem conditions.

The background monitor also lets you send warnings to
e-mail addresses and cell phones (via e-mail).
This feature requires <var class="product">[[Janus Sockets]]</var> and a started <var class="product">Janus Sockets</var> port.

===Additional setup for SirFile===
If the <var class="product">SirFile</var> background monitor is to be used, add the following line to User 0's input stream:
SIRFILE BACKGROUND

As with <var class="product">SirMon</var>, the background monitor may be started automatically in a BATCH2 thread or in an sdaemon thread. See [[SirFile refresh process]] for details.

You can customize the system and file-specific thresholds or use the
supplied defaults to establish problem conditions.

===Additional setup for RKWeb===
New for RKTools version 7.7 (and requiring at least Model 204 version 7.6), [[RKWeb]] (Model 204 Tools on the Web) provides web access for all the important elements of Model 204. Use of this product requires <var class="product">[[Janus Web Server]]</var>. If your site does not own Janus Web Server, RKWeb can still be used by a limited number of Janus Web threads under the Janus TOGA agreement, which allows the running of as many as five web threads.

Because RKWeb includes an interface for password maintenance and other protected Model 204 entities, it is mandatory to run it on an SSL-protected web port. Experienced users of Janus Web will probably have Janus ports already defined and protected by SSL certificates. Users new to Janus Web might want to review [[#Defining a Janus port and generating a self-signed SSL certificate|Defining a Janus port and generating a self-signed SSL certificate]], below, on defining an unprotected port that can be used to generate an initial self-signed certificate. 

====Browser support and configuration====
RKWeb supports Edge, Chrome, and the latest versions of Firefox and Safari. IE (Internet Explorer) is explicitly not supported as it is deprecated by Microsoft.

On some browsers, it might be necessary to allow pop-ups or to whitelist your RKWeb port so that pop-ups are authorized.

RKWeb makes extensive use of Javascript, which must be enabled for your browser.

====Janus Web port definition====
Authorized Janus Web Server users will find that RKWeb works best with at least ten Janus Web threads available on the port definition. Non-Janus customers can still use RKWeb via the free [[Janus Web Server#Limited Janus Web Server|Limited Janus Web Server]] feature, which allows a Janus Web port to be defined with as many as five threads. Under this configuration, RKWeb might operate a little slowly and might require occasional forced-refreshes, but all features are otherwise allowed.

An SSL-protected web port can be defined like this:

JANUS DEFINE portname 8205 WEBSERV 20 IBSIZE 4096 OBSIZE 65534 TRACE 1 -
RBSIZE 4096 UPCASE SESCOOKIE RKSESSION SSLSES VARIPADDR -
SSL JANSSL JUNE2017.PKEY SSLCACHE 320 SSLMAXCERTL 2048 -
SSLIBSIZE 32767 SSLOBSIZE 16000 -
WEBUSER WEBUSER WEBACCT WEBUSER MAXTEMP 2000 COMPRESS 1
JANUS START portname
privateKeyPassword


Such an SSL port as defined above will not start unless you have already obtained a signed certificate. To do so, you can start with an unsecured port and use the JANSSL application to [[#Defining a Janus port and generating a self-signed SSL certificate|generate a self-signed SSL certificate]].

RKWeb also provides an interface (<code>Manage > SSL Certificates</code>) for running the [[Janus Network Security]] application (JANSSL) for obtaining and managing SSL certificates. The RKWeb version of this application mimics the
operation of the application that is described in detail in the Janus Network Security wiki pages.

====Janus Web rules for RKWeb====
Following are the recommended and mandatory [[JANUS WEB rule matching order and examples|Janus rules]] to run RKWeb:

*... Codepage 0037... json requires square brackets to be Unicode 5B & 5D
*... translate EBCDIC BA/BB accordingly
UNICODE TABLE STANDARD MAP E=BA IS U=005B
UNICODE TABLE STANDARD MAP E=BB IS U=005D

*... TYPE rules for serving up binaries
JANUS WEB portname TYPE ANY * TEXT/HTML
JANUS WEB portname TYPE ANY *.HTML TEXT/HTML
JANUS WEB portname TYPE ANY / TEXT/HTML
JANUS WEB portname TYPE ANY *.HTM TEXT/HTML
JANUS WEB portname TYPE ANY *.GIF IMAGE/GIF
JANUS WEB portname TYPE ANY *.PNG IMAGE/PNG
JANUS WEB portname TYPE ANY *.CSS TEXT/CSS
JANUS WEB portname TYPE ANY *.JS TEXT/JAVASCRIPT
JANUS WEB portname TYPE ANY *.JPEG IMAGE/JPEG
JANUS WEB portname TYPE ANY *.JPG IMAGE/JPEG
JANUS WEB portname TYPE ANY *.ICO IMAGE/X-ICON

*... support for the Ace Editor, part of RKWeb
JANUS WEB portname ON /ACE/* OPEN M204PROC SEND * TEXT
JANUS WEB portname ON /ACE/EDITOR OPEN M204PROC CMD 'RKWEB'
JANUS WEB portname ON /ACE/EDITOR.JSON OPEN M204PROC CMD 'RKWEB'
JANUS WEB portname ON /ACE/PROCLIST OPEN M204PROC CMD 'RKWEB'
JANUS WEB portname ON /ACE/PROCLIST.JSON OPEN M204PROC CMD 'RKWEB'
JANUS WEB portname ON /ACE/S.SETTINGS.PNG OPEN M204PROC SEND S.SETTINGS.PNG BINARY EXPIRE +999999
JANUS WEB portname ON /ACE/S.SIRLIB_SEQ.PNG OPEN M204PROC SEND S.SIRLIB_SEQ.PNG BINARY EXPIRE +999999
JANUS WEB portname ON /ACE/*.JS OPEN M204PROC SEND *.JS TEXT
JANUS WEB portname ON /ACE/SRC/SNIPPETS/*.JS OPEN M204PROC SEND /ACE/SRC/SNIPPETS/*.JS BINARY EXPIRE +999999
JANUS WEB portname ON /ACE/SRC/*.JS OPEN M204PROC SEND /ACE/SRC/*.JS BINARY EXPIRE +999999
JANUS WEB portname ON /ACE/SRC/MODE-M204.JS OPEN M204PROC SEND MODE-M204.JS TEXT
JANUS WEB portname ON /ACE/LIB/*.JS OPEN M204PROC SEND *.JS BINARY EXPIRE +999999

*... RKWeb rules:
JANUS WEB portname ON /RKWEB/* CMD RKWEB
JANUS WEB portname ON /RKWEB/*.CSS OPEN FILE M204PROC SEND "1.CSS TEXT EXPIRE +7200
JANUS WEB portname ON /RKWEB/*.JS OPEN FILE M204PROC SEND "1.JS TEXT EXPIRE +7200
JANUS WEB portname ON /RKWEB/*.GIF OPEN FILE M204PROC SEND "1.GIF EXPIRE +7200
JANUS WEB portname ON /RKWEB/*.PNG OPEN FILE M204PROC SEND "1.PNG EXPIRE +7200
JANUS WEB portname ON /RKWEB/*.JPG OPEN FILE M204PROC SEND "1.JPG EXPIRE +7200
JANUS WEB portname ON /RKWEB/*.JPEG OPEN FILE M204PROC SEND "1.JPEG EXPIRE +7200
JANUS WEB portname ON /RKWEB/*/*.CSS OPEN FILE M204PROC SEND "2.CSS TEXT EXPIRE +7200
JANUS WEB portname ON /RKWEB/*/*.JS OPEN FILE M204PROC SEND "2.JS TEXT EXPIRE +7200
JANUS WEB portname ON /RKWEB/*/*.GIF OPEN FILE M204PROC SEND "2.GIF EXPIRE +7200
JANUS WEB portname ON /RKWEB/*/*.PNG OPEN FILE M204PROC SEND "2.PNG EXPIRE +7200
JANUS WEB portname ON /RKWEB/*/*.JPG OPEN FILE M204PROC SEND "2.JPG EXPIRE +7200
JANUS WEB portname ON /RKWEB/*/*.JPEG OPEN FILE M204PROC SEND "2.JPEG EXPIRE +7200
JANUS WEB portname ON /RKWEB/*/RKWSEND/*.* OPEN FILE M204PROC SEND "2."3 EXPIRE +7200
JANUS WEB portname ON /RKWSEND/* OPEN FILE M204PROC SEND * EXPIRE +7200

*... Rules supporting the applications implemented as Janus Legacy apps.
JANUS WEB portname DISALLOW /ACE*
JANUS WEB portname DISALLOW /RKW*
JANUS WEB portname DISALLOW /SIRLIB*
JANUS WEB portname DISALLOW /DICTADMIN*
JANUS WEB portname DISALLOW /DICTREPORT*
JANUS WEB portname DISALLOW /DICTDOC*
JANUS WEB portname DISALLOW /XREF*
JANUS WEB portname DISALLOW /FILEMGMT*
JANUS WEB portname DISALLOW /CCACATREPT*
JANUS WEB portname DISALLOW /CCATSF*

JANUS WEB portname ALLOW /ACE* USER *
JANUS WEB portname ALLOW /RKW* USER *
JANUS WEB portname ALLOW /SIRLIB* USER *
JANUS WEB portname ALLOW /DICTADMIN* USER *
JANUS WEB portname ALLOW /DICTREPORT* USER *
JANUS WEB portname ALLOW /DICTDOC* USER *
JANUS WEB portname ALLOW /XREF* USER *
JANUS WEB portname ALLOW /FILEMGMT* USER *
JANUS WEB portname ALLOW /CCACATREPT* USER *
JANUS WEB portname ALLOW /CCATSF* USER *

JANUS WEB portname ON /SIRLIB* CMD 'SIRLIB *'
JANUS WEB portname ON /DICTADMIN* CMD 'DICTADMIN *'
JANUS WEB portname ON /DICTREPORT* CMD 'DICTREPORT *'
JANUS WEB portname ON /DICTDOC* CMD 'DOCUMENT *'
JANUS WEB portname ON /XREF* CMD 'XREF *'
JANUS WEB portname ON /FILEMGMT* CMD 'FILEMGMT *'
JANUS WEB portname ON /CCACATREPT* CMD 'CCACATREPT *'
JANUS WEB portname ON /CCATSF* CMD 'CCATSF *'

JANUS WEB portname SCREEN /SIRLIB/* -
EXITURL '/rkweb/' EXITKEY 'Exit SirLib' AUTOPF ON CSS /styles/cool.css -
BGCOLOR 'white' TEXT 'black' -
BLUE '#000066' GREEN '#006600' PINK '#ff80ff' RED '#ff0000' TURQUOISE '#0033ff' WHITE '#0000ff' YELLOW '#ffff00'

JANUS WEB portname SCREEN /DICTADMIN* -
EXITURL '/rkweb/' EXITKEY 'Exit DictAdmin' AUTOPF ON CSS /styles/cool.css -
BGCOLOR 'white' TEXT 'black' -
BLUE '#000066' GREEN '#006600' PINK '#ff80ff' RED '#ff0000' TURQUOISE '#0033ff' WHITE '#0000ff' YELLOW '#ffff00'

JANUS WEB portname SCREEN /DICTREPORT* -
EXITURL '/rkweb/' EXITKEY 'Exit DictReport' AUTOPF ON CSS /styles/cool.css -
BGCOLOR 'white' TEXT 'black' -
BLUE '#000066' GREEN '#006600' PINK '#ff80ff' RED '#ff0000' TURQUOISE '#0033ff' WHITE '#0000ff' YELLOW '#ffff00'

JANUS WEB portname SCREEN /DICTDOC* -
EXITURL '/rkweb/' EXITKEY 'Exit Document' AUTOPF ON CSS /styles/cool.css -
BGCOLOR 'white' TEXT 'black' -
BLUE '#000066' GREEN '#006600' PINK '#ff80ff' RED '#ff0000' TURQUOISE '#0033ff' WHITE '#0000ff' YELLOW '#ffff00'

JANUS WEB portname SCREEN /XREF* -
EXITURL '/rkweb/' EXITKEY 'Exit Xref' AUTOPF ON CSS /styles/cool.css -
BGCOLOR 'white' TEXT 'black' -
BLUE '#000066' GREEN '#006600' PINK '#ff80ff' RED '#ff0000' TURQUOISE '#0033ff' WHITE '#0000ff' YELLOW '#ffff00'

JANUS WEB portname SCREEN /FILEMGMT* -
EXITURL '/rkweb/' EXITKEY 'Exit FileMgmt' AUTOPF ON CSS /styles/cool.css -
BGCOLOR 'white' TEXT 'black' -
BLUE '#000066' GREEN '#006600' PINK '#ff80ff' RED '#ff0000' TURQUOISE '#0033ff' WHITE '#0000ff' YELLOW '#ffff00'

JANUS WEB portname SCREEN /CCACATREPT* -
EXITURL '/rkweb/' EXITKEY 'Exit CCACatRept' AUTOPF ON CSS /styles/cool.css -
BGCOLOR 'white' TEXT 'black' -
BLUE '#000066' GREEN '#006600' PINK '#ff80ff' RED '#ff0000' TURQUOISE '#0033ff' WHITE '#0000ff' YELLOW '#ffff00'

JANUS WEB portname SCREEN /CCATSF* -
EXITURL '/rkweb/' EXITKEY 'Exit CCATSF' AUTOPF ON CSS /styles/cool.css -
BGCOLOR 'white' TEXT 'black' -
BLUE '#000066' GREEN '#006600' PINK '#ff80ff' RED '#ff0000' TURQUOISE '#0033ff' WHITE '#0000ff' YELLOW '#ffff00'

START SUBSYSTEM DICTADMIN
START SUBSYSTEM DICTREPORT
START SUBSYSTEM DOCUMENT
START SUBSYSTEM XREF
START SUBSYSTEM FILEMGMT
START SUBSYSTEM CCACATREPT
START SUBSYSTEM CCATSF


Again, as described earlier in [[#Janus Web port definition|Janus Web port definition]], because the above rules force users to log in with their enterprise credentials, and because RKWeb provides an interface into protected elements like passwords and APSY definitions, the port on which <var class="product">RKWeb</var> runs must be SSL protected.

To verify that the Janus Web rules are defined and that the SSL and unsecured ports are started, issue a <code>[[JANUS STATUS|JANUS STATUS *]]</code> command.

Once the rules are implemented and the port is started, You can access RKWeb with a URL like this:

<nowiki>https://www.mydomain.com/rkweb/welcome.html
</nowiki>

In addition to web rules, if low-privileged users are to be given access to RKWeb, certain system level methods need to be made available to those users. The following commands are required to implement this:

SIRMETH ALLOW SYSTEMSET SUBSYSTEM RKW* NONPRE
SIRMETH ALLOW SUBSYSTEMSET SUBSYSTEM RKW* NONPRE
SIRMETH ALLOW SYSTEMSET SUBSYSTEM SIR* NONPRE


As implied by the recommended and mandatory <var>JANUS WEB</var> rules above, some RKWeb applications are implemented with [[Janus Web Legacy Support|Janus Legacy]], which launches them into a separate browser tab. These Janus Legacy applications are not fully integrated with RKWeb, so you must use the security configured for those applications. For instance, [[Dictionary/204 FILEMGMT overview#Prerequisites|FILEMGMT]] is implemented as Janus Legacy, and it might prompt the user for a separate password.

===Additional setup for JANSSL===

====Defining a Janus port and generating a self-signed SSL certificate====
You can run RKWeb on any SSL-protected Janus port, and experienced users are likely to add the [[#Janus Web rules for RKWeb|recommended Janus rules]] to a port or ports they already have configured.

New users might need to define an initial unprotected Janus port that can then be used to generate a self-signed certificate. That certificate is then used to protect the port on which RKWeb is to run. Directions follow:
<ol>
<li>Enter these rules to create a very basic Janus Web port:
JANUS DEFINE MYWEBPORT 80 WEBSERV 10 IBSIZE 4096 OBSIZE 8192 TRACE 1 RBSIZE 4096 -
UPCASE WEBUSER WEBUSER WEBACCT WEBUSER MAXTEMP 1000

JANUS WEB MYWEBPORT ON / OPEN FILE M204PROC CMD 'INCLUDE JANWEB.HOMEPAGE.HTML'
JANUS WEB MYWEBPORT ON /JANSSL/* OPEN FILE M204PROC CMD 'INCLUDE JANSSL.*'
JANUS WEB MYWEBPORT ON /JANWEB/* OPEN FILE M204PROC CMD 'INCLUDE JANWEB.*'

* ALLOW rules that will force a logon for the JANSSL application.
* These will result in a warning, which is expected, but can be ignored.
JANUS WEB MYWEBPORT DISALLOW *
JANUS WEB MYWEBPORT ALLOW * USER *

JANUS START MYWEBPORT </li>

<li>Use either of the following ways to connect to the JANSSL certificate management program:
<ul>
<li>With the following URL, invoke the Janus default home page:
<nowiki>http://</nowiki>www.mydomain.com:xxxx 

where <var class="term">xxxx</var> is the port number. In the preceding port definition, <code>80</code> is the default port for web connections. Your network administrator might require a different port number. 

On the Janus default home page, click the link to the JANSSL certificate management program. </li>

<li>Using your own domain name and port number, connect directly to the JANSSL certificate management program:

<nowiki>http://</nowiki>www.mydomain.com:9999/janweb/sslmain.html </li>
</ul></li>

<li>Use the certificate management program to generate a self-signed certificate.

The program contains ample online Help. Follow the instructions for generating a self-signed certificate. </li>

<li>Use the self-signed certificate to protect the port from which RKWeb will run. </li>
</ol>

[[Category: RKTools]]

Security Server (formerly RACF) interface

2017-07-19T22:19:35Z

Mlarocca: /* SECPLIST parameter */

==Overview==
This topic presents an overview of how Security Server works and describes the impact of the Security Server Interface on the Model 204 user, system manager, and Security Server security administrator.

Note: The Security Server interface was formerly known as the RACF interface.

===Security Server===

Security Server is an extension of the IBM z/OS operating system that provides comprehensive data security. The Security Server Interface allows a Model 204 installation to use Security Server services within the Security Server environment. 

===Model 204 Security Server Interface===

The Model 204 Security Server Interface allows an orderly migration from Model 204 security to Security Server security and allows an installation to use a combination of either or both security methods. The interface provides the tools and instructions necessary to: 

<ul>
<li>Define a Security Server control group so that Model 204 can distinguish between separately running copies (that is, test and production)
</li>

<li>Define Security Server generic profiles for Security Server authorization of Model 204 user privileges within a control group
</li>

<li>Define a generic profile within Security Server that is associated with a control group, and determines whether a user can log in to Model 204
</li>

<li>Define a Security Server common control group for Model 204 resources that can be shared between running copies
</li>

<li>Define a default user priority class, or define the Security Server generic profiles that permit certain users to have specified Model 204 priorities
</li>

<li>Provide a mechanism to validate accounting information
</li>

<li>Determine a generic profile within Security Server that can define whether a user is allowed to submit JCL through the USE command
</li>

<li>Allow a system manager to add, change, or delete Security Server Interface options that control interface operations
</li>

<li>Provide a mechanism that establishes a shadow login capability to restrict user authorization via a default user ID for users who do not log directly in to Security Server
</li>

<li>Provide a method for a Security Server security administrator to define a default group, user ID, and password for the default user ID
</li>

<li>Provide a method for a Security Server security administrator to force users to log in through Security Server and not through
CCASTAT
</li>
</ul>
===Model 204 Security Server Interface components===

In summary, the Security Server Interface provides all the facilities an installation needs to implement Security Server security within the Model 204 environment. 


The following figure illustrates the components of the Security Server Interface. 

<center>
[[File:SECURITY_Security_Server_interface.jpg|border|450px]]
</center>

Security Server Interface

The Security Server Interface consists of the following components: 

<table>
<tr><th>Component</th> <th>Notes</th></tr>
<tr>
<td>Model 204 </td>

<td>Links with the Security Server Interface module </td>
</tr>

<tr>
<td>Security Server Interface module, RACFOS</td>

<td>Communicates with Security Server by using the System Authorization Facility (SAF) z/OS router</td>
</tr>

<tr>
<td>RACFPARM module </td>

<td>Can be linked with Model 204 or loaded dynamically at initialization</td>
</tr>

<tr>
<td>Model 204 system file, CCASTAT</td>

<td>Contains file protection passwords, user IDs, and user ID passwords</td>
</tr>

</table>

==Brief introduction to Security Server==

This section provides a brief summary of key Security Server features that are used in the discussion of the Model 204 Security Server Interface. 

For more information about the Security Server, see the [http://www-03.ibm.com/systems/z/os/zos/features/racf/resources.html IBM documentation] associated with that product. 

===Security Server processing===

Security Server identifies and verifies users accessing a system in which Security Server is installed and determines whether or not the user: 

<ul>
<li>Is defined to Security Server
</li>

<li>Has supplied a valid password (and/or operator identification card) and group name
</li>

<li>Has the REVOKE attribute, which prevents a Security Server defined user from entering the system at all or from entering the system with certain groups
</li>

<li>Can use the system only at certain times or on certain days as specified by the system manager or Security Server security officer
</li>

<li>Is authorized to access the terminal (which also can include day and time restrictions for accessing that terminal)
</li>

<li>Is authorized to access the application
</li>
</ul>

The following types of checking are performed by Security Server:
<ul>

<li>Authorization
</li>

<li>Global access
</li>
</ul>

===Authorization checking===

When Security Server verifies a user’s identity, Security Server specifies the scope of that user’s authorization for the current terminal session or batch job in a control block called the accessor environment element (ACEE). Security Server controls the interaction between the user and protected resources and authorizes not only which resources the user can access, but the way in which the user can access them (for example, as read-only or update). 

At the start of processing, Security Server performs the following checks that are related to the security classification of users

and data: 

<ul>
<li>Compares the security level in the user and resource profiles. If the resource has a higher security level than the user, Security Server denies the request.
</li>

<li>Checks a category list (that is, a list of site-defined names corresponding to departments or areas within an organization) in the user’s profile against the category list in the resource profile. If the resource profile contains a category that is not in the user’s
profile, Security Server denies the request.
</li>
</ul>

If Security Server has not denied the request as a result of the security classification checks, processing continues. 

Security Server permits access to a resource if the user satisfies any of a number of conditions, such as the following: 

<ul>
<li>The resource is a data set and the high-level qualifier is the user’s user ID
</li>

<li>The user’s user ID is in the access list with sufficient authority
</li>

<li>The user’s current connect group is in the access list with sufficient authority
</li>

<li>When list-of-group checking is active, one of the other groups with which the user is connected is in the access list with sufficient authority
</li>

<li>The universal access authority (UACC) is sufficiently high
</li>

<li>The user satisfies both of these conditions:
<ul>
<li>The user has the OPERATIONS attribute or the resource is within the scope of a group in which the user has the group-OPERATIONS attribute</li>
<li>The user’s user ID or any group name the user is connected to is in the access list with an authority not less than the user’s intended access</li>
</ul>
</li>
</ul>

Security Server provides two installation exits that a site can use during RACHECK processing, as well as a quicker form of
authorization checking called FRACHECK, or fast path RACHECK processing. 

===Global access checking===

In addition to authorization checking, Security Server also provides global access checking. Global access checking allows a site to store a system-wide table of default authorization levels for selected resources. Security Server checks this table to determine if access to a resource is permitted.

If access is permitted, Security Server bypasses further RACHECK processing. If the global access check fails, RACHECK processing continues. Frequently accessed resources with generalized access rules are good candidates for global access checking.

Global access checking handles resources in both the data set and the general resource classes, with the exception of group
resource classes.

Global access checking does the following:

<ul>
<li>
Grants access, but does not, by itself, deny any request for access
</li>

<li>
Does not allow logging of permitted access or gather statistics
</li>

<li>
Does not offer a postprocessing installation exit
</li>

<li>
Performs no I/O on the Security Server data set, thus offering a high-performance checking option
</li>
</ul>

===Using profiles to protect resources===

Security Server protects data sets (both DASD and tape) and general resources such as tape volumes and terminals. These
resources are protected through profiles defined by the site. Authorized users can create, modify, list, and delete profiles using
Security Server commands. 

When the ADDSD statement is used to define and protect a data set, Security Server builds a data set profile and stores it in the Security Server data set. Profiles can be either generic or discrete depending on the nature of the resource. 

===Generic profile===

A generic profile protects a single resource such as one data set, or a number of related resources; for example, those having similar naming structures, or the same access, authorization, and auditing requirements. 

A generic profile contains a list of authorized users and the access authority of each user. A single generic profile can protect
many data sets that have similar naming structures. Data sets protected by generic profiles need not be defined individually to
Security Server, which saves the system manager from having to enter and maintain individual profiles. 
Many users can protect all their data sets with a single generic profile consisting of their user ID and an asterisk: 
user_id.*


This profile protects all the user’s data sets that begin with the user’s user ID, regardless of the number of qualifiers. 

===Discrete profile===

A discrete profile protects resources that have specific or unique access authorization or logging requirements such as a single sensitive data set on a specified volume. 

A discrete profile contains the same kind of information as a generic profile, but it protects only the one identified data set on the specified volume or volumes. 

If the access authorization requirements are general, define a generic profile. If the data set has unique access authorization
requirements, define a discrete profile. 

Either type of profile can protect tape data sets as well as the following: 

<ul>
<li>
Cataloged and uncataloged non-VSAM data sets
</li>

<li>
VSAM data sets
</li>

<li>
Data sets with the same name residing on different volumes
</li>

<li>
Generation data group (GDG) data sets
</li>

<li>
Data sets and catalogs with single level names via a site-supplied prefix
</li>
</ul>

In Model 204, the Security Server Interface user privileges and other authorization items are defined as data set names and
treated as system resources. Generic profiles control who can use those resources by permitting individual users to access them.
These rules are written by the Model 204 system manager and the Security Server security administrator. 

==Running the Security Server Interface with Model 204==

When running either as an Online or in batch mode, Model 204 checks Security Server for the system resources a user has
permission to access. Model 204 manages the authorization process, because only Model 204 can identify the user requesting a
resource. Model 204 asks Security Server to validate those requests and responds to users who have been denied requests for
resources. 

Model 204 interfaces with Security Server in the following distinct areas: 

<ul>
<li>
User logins

<ul>
<li>LOGIN/LOGON command
</li>

<li>IFSTRT function
</li>

<li>IFLOG function
</li>
</ul>

</li>

<li>User resource requests

<ul>
<li>Dynamic allocation of new DASD space (ALLOCATE command)
</li>

<li>Job submission (<var>USE $JOB</var> command)
</li>

<li>Sequential data set handling (Record I/O)
</li>

<li>VSAM data set handling (External I/O)
</li>
</ul>
Note: Because Model 204 databases are not validated on behalf of the user by the security interface, Security Server must grant the owner of an address space permission to open Model 204 file data sets for update, regardless of whether the owner has write or read-only privileges. 
This permission allows Model 204 to write back updates to the FPL (File Parameter List) page, as required by the database management system, regardless of the Model 204 file open privileges.
</li>

<li>User logouts

<ul>
<li>LOGOUT/LOGOFF command
</li>

<li>IFFNSH/IFDTHRD function
</li>
</ul>
</li>
</ul>

The Security Server Interface uses the standard IBM-supplied calls to validate user requests for Model 204 resources. No source code modifications or exits to the Security Server software are needed. However, you can define an additional Security Server control group for nonshared resources as well as for resources shared between multiple copies of Model 204. 

==Using the Security Server Interface==

This section describes the changes that affect a Model 204 user. They include: 

<ul>
<li>LOGIN or LOGON </li>

<li>IFSTRT function </li>

<li>IFLOG function within IFAM1 </li>

<li>Dynamic allocation </li>

<li>Job submission </li>

<li>Sequential and VSAM data set handling </li>
</ul>

===LOGIN or LOGON command===

The [[LOGIN or LOGON command|LOGIN/LOGON]] command allows you to gain access to Model 204. Once you are connected to Model 204, and if the system manager has set Model 204 to require logins, any commands you enter (other than <var>LOGIN</var> or <var>LOGON</var>) produce the following message: 

*** PLEASE LOGIN


To log in, enter: 

LOGIN userid [account]


or


LOGON userid [account]


where: 
<table class="noBorder">
<tr>
<td><var class="term">userid</var></td>
<td>Is a character string that identifies you.</td> </tr>

<tr><td><var class="term">account</var></td>
<td>Is an optional character string that identifies the account under which you log in.</td> </tr>
</table>

===User ID information===

If Model 204 provides security authorization checks, as a Model 204 user you are assigned the following by the system manager: 

<ul>
<li>User ID that identifies you to Model 204. </li>

<li>Password that provides access to the system. Note that Model 204 versions 7.7 and later also support [[#Passphrases|passphrases]]. </li>

<li>User privileges associated with your user ID and password to define the particular type of access that you have. </li>

<li>Default priority class assigned to your user ID. </li>
</ul>

When native Model 204 security is in effect, this ID information is stored in a record in the system file CCASTAT. This record is deleted from CCASTAT when the system manager moves the user into Security Server security mode.
The [[#Preparing a RACFPARM parameter module with RACFGEN|RACFPARM]] module supplies a default Logonid for CCASTAT Logonids to do validation requests on Security Server.

===Security Server processing===

When Security Server performs login validation, the user ID must be eight characters or fewer (seven characters if jobs are
submitted through the internal reader). Your user ID is verified by Security Server before you can log in to Model 204. 

If your site chooses to perform Security Server account validation, any value entered in the account field is verified via Security Server services. When Security Server is performing account validation, the account is limited to a maximum length of eight characters. If you do not enter an account, the default account becomes your user ID. Refer to [[#Login processing|Login processing]] for more information on login processing. 
====Changing your password====
If you have the appropriate authority, you can change your Security Server user ID password when you log in to Model 204. For more information, see the [[LOGIN or LOGON command]] page.
====Passphrases====
If Security Server is configured to support passphrases, they can be used with Model 204 version 7.7 and later. Passphrases are 9-127 characters long and can contain any special characters (such as blanks, commas, and semicolons) supported by Security Server. See [[LOGIN or LOGON command#Setting a password|Setting a password]] for more information.

===IFSTRT function===

In the IFAM1 and IFAM4 environments, the IFSTRT function is used in a Host Language Interface program to allocate a Host
Language Interface thread. IFSTRT also establishes the calling convention, performs a user login, and determines whether or not the thread has updating privileges. 

When processing the login argument of the IFSTRT call, the user login process follows the rules for [[#User 0 login|User 0 login]].

===IFLOG function within IFAM1===

The IFLOG function is used only in the IFAM1 environment. It is called following IFSTRT to identify you when a login is required.

This function is necessary in any IFAM1 program where user authorization is validated by Security Server. 

As with the IFSTRT function, the user login process is the same as the process for [[#User 0 login|User 0 login]].

===Dynamic allocation considerations===

All dynamic allocation services in a Security Server environment are subject to Security Server system rules for data set
validation. For example, data set allocation can be restricted to allow the creation of data sets with certain name patterns. The rules for data set access are determined by the Security Server security administrator. 

To dynamically allocate a new data set, you must have Security Server ALTER authority. If you issue an ALLOCATE command
and you do not have ALTER authority, you receive a Model 204 error message. 

If you log in to Model 204 via CCASTAT, your allocation privileges are determined by the Security Server default user’s
authorization. 

Note: When you open a new or existing sequential or a VSAM data set, it is validated for read/write access. Security Server does not perform open access authorization on Model 204 data sets, because these data sets are currently protected under Model 204 security. 

===Job submission considerations===

When an Online user issues the <var>[[USE $PRINT / $PUNCH / $JOB command|USE $JOB]]</var> command to submit a batch job, Model 204 identifies the user so that Security
Server can determine if the user has proper authorization. If the submitter is IFAM1, IFAM4, or User 0, no additional processing
occurs; the submitted job inherits the privileges from the submitting job, because it has already been authorized to run by Security Server. 

In a Model 204 system in which the Security Server Interface is running, the following JCL statement is appended automatically
to the submitted job statement(s) to identify the Model 204 user: 

// USER=userid,PASSWORD=password,GROUP=groupname


where: 
<table class="noBorder">
<tr>
<td><var class="term">userid</var></td> <td>Is the submitting user’s Security Server user ID, or the default user ID if the user is logged in through CCASTAT.</td> </tr>

<tr><td><var class="term">password</var></td> <td>Is the user password associated with the particular user ID, or the default password for the default user ID if the user is logged in through CCASTAT.</td> </tr>

<tr><td><var class="term">groupname</var></td> <td>Is the Security Server group to which the submitting user is assigned. This is the group identified in the user’s ACEE that is provided by Security Server during user login, or the default group if the user is logged in through CCASTAT.</td> </tr>
</table>

The default user ID, password, and group information is defined in the Security Server Interface parameter module (RACFPARM) and cannot be modified by the user or controlled by the system manager. RACFPARM is described later in this section. 

If Model 204 finds any of the Security Server control parameters listed previously while processing the submitted JOB, they are
deleted from the JCL to prevent users from violating security. 

An installation can request that Model 204 check for user authority to submit a job. Because Security Server does not have a
facility to restrict job submission, Model 204 checks the generic profile for the comgroup.SUBMIT option. Comgroup.SUBMIT
determines whether or not a user is permitted to submit JCL. For more information about comgroup.SUBMIT, refer to the [[#Preparing a RACFPARM parameter module with RACFGEN|RACFGEN macro]] discussion.


If an unauthorized user attempts to submit a job, Model 204 issues an error message. 

For users logged in via CCASTAT, the authority to submit jobs is determined by the default user’s authorization. 

====USE $JOB example====

With a <var>USE $JOB</var> procedure, jobs submitted by users known to CCASTAT are logged in as the default user (here, <code>M204USR</code>).

In this case, the user who submitted the Online job is <code>userX</code>, and the user executing the <var>$JOB</var> is <code>userX2</code>:
14.21.44 J0763715 ---- FRIDAY, 19 FEB 2016 ----
14.21.44 J0763715 IRR010I USERID M204USR IS ASSIGNED TO THIS JOB.
14.21.44 J0763715 ICH70001I M204USR LAST ACCESS AT 13:40:32 ON FRIDAY, FEBRUARY 19, 2016

Jobs submitted by users known to RACF and unknown to CCASTAT are logged in under their own RACF profile.

In this case, the user who has submitted the Online job is <code>userY</code>, and the user executing the <var>$JOB</var> is <code>userY2</code>:
14.35.10 J0763765 ---- FRIDAY, 19 FEB 2016 ----
14.35.10 J0763765 IRR010I USERID userY2 IS ASSIGNED TO THIS JOB.
14.35.10 J0763765 ICH70001I userY2 LAST ACCESS AT 14:34:49 ON FRIDAY, FEBRUARY 19, 2016

===Sequential and VSAM data set considerations===

Security Server always performs an authorization check if you try to use a sequential or VSAM data set. To use a sequential or
VSAM data set you must be a member of a control group (or optionally a common control group) that has: 

<ul>
<li>Security Server alter or update privileges to open a deferred update data set or to issue the DUMP or USE commands
</li>

<li>Security Server alter authority to dynamically allocate a new sequential data set
</li>

<li>Security Server read privileges to read sequential files from User Language or to read the file specified in a RESTORE command
</li>

<li>Security Server read privileges to read external VSAM files from User Language.
</li>
</ul>

If you issue a sequential or VSAM data set OPEN command that fails for Security Server reasons, Model 204 issues an error
message. 

If you log in to Model 204 via CCASTAT, authorization is determined by the default user’s authorization limits. 

Model 204 sequential file data sets (such as CCASTAT, CCAAUDIT, CCAJRNL, or CCAJLOG) are also checked to determine if the owner of the address space has the authority to write to them. 

Security Server directly checks the following Model 204 commands: 
<ul>
<li>
[[DUMP command|DUMP]] and [[DUMPG command|DUMPG]]
</li>

<li>
[[RESTORE command|RESTORE]] and [[RESTOREG command|RESTOREG]]
</li>

<li>
[[USE_command:_Directing_output|USE OUTXXXXX]]
</li>

<li>
[[ALLOCATE command|ALLOCATE]] a new data set
</li>

<li>
OPEN DATASET
</li>

<li>
[[OPEN FILE command|OPEN filename]] with deferred update
</li>
</ul>

==Login processing==

The system manager is responsible for defining security processing in a Model 204 installation in which Security Server supplies authorization services. This section describes the login processing performed by the Security Server Interface. 

===Model 204 and Security Server login processing===

When a user logs in to Model 204, Model 204 acquires the user ID and account and searches CCASTAT to determine whether or not the user ID exists.
If the user ID is found, Model 204 queries the user for a password and proceeds with authorization processing. If the RACFPARM module indicates that CCASTAT defined users cannot log in, the login fails.
If the user ID is not found in CCASTAT and Security Server security is in effect, Model 204 uses Security Server facilities to authorize the user login: 

<ul>
<li>Model 204 passes the login user ID and password to Security Server to verify that the user is a valid Security Server user and that the password is correct.
</li>

<li>If the site has chosen to verify that the user is authorized to use Model 204, Security Server is asked if the user has PERMIT
authority to access the generic profile for resource group.LOGIN. If this check is successful, account processing occurs.
</li>

<li>If the installation has chosen to verify the account, the value entered is checked against the Security Server profile for
comgroup.ACCOUNT.account. If the value entered has PERMIT authority, the user is allowed into Model 204.
</li>
</ul>

If Security Server denies system access because of an invalid password or account, or if the user is not authorized to use Model 204, no login occurs and Model 204 issues an error message. 

Once users are successfully logged in, they are granted Model 204 privileges of X'00'. Any additional privileges are determined whenever they enter a Model 204 command that requires a specific privilege. 

Users who do not log in directly to Security Server are automatically restricted in what they can do by the privileges associated with the default user ID. Refer to [[#Security Server default user ID|Security Server default user ID]] for more information.

All the system manager commands concerning CCASTAT maintenance functions work as usual. The ZBLDTAB and ZCTLTAB utilities also continue to work as usual. 

File, group, and subsystem security functions are defined as described in the Model 204 documentation, particularly the [[Model 204 security features]] topic. 

===User 0 login===

When the Security Server Interface is active, User 0 is validated as the owner of the Model 204 run, regardless of whether the
run is Online, BATCH204, IFAM1, or IFAM4. Model 204 always attempts to log in User 0 automatically, and verifies that any user ID supplied matches the user ID of the owner of the address space. It is not necessary to supply a user ID on the login command for User 0; Model 204 determines the owner user ID and supplies it automatically. 

If a user ID is supplied on the login command and the user ID does not exist on CCASTAT, it must match the user ID of the owner of the address space or the login fails. If the user ID is found on CCASTAT and CCASTAT users are allowed to log in, all further authorization checking is based on a default user ID specified by the installation (if running as an APF-authorized program). 

BATCH204 and IFAM4 can run without APF authorization if the user ID is equal to the ADDR SPACE ID and there is no default login ID (you cannot login from CCASTAT). If you try to log in without meeting these conditions, your login fails or a B78 System ABEND occurs. 

Technical Support recommends that you do not specify a user ID in the login for User 0, so jobs can be easily migrated from test to production without having to change the login command. 

Whether or not you supply a user ID, no password is needed and Model 204 does not prompt for one. If a password statement is coded in the input stream, it is treated as an invalid Model 204 command. If the user ID is on CCASTAT, Model 204 prompts for a password. If the password is correct, the login succeeds but all future data set authorization checking is based on the default user ID. 

===AUTHCTL VIEW command===

The <var>[[AUTHCTL command|AUTHCTL VIEW]]</var> command displays the interface control options currently in effect for the active interface.


For example, if you enter either of these: 

AUTHCTL VIEW

AUTHCTL VIEW RACF

The following list is displayed (assuming this information was used during initialization): 

Security Server INTERFACE OPTIONS
GROUP M204TEST <var class="term">Security Server control group name</var>
COMGROUP M204COM <var class="term">Security Server common control group name</var>
VALIDATE LOGIN <var class="term">Validation option in effect</var>
VALIDATE ACCOUNT <var class="term">Validation option in effect</var>
PRIORITY LOW <var class="term">Priority default</var>
DLMCHECK <var class="term">Use $JOB DLM checking option</var>
M204GRP <var class="term">Default user group</var>
M204USR <var class="term">Default user ID</var>


The additional lines displayed indicate the current default user ID and group in use. For more information about defaults, refer to [[#Security Server default user ID|Security Server default user ID]].


For information about setting control information, see [[#Preparing a RACFPARM parameter module with RACFGEN|Preparing a RACFPARM parameter module with RACFGEN]]. 

===Using trusted login for CRAM users===

If your site uses [[Defining the user environment (CCAIN)#CRAM (IODEV=11, 23, 29)|CRAM]], you can use the trusted login feature, which allows users to issue login commands or calls that do not include a user ID and password.
For a user to log in as trusted, the user ID must be defined to Security Server. User IDs defined to CCASTAT are not allowed to log in as trusted users. CICS users must be using the Security Server interface for CICS. Only CICS user IDs that log in through Security Server can log in as trusted users. 

Trusted login can be used with the following CRAM thread IODEV types: 

<ul>
<li>IODEV11 (CRFSCHNL)
</li>

<li>IODEV29 (CRIOCHNL)
</li>

<li>IODEV23 (IFAMCHNL)
</li>
</ul>

To set up trusted login for a user, set the SECTRLOG user parameter, as discussed in [[#Setting up the SECTRLOG parameter for trusted login|Setting up the SECTRLOG parameter for trusted login]]. 

====Login processing for trusted login====

For users connecting with a CRAM thread that allows trusted login, the user login processing routines are changed to handle a LOGIN command or IFSTRT call without a user ID and password: 
<ul>
<li>CRFS and CRIO channel threads handle User Language statements. These users ordinarily issue a LOGIN or LOGON request with the following format: 

<ul>
<li>version 7.6 and earlier:
LOGIN userid [account];password [:new password];apsyname
</li>
<li>version 7.7 and later:
LOGIN userid [account];password;apsyname
</li>
</ul>
For trusted logins, the format is: 

LOGIN;;apsyname
</li>

<li>The IFAM channel threads handle IFAM2 statements. These users ordinarily issue an IFSTRT or IFSTRTN call with the following format: 

IFSTRT (RETCODE,LANG_IND,LOGIN,THRD_TYP,THRD_ID) 

IFSTRTN (RETCODE,LANG_IND,LOGIN,THRD_TYP,THRD_ID,CHAN) 

The LOGIN parameter is required and supplies the user ID and password as a character string using the following format: 
<ul>
<li>version 7.6 and earlier:
‘userid [account];password [:new password];’
</li>
<li>version 7.7 and later:
‘userid [account];password;’
</li>
</ul>

For trusted logins, the statement format is the same but the login character string is a semicolon surrounded by single quotes (';'). 
</li>
</ul>

====Trusted login errors====

When using trusted login, you might receive one of the errors described in this section. 
<ul>
<li>The following message: 
M204.2378: SECURITY TRUSTED LOGIN FEATURE DISABLED 
is generated in either of the following situations: 
<ul>
<li>The Model 204 job requesting the trusted login feature is running without a Model 204 Security Interface (CA-ACF2, Security Server, or CA-Top Secret).</li>
<li>
Model 204 address space does not have enough storage to allocate an internal work area for the trusted login feature. In this
situation, the Model204 job does not initialize because it still has to allocate storage for the Model 204 file buffers.
</li>
</ul>
</li>

<li>The following message is issued when the trusted user ID passed by CRAM is not between 1-8 bytes long:
M204.2379: INVALID TRUSTED USERID LENGTH = length
</li>
</ul>

==Maintaining the Security Server Interface==

At each Security Server site, the security administrator performs system-wide maintenance functions within Security Server. The security administrator is responsible for defining and maintaining the Security Server generic profiles and permits for authorization that are eventually used by Model 204. The following discussions describe the Model 204 data maintained by the security administrator. 

The privilege names that Model 204 uses are based on generic data set profiles. Although the Security Server ADDSD command describes a resource profile for Model 204, use it as if you are defining a data set. 

This method provides the simplest way to describe resources. You do not need to reassemble any Security Server modules because all definition is external. In addition, it is portable across Security Server releases, because no internal modifications are made to Security Server tables and no Security Server exits are used. 

In the following examples, the simplest set of conditions is described. You can fully utilize all Security Server options (for example, auditing when a resource is used, changing the universal access authority, or naming a specific owner of the group). Use security access levels for both the profiles and the permits for authorized users of those profiles. 

The interface requires that users of these resources are permitted READ authority. 

===Defining user privileges===

You must identify user privilege names as Security Server generic data set profiles. The standard Model 204 user privileges
described earlier have been assigned fixed names. The following set of user privilege names defines the possible privilege types for a user. These names are further qualified by the control group name entered in the RACFPARM module. 


These user privilege profile names are described in the following table. See the [[LOGCTL command: Modifying user ID entries in the password table|LOGCTL]] command page for more information on the LOGCTL settings.


<table>
<caption>User privilege names</caption>

<tr class="head">
<th>User privilege name... </th>
<th>Defines a user who can... </th>
<th>Corresponding LOGCTL setting </th>
</tr>

<tr>
<td>group.PRIV.SUPER.USER </td>
<td>Exercise superuser privileges: a user with READ access to this profile can execute a CREATE command. </td>
<td>X'80' </td>
</tr>

<tr>
<td>group.PRIV.SYSTEM.ADMIN</td>
<td>Exercise system administrator privileges: a user with read access to this profile can issue system administrator commands such as LOGWHO, MONITOR, PRIORITY, and WARN. </td>
<td>X’40’ </td>
</tr>

<tr>
<td>group.PRIV.CHANGE.FILE.PASSWORD</td>
<td>Change the file password that is used to open a file: valid only if the file entry is stored in CCASTAT. </td>
<td>X'20' </td>
</tr>

<tr>
<td>group.PRIV.SYSTEM.MANAGER </td>
<td>With system manager privileges: a user with read access to this profile can issue all system administrator commands along with certain other privileged commands such as LOGCTL, AUTHCTL VIEW, and DUMPG. </td>
<td>X'08' </td>
</tr>

<tr>
<td>group.PRIV.OVERRIDE.RECORD.SECURITY </td>
<td>Override record security. </td>
<td>X'04' </td>
</tr>
</table>

===Defining corresponding generic profiles===

Security Server generic data set profiles must be developed and defined to Security Server to correspond to the defined
privileges. The Security Server generic data set profiles used to define the standard Model 204 privileges and other resources to
Security Server in a batch TSO execution are as follows: 

<nowiki>//JOBNAME JOB (other information).....
//DOIT EXEC PGM=IKJEFT01,DYNAMNBR=20
//SYSTSPRT DD SYSOUT=A
//SYSTSIN DD * </nowiki>
ADDGROUP group DATA('MODEL204 Security Server CONTROL GROUP NAME')
ADDSD 'group.PRIV.SUPER.USER*' UACC(NONE) GENERIC
ADDSD 'group.PRIV.SYSTEM.ADMIN*' UACC(NONE) GENERIC
ADDSD 'group.PRIV.CHANGE.FILE.PASSWORD.*' UACC(NONE) GENERIC
ADDSD 'group.PRIV.SYSTEM.MANAGER*' UACC(NONE) GENERIC
ADDSD 'group.PRIV.OVERRIDE.RECORD.SECURITY.*' UACC(NONE) GENERIC
ADDSD 'group.LOGIN*' UACC(NONE) GENERIC

ADDGROUP comgroup DATA('MODEL204 Security Server COMMON GROUP NAME')
ADDSD 'comgroup.SUBMIT*' UACC(NONE) GENERIC
ADDSD 'comgroup.PRIORITY.HIGH*' UACC(NONE) GENERIC
ADDSD 'comgroup.PRIORITY.STANDARD.*' UACC(NONE) GENERIC
ADDSD 'comgroup.PRIORITY.LOW*' UACC(NONE) GENERIC
ADDSD 'comgroup.ACCOUNT.<var class="term">nnnnnnnn</var>.*' UACC(NONE) GENERIC


Note: <var class="term">nnnnnnnn</var> represents an account number; there are as many as required. Also, high-level qualifiers cannot exceed eight (8) characters. 

In the following two sample PERMIT statements, the first is for a system manager and the second is for login authorization to a
copy of Model 204: 

PERMIT 'group.PRIV.SYSTEM.MANAGER*' ACCESS(READ) ID(user ID1,user ID2.....)

PERMIT 'group.LOGIN*' ACCESS(READ) ID(user ID1,user ID2.....)


Where: 
<table class="noBorder">
<tr><td><var class="term">group</var>.PRIV.<var class="term">privilege</var></td> <td>Specifies one of the fixed types that Model 204 uses to build Security Server retrieval search keys for the rules </tr>

<tr><td><var class="term">group</var></td> <td>Is the Security Server control group defined to Model 204</td></tr>
</table>


The previous Security Server PERMIT statement sample permits the specified users to access the named resource. Rules for determining the authorized user are described in the [http://www-03.ibm.com/systems/z/os/zos/features/racf/library/library.html IBM Security Server documentation].

The privilege rules are tested whenever a user issues a command that requires a specific privilege. If the user is authorized to have that privilege, the command succeeds. If not, the user typically receives a Model 204 error message and the attempt might be logged as an Security Server violation. 

==Installing the Security Server Interface==

The Model 204 interface to Security Server consists of the following components: 

<ul>
<li>Code in Model 204 that utilizes Security Server facilities </li>

<li>Security Server group and generic data set profile definitions defined at your site </li>

<li>SECPLIST User 0 parameter in CCAIN </li>
</ul>

The user site requirements that must be met in order to activate the Security Server Interface are identified in this section. 

===Terminal security considerations===

Security Server can enforce terminal security when a user logs in. At that time, the source of the login is passed to Security
Server. For systems running Model 204 with the SNA Communications Server (formerly VTAM) interface, this poses no problem
because Model 204 recognizes the terminal name and stores it for use. 

Configurations using CRAM (TSFS, CICS, IFDIAL) must use the CRAM channel name instead of the terminal ID as the user
source, because there is no secured mechanism in CRAM for identifying the source of the user. Because CRAM channel names
can be identified as valid sources, the user IDs allowed to use those sources can be validated. Using the CRAM channel name
temporarily ensures that entry to Model 204 is from an approved source. 

===SECPLIST parameter===

The SECPLIST User 0 parameter in CCAIN lets you specify the name of the RACFGEN argument set with which to initialize the interface. The name is defined by the assembler label name of the RACFGEN macro. 
<ul>
<li>If the SECPLIST parameter is not in CCAIN, RACFPARM is used as the default name of the argument set. </li>

<li>If no match is found for the SECPLIST name or the RACFPARM default name in the RACFPARM module, the interface is initialized using the precoded default parameters defined in the Security Server Interface. In this case, Login, Account, and Priority validation are not performed. </li>
</ul>


The following RACFPARM module contains two sets of Security Server arguments: 
<ul>
<li>In the first set, the name is LOG1 and account security is in effect. If the user is logged on through CCASTAT, the default Logonid is M204USR.</li>

<li>In the second set, the name is LOG2 and both account and login security are in effect. In addition, if the user is logged on through CCASTAT, the Logonid of the executing job is considered the default Logonid.</li>
</ul>

 TITLE 'RACFPARM MODULE' X
LOG1 RACFGEN GROUP=M204PROD, X
COMGRUP=M204RACF, X
PRTY=H, X
VALIDAT=ACCOUNT, X
DEFUSER=M204USR, X
DEFUGRP=, X
DEFPASS=, X
DMLCHECK
LOG2 RACFGEN GROUP=M204TEST, X
COMGRUP=M204RACF, X
PRTY=S, X
VALIDAT=(ACCOUNT,LOGIN), X
DEFUSER=JOBNAME, X
DEFUGRP=M204GRP, X
DEFPASS=DEFPASS, X
DMLCHECK
RACFGEN TYPE=END
END


===Preparing a RACFPARM parameter module with RACFGEN===

The RACFGEN macro generates a set of arguments that govern login and other security processes. There can be multiple
argument sets in a RACFPARM module. The RACFPARM parameter module can be linked with Model 204 or dynamically loaded
when the Security Server Interface is initialized.

The arguments for the RACFGEN macro are described in detail in this section. 

The following is a sample RACFGEN macro with one set of arguments. The name of the argument set is RACFPARM, which is
the required name if you are linking statically into your Model 204 modules. 

TITLE 'GENERATE A Security Server PARAMETER MODULE'

RACFPARM RACFGEN GROUP=M204RACF, Control group X
COMGRUP=M204RACF, Common control group X
PRTY=S, Priority X
VALIDAT=, Validation items X
DEFUSER=M204USR, Default user ID X
DEFUGRP=M204GRP, Default user group X
DEFPASS=M204PASS, Default user password X
DLMCHECK/NODLMCHECK Check DLM=
RACFGEN TYPE=END
END


Where: 
<ul>
<li>RACFPARM defines the name of this set of Security Server arguments. Because there can be any number of argument
sets in the RACFPARM module, each set must be given a unique name. There is no default name.

Note: If you want to statically link the RACFPARM module, you must include (as the first argument) a Security Server argument set named RACFPARM. Otherwise, the SECPLST value for the user is not found in the RACFPARM module, and the interface is initialized using the precoded default parameters defined in the Security Server Interface. In this case, Login, Account, and Priority validation are not performed. This may result in the user being unable to login. 
</li>

<li>GROUP specifies the 1- to 8-character Security Server control group name selected by your site. The rules for Model 204 privileges are defined and grouped by this code and stored in Security Server profiles. The group name must match the generic profile high-level qualifier defined to Security Server in the ADDSD statements for the profiles, all of which take the form of <var class="term">group.keyword.variable.data</var>.

The default is M204RACF. 

You can use the <code>GROUP</code> name to create a separate set of privilege definitions for an individual copy of Model 204. This allows
your site to have different privileges for different versions of Model 204, for instance for test and production. </li>

<li>COMGRUP specifies the 1- to 8-character Security Server common group name selected by your site. The rules for the VALIDAT ACCOUNT, PRIORITY, and SUBMIT options are defined and grouped by this code and stored in Security Server profiles.

The common group name must match the generic profile high-level qualifier defined to Security Server in the ADDSD statements for the profiles, all of which take the form of <var class="term">comgroup.keyword.variable.data</var>. 

The default is <var>M204RACF</var>, if a group name is not specified. 

Note: COMGRUP is used to create a common set of privilege definitions shared between copies of Model 204. 
</li>

<li>PRTY specifies the default priority for any user who successfully logs in through Security Server. Options are H (high), S (standard), L (low), or N (none). The default priority is STANDARD if the PRTY keyword is omitted. For more information about priorities, refer to [[Controlling system operations (CCAIN)#Priority scheduling|Priority scheduling]]. </li>

<li>VALIDAT specifies the type of validation to be performed. Multiple validation types can be specified for the interface.

Options are: 
<ul>
<li>ACCOUNT specifies that Security Server validates any account entered by the user during the login process. VALIDAT ACCOUNT verifies that Security Server permits the account value entered by the user. If so, the user is allowed in to Model 204. If not, the login fails.

This validation uses the comgroup.ACCOUNT.account# profile. </li>

<li>LOGIN specifies that Security Server rules are tested to determine if a user is allowed to log in to Model 204. If VALIDAT LOGIN is specified, the Security Server Interface determines if the user is permitted to use Model 204 before allowing access. If LOGIN is not specified, all users who pass the user ID/password and optional account validation are allowed access to Model 204.

This validation is performed using the profile group.LOGIN, so it can be used to limit the ability to log in when several copies of Model 204 are running. </li>

<li>PRIORITY verifies which priority the user is permitted to have. This option can be specified in addition to a standard priority. If priority validation fails, the standard priority is the default.

This validation uses the profiles:
comgroup.PRIORITY.HIGH
comgroup.PRIORITY.STANDARD
comgroup.PRIORITY.LOW
comgroup.PRIORITY.NONE

Validation is checked from highest to lowest priority. If a user has PERMIT access to one of these priorities, the value is assigned. If no PERMIT is found and a standard priority is not specified, the priority for the user is set to STANDARD. </li>

<li>SUBMIT uses Security Server rules to determine whether or not a user is allowed to issue the USE command to submit a job through the internal reader. If this option is specified, Security Server checks the user’s authorization privileges before allowing the user to submit the job. If this option is not specified, all users who pass the user ID/password and optional account validation are allowed to submit jobs.

This validation uses the comgroup.SUBMIT profile. </li>
</ul>

<li>DEFUSER defines the default submitting user’s Security Server user ID if the user is not directly logged in through Security Server. Refer to [[#Job submission considerations|Job submission considerations]] for a description of how the Security Server user ID is used when submitting jobs.

<ul>
<li>If DEFUSER=, that is, this field is left blank, then CCASTAT-defined users are not allowed to log into Model 204. Only valid Security Server users can utilize the running system. </li>

<li>If DEFUSER=<var class="term">JOBNAME</var>, then the following occurs. The ASID ACEE is moved to DEFUSER, the GROUP ACEE is moved to
DEFGROUP, and the default user’s ACEE pointer is set to AUCKDPTR. </li>
</ul>

<li>DEFUGRP defines the default Security Server group to which a submitting user is assigned if the user is not directly logged in
through Security Server. Refer to [[#Job submission considerations|Job submission considerations]] for a description of how the Security Server group is used when submitting jobs. </li>

<li>DEFPASS defines the default PASSWORD for the default user ID if the user is not directly logged in through Security Server. Refer to [[#Job submission considerations|Job submission considerations]] for a description of how the Security Server password is used when submitting jobs. </li>

<li>The DLMCHECK/NODLMCHECK argument specifies DLM processing options for jobs submitted through the internal reader using the USE command. The DLM parameter on a DD * or DD DATA statement allows a job to be submitted that can itself submit other jobs. This is a potential security compromise. The DLMCHECK/NODLMCHECK argument provides the ability to enforce certain rules when coding the DLM= parameter.

DLM processing options are as follows: 
<ul>
<li>DLMCHECK enforces the rule that if a DLM= parameter is used in a JCL stream, it must be the only parameter supplied. In this case, only the following forms of these statements are correct:

//DDNAME DD *,DLM=';;' 

or 

//DDNAME DD DATA,DLM='&&&&' 

In these statements, the DLM value follows the rules described in [http://www.ibm.com IBM] JCL documentation; any other parameters supplied result in an error. If there is a job statement following the offending statement, Model 204 appends the following to the job statement set as if it is an independent job: 

USER=...,PASSWORD=...GROUP=... 
</li>

<li>NODLMCHECK checks only the validity of the DLM= parameter and not the other optional parameters that can be specified on the JCL statement. All JCL statements after the DLM= parameter are sent to the internal reader without being checked. This argument does not guarantee that an error on the statement with the DLM= parameter is caught before it is submitted.

DLMCHECK is the default. </li>
</ul>
</li>
</ul>

The result from assembling the RACFGEN macro is link-edited to a library that is included in a Model 204 link-edit, or it can be optionally linked into a separate library and loaded at execution time. 

If you link RACFPARM as a separate load module, use the SECRLINK job in the JCL library. Modify the job according to the comments. 

If you link RACFPARM with the Model 204 configuration, add the following line in SYSLIN for the link-edit steps of ONLINE, BATCH204, IFAM1, and IFAM4. 

INCLUDE OBJLIB(RACFPARM) 

===Model 204 link-editing requirements===

To support multiple Model 204 logins for different user IDs, Model 204 must be linked to an authorized library using the
appropriate Security Server services. This means that any Online configuration must be linked to an authorized library. 

BATCH204 or IFAM can be linked to a nonauthorized library, provided that the user logging in is the same user who starts the job and there is not a default login ID that prevents CCASTAT logins. Otherwise, the login fails or a System B7A ABEND occurs. 

===Defining Model 204 to Security Server===

Model 204 allows multiple users per address space and provides services to many users through its own processing, but Security Server is aware only of the maintask in the address space (in this instance, Model 204). Model 204 must be defined as having the appropriate Security Server privileges to perform services on behalf of a Model 204 control group. 

You can define an additional Security Server control group for nonshared resources as well as for resources shared between
multiple copies of Model 204.The first step in the definition process is to choose a name and define a profile for the Model 204
control group and optionally the common group. For example: 

ADDGROUP M204RACF OWNER(SECURITY) DATA('MODEL 204 CONTROL GROUP')
ADDGROUP M204COM OWNER(SECURITY) DATA('MODEL 204 COMMON CONTROL GROUP')


===Defining Model 204 users in Security Server===

In Security Server, the user profile record contains all information for a defined user of a computer system. There are no special entries or any differences in the way a Security Server user is defined to the system. All authorization services are performed using the generic profiles for privileges. See [[#Defining corresponding generic profiles|Defining corresponding generic profiles]] for more information.


===Security Server default user ID===

The default user ID limits the authorization of users that have not logged in directly to Security Server (that is, users still defined in CCASTAT). 

Each user not logged directly into Security Server is assigned the authorization provided by Security Server for the default user ID. The authorization includes all user resource requests, as described in [[#Running the Security Server Interface with Model 204|Running the Security Server Interface with Model 204]].

The default user ID automatically is assigned the user ID <code>M204USR</code> with the password <code>M204PASS</code> and belongs to group
<code>M204GRP</code>. A user ID of this name must be defined to Security Server for CCASTAT-defined users to be able to log in. 

For security reasons, the system manager cannot modify this group, user ID, and password. If different data is required or if the installation would like to change defaults, the parameter module RACFPARM must be modified by the Security Server security
administrator or systems programmer. 

RACFPARM provides the mechanism to supply overrides to the default group, user ID, and password. This module can be made available during the Model 204 link-edit. Otherwise, Model 204 attempts to load it at the time the interface is initialized. If the module is loaded dynamically, it must be made available in the STEPLIB containing Model 204 or in a system load library. The RACFPARM module is generated with the RACFGEN macro. 

Note: All LOADLIBs concatenated in one STEPLIB must be APF-authorized or you lose your APF authorization for that job step. 

===Setting up the SECTRLOG parameter for trusted login===

The <var>[[SECTRLOG parameter|SECTRLOG]]</var> user parameter defines which CRAM thread applications are allowed to log in to Model 204 with a trusted user ID. The CRAM threads for which trusted login applications are allowed are: 
<ul>
<li>IODEV11 (CRFSCHNL) </li>

<li>IODEV29 (CRIOCHNL) </li>

<li>IODEV23 (IFAMCHNL) </li>
</ul>

SECTRLOG must be set on the first IODEV line for each trusted CRAM thread, because it is picked up during the initialization of each CRAM channel.
The following settings are valid: 

<table>
<tr class="head">
<th>Setting</th> <th>Meaning</th></tr>

<tr><td>X'00'</td>
<td>Trusted Login not allowed (default)</td> </tr>

<tr><td>X'01'</td>
<td>CICS applications (CRFS, CRIO, IFAM)</td> </tr>

<tr><td>X'02'</td>
<td>TSO applications (CRIO, CRFS)</td> </tr>

<tr><td>X'04'</td>
<td>Batch applications (CRIO, IFAM)</td> </tr>
</table>

===Conversion tasks and considerations===

The following table identifies the general tasks that must be completed to install and activate the Security Server Interface. Before conversion, you also might want to review the RACFPARM module definitions and link a separate copy of Model 204 for testing and production. 

<table>
<caption>Conversion checklist for Security Server </caption>
<tr class="head"><th>Step</th> <th>Task</th></tr>

<tr><td>1.</td>
<td>Define a Security Server GROUP control profile for Model 204.</td>
</tr>

<tr><td>2.</td>
<td>Define a Security Server GROUP common profile for Model 204. </td>
</tr>

<tr><td>3.</td>
<td>Define Security Server generic profiles for user privileges, and specify the users who have PERMIT access to have those privileges. </td>
</tr>

<tr><td>4.</td>
<td>Define Security Server generic profiles for:
<ul>
<li>Model 204 login authority related to the control group if the VALIDAT LOGIN option is specified in the RACFPARM</li>

<li>Authorized account code profiles related to the common group if the VALIDAT ACCOUNT option is specified in the RACFPARM</li>

<li>Authorized PRIORITY profiles if the VALIDAT PRIORITY option is specified to assign individual priorities to users and specify which users have PERMIT access for those privileges</li>
</ul></td>
</tr>

<tr><td>5.</td>
<td>Run RACFGEN to assemble the RACFPARM module.</td>
</tr>

<tr><td>6.</td>
<td>Link RACFOS into Model 204.</td>
</tr>

<tr><td>7.</td>
<td>Link RACFPARM$ into Model 204 directly or use SECRLINK to create a separate LOAD module to be used for dynamic linking at initialization.</td>
</tr>

<tr><td>8.</td>
<td>Add a new parameter in the user zero input stream called SECPLIST=<var class="term">parametername</var>. </td>
</tr>

<tr><td>9.</td>
<td>Delete Model 204 users from CCASTAT to turn on Security Server authorization checking.</td>
</tr>
</table>

==See also==
<ul>
<li>[[Security interfaces overview]]</li>
</ul>

[[Category:Security interfaces]]

Fast/Reload statements

2016-12-16T14:45:32Z

Mlarocca:

==Overview==
All <var class="product">Fast/Reload</var> programs must begin with a [[File Load utility: FLOD and FILELOAD commands|FILELOAD or FLOD command]] and end
with an <var>END</var> statement.
All statements between the <var>FILELOAD</var> or <var>FLOD</var> and the <var>END</var>
are converted into machine code by the <var class="product">Fast/Reload</var> compiler or are used to
set environmental parameters by the <var class="product">Fast/Reload</var> compiler.
An example of a very simple <var class="product">Fast/Reload</var> program is:
FILELOAD -1,-1,0,1000000,10000,10000,,68
G
DUMMY=1,0,X'8000'
FIELD1=1,10
END


<var class="product">Fast/Reload</var> supports all the [[File Load utility: FLOD and FILELOAD commands#Syntax of File Load statements|statements supported by FLOD and FILELOAD]] except
the following:
<ul>
<li>The <var>L</var> statement.
<li>The <var>ENDL</var> statement.
<li>The <var>F</var> statement.
<li>The <var>ENDF</var> statement.
<li>The <var>UP</var> statement.
<li>The <var>DOWN</var> statement.
<li>The <var>DELETE</var> statement.
</ul>
In addition, the X'4000' mode bit used to delete a field occurrence or occurrences is
not currently supported.
Finally, <var>FLOD</var> exits are not currently supported.

If you have <var>FILELOAD</var> or <var>FLOD</var> programs that contain statements not supported by
<var class="product">Fast/Reload</var>, you can still run the programs with the same load module you use
for <var class="product">Fast/Reload</var> programs.
The <var>[[FLOD and FLODX command|FLODX]]</var> and <var>[[FILELOAD and FILELOADX command|FILELOADX]]</var> commands invoke the
original <var class="product">Model 204</var> <var>FLOD</var> and <var>FILELOAD</var> programs instead of <var class="product">Fast/Reload</var>.

<var class="product">Fast/Reload</var> attempts to copy the <var>FLOD/FILELOAD</var> program
to the temporary procedure indicated by the <var>FRELPREV</var> system parameter
(which defaults to -1).
If <var class="product">Fast/Reload</var> determines that the <var>FLOD</var> or <var>FILELOAD</var> program
cannot be processed by <var class="product">Fast/Reload</var> but can be processed by standard <var>FLOD</var> or <var>FILELOAD</var>,
the <var>FRELPREV</var> temporary procedure is opened for input, and the program is passed to
standard <var>FLOD</var> or <var>FILELOAD</var> to be read again.

For more information on both supported and unsupported
statements, see [[:Category:File loading and reorganization]].
In addition to the standard statement set, <var class="product">Fast/Reload</var> supports the extra statements
described in the following subsections: [[#opts|The OPTIONS statement]]
and [[#laistmt|The LAI statement]].

Note: Each statement must begin in column one, since a blank in column one of a FLOD statement indicates the "read-and-load-a-field" statement. 

==The OPTIONS statement==
This statement can appear anywhere inside a <var class="product">Fast/Reload</var> program and is used to set
environmental parameters that affect the way the load will be performed.
The <var>OPTIONS</var> statement can be abbreviated to its first three or more characters.
For example, the following are all valid <var>OPTIONS</var> statements:
OPTIONS TAPEI FOOFOO
OPTION TAPEI FOOFOO
OPTI TAPEI FOOFOO
OPT TAPEI FOOFOO
Multiple parameters can be set via the <var>OPTIONS</var> statement.
They are described in the following subsections.
The minimum required abbreviation for each is indicated in uppercase.

===ANYorder===
This option only has an effect when data is being loaded into a hash
or sort key file.
When data is being loaded into one of these files,
performance will generally be good if the data is being loaded in
hash or sort key order.
If the data being loaded is not in this order,
load performance could be disastrously affected.
<var class="product">Fast/Reload</var> normally does not continue in such a case.
The <var>ANYORDER</var> option overrides this behavior and lets the file load continue.

In general, it is better to determine the reason records
are out of order and to correct the problem, than to use the <var>ANYORDER</var>
option to ignore it.

If you are using <var>[[#The LAI statement|LAI]]</var>, the ordering can be done by the <var>HASH</var> or <var>SORT</var>
option of the
<var>[[Fast/Unload Extraction Language (FUEL)#UNLOAD ALL INFORMATION or UAI|UAI]]</var>
statement in <var class="product">Fast/Unload</var>.

Otherwise, to obtain the full track I/O benefits of <var class="product">Fast/Reload</var>,
you should ensure that your input records are in the correct order.
You must sort the TAPEI dataset in order by the <var>SORT</var> key, or by the
hash code of the <var>HASH</var> key.
This can be achieved using the M204HASH utility, as described in [[Hash key files]].

===BAVail [page_type] size===
This option has the following two beneficial effects:
<ol>
<li>If <var class="term">size</var> (default -1) is non-negative (and the file is not <var>SORTED</var>), the
use of the <var>[[BRESERVE parameter|BRESERVE]]</var> (= bres) parameter is changed during the file load.
A record will start within <code>remain <= size + bres</code> bytes at the end of the page if and only if the record fits in its entirety on that page. That is, the total record size is less than or equal to <var class="term">remain</var>.
This ensures that no base record is split with <var>BRESERVE</var> bytes or fewer in the base
record, while using more available space on a Table B page than the default algorithm.

<li>If <var class="term">size</var> is greater than zero, <var class="product">Fast/Reload</var>
ensures, during the file load, that at least <var class="term">size</var> bytes are unused on a Table B page.
This provides for some record growth by subsequent updates, for example, during an Online run,
without shifting fields to an extension record.
</ol>
<var>BAVAIL</var> is ignored if <var class="product">Fast/Reload</var> is not operating using full track I/O.
A base record is the first part of a Table B record, as opposed to
the subsequent parts of a Table B record, which are called extension records.

====Parameters====
<ul>
<li><var class="term">size</var> is -1 (the default) or a non-negative number. The smallest value of <var class="term">size</var>
for any <var>BAVAIL</var> option is -1. The largest value is
6130 minus the length of all preallocated fields,
minus 3 if <var>FILEORG</var> is <var>SORTED</var>, minus 1 if <var>FILEORG</var> is <var>HASHED</var>, minus 4 if
<var>FILEORG</var> is <var>UNORDERED</var>. </li>

<li><var class="term">page_type</var> can be any of the following:
<table class="thJustBold">
<tr><th>ALL</th>
<td>This applies to all Table B pages. If <var class="term">size</var> is non-negative,
then <var class="product">Fast/Reload</var> guarantees that every table B page contains at least <var class="term">size</var> unused bytes.</td></tr>

<tr><th>BASE</th>
<td>This applies to any page that
contains one or more base records. If <var class="term">size</var> is non-negative, then <var class="product">Fast/Reload</var> guarantees that any page with a base record contains
at least <var class="term">size</var> unused bytes.</td></tr>

<tr><th>EXT</th>
<td>This applies to any page that contains an extension record. If <var class="term">size</var> is non-negative, then <var class="product">Fast/Reload</var> guarantees
that any page with an extension record contains at least <var class="term">size</var> unused bytes.</td></tr>
</table>

If <var class="term">page_type</var> is omitted, <var class="term">size</var> applies to all Table B pages.</li>
</ul>

====Usage====
Multiple <code>OPTIONS BAVAIL</code> specifications will override the value(s) previously specified.
For example:
OPTIONS BAVAIL 100 BAVAIL BASE 150

will set aside 150 bytes on each page with a Table B base record, and 100 bytes
on all other Table B pages, but
<nowiki>OPTIONS BAVAIL BASE 150 BAVAIL 100
</nowiki>
will set aside 100 bytes on all Table B pages.

The default <var>BAVAIL</var> for each page type is -1.
If the value of all of them is
-1, <var class="product">Fast/Reload</var> does not specifically reserve any Table B space, but uses the normal
<var class="product">Model 204</var> space algorithm determined by <var>BRESERVE</var>, ensuring that a record does not
start within the last <var>BRESERVE</var> bytes of a page.

If the file being loaded is not a <var>SORTED</var> file (<var>[[FILEORG parameter|FILEORG]]</var> X'01'),
a non-negative setting for any page type
will modify the effect of the <var>BRESERVE</var> parameter for all Table B pages.
Let <code>BA</code> be the maximum of all <var>BAVAIL</var> values; if
it is non-negative, then if an entire Table B record is
less than <var>BRESERVE</var> bytes long, it can be stored within the last <code>BA
+ BRESERVE</code> bytes on the page, but otherwise a Table B record is not
started in that area.

Therefore, you may want to set a temporary value for <var>BRESERVE</var> during the
file load which differs from the value used during online updating.
For example:
<nowiki>OPEN FILE mumble
RESET BRESERVE 300
FILELOAD -1,-1,0,1000000,1000000
OPTIONS BAVAIL 400
LAI
END
RESET BRESERVE 800
</nowiki>
Note: The correct values for <var>BRESERVE</var> and <var>BAVAIL</var> are file-specific, and depend
on characteristics such as record sizes, the cost to your applications of
extension records, the importance of conserving Table B space, and updating
characteristics.
Like any tuning exercise, this requires analysis and experimentation.
The numbers in the above example could be wrong for your file, in fact, you may
do better with an online <var>BRESERVE</var> that is smaller than the file load <var>BRESERVE</var>,
and <var>BAVAIL</var> may be smaller than both, larger than both, or in between.


====Examples====
In the following examples:
<ul>
<li>The file is a simple <var>ENTRY ORDER</var> file (<var>FILEORG</var> X'00').
<li>There are no preallocated fields.
<li>Each page contains 6140 usable bytes.
(A page has 6144 bytes prior to the trailer, but there are 2 bytes used
to determine the number of records on a page, and 2 used for the amount of unused space.)

<li><code>Dataln</code> means the total length of data in
a record, <code>basln</code> means the space used for a base record,
and <code>extln</code> means the space used for an extension record.

<li>Each base record or extension record requires a 2-byte page locator, and
contains a 3-byte area which is zero or has the record number of a
subsequent extension record.
So, for example, if a record is completely stored in a base record,
<code>basln = dataln + 5</code>.

<li>Each example illustrates a case starting with a base record on an empty page.

<li>The resulting space allocation shows each page as the letter "P" and a
page number, followed by extension and/or base records
and free space enclosed in square brackets.
For example, the following shows two records stored on one page:
<nowiki>Rec0 dataln=100
Rec1 dataln=300
P0 [Rec0 basln=105] [Rec1 basln=305]
[free=5730]
</nowiki>

<li>Extension records are shown with the base record ID followed by a period and
extension number. For example, this
shows one record stored on three pages:
<nowiki>Rec0 dataln=12570
P0 [Rec0 basln=6140]
P1 [Rec0.1 extln=6140]
P2 [Rec0.2 extln=305] [free=5835]
</nowiki>

<li>Results are shown for different values for <var>BAVAIL</var>.
With the default value of <code>BAVAIL=-1</code>, <var class="product">Fast/Reload</var> uses the standard
<var class="product">Model 204</var> algorithm for allocating Table B space during a file load.
This standard algorithm is always used when <var class="product">Fast/Reload</var> is not using full track I/O.
</ul>

<ol>
<li>The following example shows that <code>BAVAIL=0</code> can be used for maximum packing on a
page, and <code>BAVAIL>0</code> can be used to ensure free space on a page; each of them
ensure a base record is not split in the first <var>BRESERVE</var> bytes:
Rec0 dataln = 6000
Rec1 dataln = 130
BRESERVE = 300

Using BAVAIL = -1:
P0 [Rec0 basln=6005] [free=135]
P1 [Rec1 basln=135] [free=6005]

Using BAVAIL = 0:
P0 [Rec0 basln=6005] [Rec1 basln=135]

Using BAVAIL = 135:
P0 [Rec0 basln=6005] [free=135]
P1 [Rec1 basln=135] [free=6005]
</li>

<li>The following example shows that without <var>BAVAIL</var>, you cannot
guarantee free space on a page:
<nowiki>Rec0 dataln=130
Rec1 dataln=6000 (60 100-byte fields)
BRESERVE = 300

Using BAVAIL = -1:
P0 [Rec0 basln=135] [Rec1 basln=6005]

Using BAVAIL = 0:
P0 [Rec0 basln=135] [Rec1 basln=6005]

Using BAVAIL = 135:
P0 [Rec0 basln=135] [Rec1 basln=5805] [free=200]
P1 [Rec1.1 extln=205] [free=5935]
</nowiki></li>

<li>The following example shows tighter packing and fewer extension
records:
<nowiki>Rec0 dataln=6000 (60 100-byte fields)
Rec1 dataln=100
Rec2 dataln=6100 (61 100-byte fields)
Rec3 dataln=100
Rec4 dataln=6000 (60 100-byte fields)
BRESERVE = 200

Using BAVAIL = -1:
P0 [Rec0 basln=6005] [free=135]
P1 [Rec1 basln=105] [Rec2 basln=6005] [free=30]
P2 [Rec2.1 extln=105] [Rec3 basln=105]
[Rec4 basln=5905] [free=25]
P3 [Rec4.1 extln=105] [free=6035]

Using BAVAIL = 0:
P0 [Rec0 basln=6005] [Rec1 basln=105] [free=30]
P1 [Rec2 basln=6105] [free=35]
P2 [Rec3 extln=105] [Rec4 basln=6005] [free=30]
</nowiki></li>

<li>The following example shows use of <var>BAVAIL</var> that
increases the extension records at file load time, but by leaving
space on all pages,
records can grow without producing extension
records which are stored on pages "far away" from the base page:
<nowiki>Rec0 .. Rec5 dataln=4000 (40 100-byte fields)
BRESERVE = 300

Using BAVAIL = -1:
P0 [Rec0 basln=4005] [Rec1 basln=2105]
[free=30]
P1 [Rec1.1 extln=1905] [Rec2 basln=4005]
[free=230]
P2 [Rec3 basln=4005] [Rec4 basln=2105]
[free=30]
P3 [Rec4.1 extln=1905] [Rec5 basln=4005]
[free=230]

Using BAVAIL = 300:
P0 [Rec0 basln=4005] [Rec1 basln=1805]
[free=330]
P1 [Rec1.1 extln=2205] [Rec2 basln=3605]
[free=330]
P2 [Rec2.1 extln=405] [Rec3 basln=4005]
[Rec4 basln=1405] [free=325]
P3 [Rec4.1 extln=2605] [Rec5 basln=3205]
[free=330]
P4 [Rec5.1 extln=805] [free=5335]
</nowiki></li>
</ol>

===DKOnly===
In many cases, <var class="product">Fast/Reload</var> bypasses the <var class="product">Model 204</var> disk buffer
monitor for Table B pages and instead uses its own full track buffers
for output.
This can, in certain instances, result in data being
loaded into different Table B pages than standard <var>FLOD</var> or <var>FILELOAD</var> would use.
An example of this is non-empty reuse record number files.
You can force <var class="product">Fast/Reload</var> to use the <var class="product">Model 204</var> disk buffer
monitor by specifying the <var>DKONLY</var> option.
This option can result in
a significant increase in the real and CPU time required to perform a file load.

===ERRCont===
This parameter lets you complete a reload despite errors that would
normally cause a <code>MSIR.0316</code> user restart.
This can be useful, for example, in a case where you know you have some
input data that will cause an error, but you
want to use a reload for reformatting purposes despite the problematic fields.

If you specify <var>ERRCONT</var> to "continue on error" a <var class="product">Fast/Reload</var> program, you probably
need to increase the <var class="product">Model 204</var> <var>ERMX</var> parameter setting to prevent a session
termination because of excessive errors.
Note: Using <var>ERRCONT</var> may place your data at risk, so use this parameter only in cases
where you know your data and have taken due precautions and backups beforehand.


The following <var>FILELOAD</var> code uses the <var>ERRCONT</var> parameter:
<nowiki>FILELOAD -1,-1,0,1000000,10000,10000,10000,50
OPTIONS ERRCONT
LAI
END
</nowiki>

===FTOnly===
In many cases, <var class="product">Fast/Reload</var> bypasses the <var class="product">Model 204</var> disk buffer
monitor for Table B pages and instead uses its own full track buffers for output.
In certain cases, though, <var class="product">Fast/Reload</var> will automatically drop back to
using the <var class="product">Model 204</var> disk buffer monitor.
When it does this, a file load
might take considerably longer than expected.
If you do not wish <var class="product">Fast/Reload</var>
to perform this automatic dropback, simply specify the <var>FTONLY</var> option.
<var>FTONLY</var> will result in the file load being terminated when an automatic dropback would
ordinarily be done.

===NObuff n_out_buffs===
<var>NOBUFF</var> must be followed by a number indicating the number of full track
output buffers <var class="product">Fast/Reload</var> is to use.
When <var class="product">Fast/Reload</var> is bypassing the <var class="product">Model 204</var> disk buffer monitor and performing
full track I/O to Table B, it uses a certain number of full track buffers.
These buffers must each be large enough to hold the data that will fit on a single
track of the disk devices containing the database file.
This means that the buffers
will each be 43,288 bytes long if you are using 3380s, 49,472 bytes long if you are
using 3390s, and 49,472 bytes long if you are using both.

Ordinarily <var class="product">Fast/Reload</var> uses three full track output buffers.
This is probably sufficient for most purposes.
On rare occasions, it might be possible to
get some speed improvements by using more than three output buffers.
In these cases, simply specify the <var>NOBUFF</var> option followed by a number greater than 3. 

<var>NOBUFF</var> must always be greater than or equal to 3. 

===NXBuff n_tableX_buffs===
<var>NXBUFF</var> must be followed by a number indicating the number of full track
Table X buffers <var class="product">Fast/Reload</var> is to use.

<var>NXBUFF</var> must always be greater than or equal to 3. 

===NOVAlidate===
<var>NOVALIDATE</var> indicates that no buffer pointer validation is to be performed.
For example, in the following statement, buffer pointer validation would make
sure that the input record was at least 107 bytes long:
<nowiki>FIELDA=99,9
</nowiki>
Without buffer pointer validation, the above statement would simply load data
off the end of the input buffer, which would result in <code>FIELDA</code> being loaded with
garbage, or perhaps in certain cases, would result in an addressing exception
because the area past the end of the buffer is not allocated.
Buffer pointer validation is probably more important with index register based
references to the input buffer, because these types of references are more likely
to have bad values in the index register and so go outside the current input buffer:
<nowiki>FIELDC=4|1,20
</nowiki>

With buffer pointer validation, if a buffer reference is determined to be invalid,
an error message is issued indicating the input record number as well as the invalid
buffer offset and length, as in the following example:
<nowiki>MSIR.0892: Input error: input record number: 1, start position/length: 99/9
</nowiki>

Standard <var>FILELOAD</var> started performing buffer pointer validation in <var class="product">Model 204</var> V5R1.

While buffer pointer validation is probably a good idea, it does have a slight
performance cost.
If there appears to be little chance of a buffer pointer error in a <var>FILELOAD</var>
program, and performance is at an absolute premium, you can use the <var>NOVALIDATE</var>
option to eliminate the cost of the buffer pointer validity checks.

Since <var>LAI</var> programs have no explicit buffer references, the <var>NOVALIDATE</var> option has
no effect on <var>LAI</var> programs.

===STAtc stats_intvl===
<var>STATC</var> must be followed by a number indicating the number of database file records that
<var class="product">Fast/Reload</var> will create before updating <var class="product">Model 204</var> statistics.
To speed up processing, <var class="product">Fast/Reload</var> does not ordinarily update <var class="product">Model 204</var> statistics
(since last, system, etc.) until the end of a file load.

If you want these statistics to be updated more frequently, you can specify a <var>STATC</var> value.
If you specify <code>OPTION STATC 10</code>, <var class="product">Model 204</var> statistics are updated for every
10th record created in the database file.
<code>OPTION STATC 0</code> and <code>OPTION STATC 1</code> are equivalent. 

===TAPei ddname===
<var>TAPEI</var> must be followed by string indicating the DDNAME to be used instead of <code>TAPEI</code>
for the input sequential file containing the data to be loaded.
For example if you wish to load data from DDNAME <code>HOMER</code>, simply specify <code>OPTION TAPEI HOMER</code>.
This allows more than one input stream to be used to load data in a single BATCH204 or Online run.

==The LAI statement==
The <var>LAI</var> statement allows data created with the <var class="product">Fast/Unload</var>
<var>[[Fast/Unload Extraction Language (FUEL)#UNLOAD ALL INFORMATION or UAI|UAI]]</var> (<var>Unload All Information</var>) statement to be loaded into a database file.
<var>LAI</var> stands for Load All Information and has several optional parameters.

===Syntax===
LAI [DElfield] [FAMsplit] [NEWfgid] [NOfdef]
[NOIndex] [NOProcs]

where the parameters can be abbreviated with only the part shown in
uppercase, and where:
<table class="thJustBold">
<tr><th>DElfield</th>
<td>Means that if a field that is not defined in the target file is found in the input dataset, that is, was unloaded by <var>UAI</var>, that field should simply be deleted.
If this parameter is not specified, the presence of an undefined field would terminate the <var>LAI</var>with an error. This statement provides an efficient way of deleting fields during a reorg.
Note: This parameter has no effect if the <var>NOFDEF</var> parameter is notalso specified. This is because if <var>NOFDEF</var> is not specified, any unloaded field will be automatically defined in the target file. </td></tr>

<tr><th>FAMsplit</th>
<td>Means that if any two names (two fields, a field and an alias, or two aliases) were part of a single <var class="product">Sir2000 Field Migration Facility</var> family in the unloaded file but are
now either separate fields or part of separate <var class="product">Sir2000 Field Migration Facility</var> families, the values should be loaded into each field or family. Effectively, this "splits" the original family into multiple components.
If <var>FAMSPLIT</var> is not specified, an attempt to do such a split causes the <var>FLOD</var> or <var>FILELOAD</var> to be terminated.

The most likely use of this parameter is to convert a file that is being controlled by <var class="product">Sir2000 Field Migration Facility</var> into one that is not, but where any fields or aliases that were in
the original file could still be referred to with SOUL programs. This might be useful for sending a non-<var class="product">Sir2000 Field Migration Facility</var> version of a file to a site
that does not have <var class="product">Sir2000 Field Migration Facility</var>. Since <var class="product">Sir2000 Field Migration Facility</var> makes sure that related fields and aliases automatically
stay in synch, it is generally not a good idea to update the non-<var class="product">Sir2000 Field Migration Facility</var> version of the file. 

See the "File Reorganizations" chapter in the
<var class="book">[[Media:SirfieldNew.pdf|Sir2000 Field Migration Facility Reference Manual]]</var>
for considerations about preserving SIRFIELD information using <var class="product">Fast/Reorg</var>.</td></tr>

<tr><th>NEWfgid</th>
<td>Means that fieldgroup IDs from the TAPEI input file are not copied to created fieldgroups, but rather that fieldgroup IDs within each record are created starting with 1.</td></tr>

<tr><th>NOfdef</th>
<td>Means that field definitions unloaded by <var>UAI</var> are not to be used to automatically define a field if it does not exist in the new file.
If this parameter is not specified, all fields that have not been explicitly
defined in the new database file but were defined in the old database file (unloaded with <var>UAI</var>) will be
defined with exactly the same attributes that they had in the old database file.</td></tr>

<tr><th>NOIndex</th>
<td>Means that Ordered Index data unloaded by UAI is not to be loaded by <var>LAI</var>. When this optionis used, visible Ordered Index data will be regenerated and sorted by <var>LAI</var>
and invisible Ordered Index data will be lost. This parameter has no effect if the <var>OINDEX</var> parameter was not specified on the <var>UAI</var> command for the unload.</td></tr>

<tr><th>NOProcs</th>
<td>Means that any procedures and procedure aliases unloaded by <var>UAI</var> are not to be loaded by <var>LAI</var>. Procedure and alias records in the input dataset will be skipped.
For more information about loading procedures, see [[Fast/Reload procedure handling]].</td></tr>
</table>

<var class="product">Fast/Reload</var> programs using <var>LAI</var> are quite simple.
For example, the following is a valid Fast/Reload program:
FILELOAD -1,-1,0,1000000
LAI
END


Note: The <var>LAI</var> statement has this limitation:
it must be the only statement that appears in a <var class="product">Fast/Reload</var> program other
than the <var>OPTION</var> statement.


===LAI compared to FILELOAD/FLOD===
When using <var>LAI</var>, some of the parameters on the <var>FILELOAD</var> or <var>FLOD</var> statement have a slightly
different meaning than when doing a standard <var>FLOD</var>.
These parameters are:
<ul>
<li>Parameter 1

This parameter has the same meaning as in standard FILELOAD/FLOD.
That is, this is the
maximum number of records that will be loaded into the database file. </li>

<li>Parameter 2

This parameter is ignored when doing an <var>LAI</var>. </li>

<li>Parameter 3

In standard FILELOAD/FLOD programs this indicates the number of physical
input records in TAPEI to be skipped.
When doing an <var>LAI</var>, this indicates the number of unloaded
Table B records to be skipped. 

This parameter, along with parameter 1, lets you split
a reload into pieces.
For example, the following statements
load the first million records unloaded via UAI, then the next million records
and finally the remaining records. 
<nowiki>FILELOAD 1000000,-1,0,100000,100000
LAI
END
FILELOAD 1000000,-1,1000000,100000,100000
LAI
END
FILELOAD -1,-1,2000000,100000,100000
LAI
END
</nowiki> </li>
</ul>
All other parameters for the <var>FILELOAD</var> statement have the same meaning as when
doing a non-<var>LAI</var> <var>FILELOAD</var>.

===Using LAI with UAI===
<var>LAI</var> is closely related to the UAI statement in <var class="product">Fast/Unload</var>.
Ordinarily, the interaction between these two is quite simple.
However, in cases where sorting of the data unloaded by <var class="product">Fast/Unload</var> is
desired and/or if the data is being loaded into a hash or sort key
file, the interaction can become more complex.

When loading data into a hash or sort key file with the <var>LAI</var> statement, the data must have been
unloaded with a <var>UAI</var> statement that specified the <var>HASH</var> or <var>SORT</var> parameter
and specified the new file's hash or sort key as the first key on the <var>UAI</var> statement.
If this is not the case, the <var>LAI</var> will not load any data.
If the <var>UAI</var> statement
is coded correctly, the data unloaded by <var>UAI</var> will be in the order that the data
will eventually be in the database file being loaded.
In these cases, <var class="product">Fast/Reload</var>
will never have to make more than one pass through Table B and will actually be
able to use full track I/O to write the Table B pages if the data is being
loaded into an empty hash or sort key file.

If the <var>UAI</var> statement is coded incorrectly, however, the unloaded data will be
in an order different from that which the data will loaded into the destination database file.
The impact of this on performance could be disastrous.
Consequently, <var class="product">Fast/Reload</var> will not ordinarily continue in the case when
data is detected out of order.
You can override this behavior with the
<var>ANYORDER</var> option, but at least in the case of reorganizations, it is generally
faster to unload the data again with the correct parameters rather than
trying to load the data in incorrect order.

The types of errors on the
<var>UAI</var> statement that can cause data to be in incorrect order are:
<ul>
<li>Specifying <var>SORT</var> on the <var>UAI</var> and then attempting to load the data
into a hash key file.</li>

<li>Specifying <var>HASH</var> on the <var>UAI</var> and then attempting to load the data
into a sort key file.</li>

<li>Specifying a <var>BSIZE</var> on the <code>UAI HASH</code> statement different from the <var>BSIZE</var>
in the hashed file being loaded.
</ul>

<blockquote class="note">
Note: If you are loading the data into a sorted file, there are several
cases of the <code>UAI SORT</code> statement that render the sort key unusable.
See [[Fast/Unload Extraction Language (FUEL)#UAI SORT or HASH and field unload order|UAI SORT or HASH and field unload order]]. 

If you are loading the data into a non-hash key, non-sort key
file, there is nothing wrong with loading data unloaded with a <var>UAI</var> command
that had a <var>SORT</var> or <var>HASH</var> key specified.
In fact, if you want to maintain
good locality for data with similar values for a particular field without
incurring the overhead of maintaining a sort key file, you
can specify that field as a sort key on a <var>UAI</var> and simply load the data into a non-sort key file. 
</blockquote>

==Loading null data==
Standard <var class="product">Model 204</var> <var>FLOD</var> and <var>FILELOAD</var> do not allow null data (stringdata with
a length of 0) to be loaded into the database file.
That is, if after stripping blanks and zeros the resulting
field has length zero, no data will be loaded into the database file.
This is the case, even if you are trying to load null data that had been
dumped using the <var class="product">SOUL</var> <var>[[PAI statement|PAI]]</var> statement.
Thus, it is extremely difficult
if not impossible to reorganize a database file containing null data
using <var>FLOD</var> or <var>FILELOAD</var>.

<var class="product">Fast/Reload</var> allows you to do this in a couple of ways:
<ul>
<li>Any null data unloaded via <var class="product">Fast/Unload</var>'s <var>UAI</var> statement will be loaded
as null data by <var class="product">Fast/Reload</var>'s <var>LAI</var> statement. </li>

<li>The <code>X'0001'</code> mode bit lets you load null data as a
zero length string into the database file. </li>
</ul>

For example, the following
<var>FILELOAD</var> program will load null data dumped via the <var>PAI</var> statement back into the new database file as null data:
<nowiki>FILELOAD -1,-1,0,1000000,10000,10000,,68
I 3
#1
G
=4,5,*
I 1
#2
=3,6|1,=
I 1,,,1|1
=2
#3
I 2,1,2,-7,-1|1
D 5,0|1=8|1,0|2,X'0801'
=1
#4
PROC.ID=1,0,X'8000'
END
</nowiki>
The key part of the above example is the X'0001' mode
bit on the <code>D</code> statement.
Note also, that for <var>PAI</var> type
reloads, it is generally a good idea to turn off blanks stripping.
This is controlled by the X'0800' mode bit on the <code>D</code> statement.

==See also==
{{Template:Fast/Reload topic list}}

[[Category:Fast/Reload]]

Connect-Star for JDBC

2016-07-27T17:50:05Z

Mlarocca: /* Connection pooling example */

{{DISPLAYTITLE: Connect★ for JDBC}}
==Overview==
Connect★ for JDBC supports Connect★ functionality to access Model 204. It includes all SQL and RCL statement syntax.

See [[Model 204 documentation]] for related Model 204 documentation.

==Connect★ for JDBC environment setup==

===Limitations and specifications===

====Limitations====
A complete listing of the Connect★ for JDBC limitations is provided in the Connect Star for Model 204 program group under the JDBC > J204 API.

====JDBC API specifications====
JDBC API incorporates JDBC 2.5 with no extended functionality.

===Platforms tested===
The following platforms have been tested successfully for connectivity with Model 204 using Connect★ for JDBC:
<ul>
<li>z/OS 1.5</li>
<li>Red Hat Linux 8.0 (Kernel 2.4)</li>
<li>Mandrake 9.2 & 10.0 (Kernel 2.6)</li>
<li>Sun Solaris 2.8</li>
<li>Windows NT, 2000, XP</li>
</ul>

These platforms are supported by Rocket Software.

===Environment requirements===
Before you install Connect★ for JDBC you must have the following installed in your working environment:
<ul>
<li>Java2 Software Development Kit (J2SDK) Version 1.5 or greater.</li>
<li>Model 204 Version 6.1.0 or greater with TCP/IP and SQL. </li>
</ul>
<div id="remove Connect* JDBC"></div>
===Removing a previous version of Connect★ for JDBC===

To remove a previous version of Connect★ for JDBC, do the following:
<ol>
<li>Go to the Control Panel > Add/Remove Programs.</li>
<li>Click on Connect Star for JDBC and remove.</li>
<li>Go to the installation folder for the previous version of J204 and delete the j204.jar file.</li>
</ol>

==Installing Connect★ for JDBC==
<ol>
<li>Ensure that you have fulfilled the preinstallation requirements as described in [[Connect* installation requirements#Preparing to install|Preparing to install]].</li>
<li>Navigate to the FTP server site: <code>ftp.rocketsoftware.com</code></li>
<li>Enter the userid and password provided by Rocket.</li>
<li>Navigate to the M204 > <var class="term">version</var> > ConnectStar folder (where <var class="term">version</var> is 7.5, for example).</li>
<li>Open the JDBC folder.</li>
<li>Choose the folder for the driver that you want: 32bit or 64bit.</li>
<li>Download the files to your PC, in binary format.</li>
<li>Run the .exe file to install the application.</li>
</ol>

==Connection parameters==
To connect a J204 client application to a Model 204 server, the application must specify connection parameters in the URL and/or java.util.Properties object supplied as parameters to DriverManager.getConnection().

See J204 API for DriverManager and J204Driver classes. If a parameter is specified in both the URL and the properties object, the value in the properties object takes precedence.

The URL includes both keyword and positional parameters. Positional parameters must be entered in the specified order, while keyword parameters may appear in any order. All keyword parameters are optional.

Note: If you specify parameters in the properties object, you must enter the key entirely in uppercase or lowercase. Otherwise, the property will not be found. The case of parameters in the URL can be upper, lower, or mixed; it does not matter. 

The URL has the following format:

====Syntax====
JDBC:J204:// {hostname} : {port} {/connection_type}
[/user/password]
[/eoc=eoc_character]
[/cursors=commit_option]
[/dirty data=dirty_data_option]
[/isolation level=isolation_level_option]
[/trace=trace_option]


====Where====
<ul>
<li><var class="term">hostname</var> specifies the server's TCP/IP name, entered in dotted decimal or string format.
Required; in the URL
</li>
<li><var class="term">port</var> specifies the port entered for the SERVPORT parameter in the DEFINE LINK command for the Model 204 server.

Required; in the URL
</li>
<li><var class="term">connection_type</var> is either SQL or RCL.

Required; in either the URL or properties list 
Properties key: connection type
</li>

<li><var class="term">user</var> and <var class="term">password</var> specify a valid Model 204 user name and password.

Optional; no defaults 
Properties keys: user, password
</li>

<li>The <var class="term">eoc_character</var> for the <var>eoc</var> parameter specifies the end-of-line character for RCL connection.
Default character is a semicolon (;) 
Properties key: eoc
</li>
<li>
The <var class="term">commit_option</var> for the <var>cursors</var> parameter determines the effect of commit on cursors. Choose one of the following options:
<ul>
<li>DROP specifies to close the cursor and drop the statement.</li>
<li>PRESERVE specifies to preserve open cursors and prepared statements.</li>
</ul>

Default is DROP 
Properties key: cursors
</li>

<li>The <var class="term">dirty_data_option</var> for the <var>dirty data</var> parameter specifies the treatment of dirty data by a Fetch statement. Choose one of the following options:</li>
<ul>
<li>DEFAULT uses the server default specified by the SQLCNVER parameter in the CCAIN stream; this is the default.</li>
<li>SKIP specifies to bypass a record containing dirty data and continue on to the next. </li>
<li>ERROR specifies to return an error message whenever dirty data is encountered.</li>
</ul>

Default is DEFAULT 
Properties key: dirty data
</li>

<li>The <var class="term">isolation_level_option</var> for the <var>isolation level</var> parameter is one of the following:</li>
<table>
<tr class="head">
<th>Option</th>
<th>Specifies</th>
</tr>
<tr>
<td>RC, the default</td>
<td>Read Committed (cursor stability)</td>
</tr>
<tr>
<td>RU</td>
<td>Read Uncommitted (dirty read)</td>
</tr>
<tr>
<td>SR</td>
<td>Serializable</td>
</tr>
</table>
Properties key: isolation level
</li>
<li>
The <var>trace</var> parameter controls logging. The <var class="term">trace_option</var> is one of the following:
<table>
<tr class="head">
<th>Option</th>
<th>Specifies</th>
</tr>
<tr>
<td>ALL</td>
<td>Write all trace messages to the log file</td>
</tr>
<tr>
<td>NONE</td>
<td>Write no trace messages</td>
</tr>
</table>

No log file is created if this parameter is omitted. For more information, see [[Connect* for ODBC#Data source default parameters|Data source default parameters]].
</li>
</ul>

====Usage====
<ul>
<li>
You must specify the host name and port in the URL. You can specify the other parameters in the URL or in the properties object. If you specify a parameter in both places, the value specified in the properties list takes precedence.</li>
<li>
Positional parameters must be entered in the specified order. Hostname, port, and connection type must be specified in the URL before other options.</li>
<li>
All keyword parameters are optional.</li>
<li>
When specifying parameters in a properties list, you must enter the key (property name) in either uppercase or lowercase characters, but not mixed case. If the key is in mixed case, the property cannot be found. When specifying parameters in the URL, you can enter uppercase, lowercase, or mixed case.</li>
</ul>

===Verifying your JDBC connection===
To verify your JDBC connection:
<ol>
<li>
Navigate to Connect Star for Model 204 program group > JDBC > DatabaseConnectivity.</li>
<li>
Complete the Connection Information screen and click the Test Connection button.</li>
</ol>
[[File:CStar_4-1_JDBC_DB_con.jpg]] 

==Connect★ for JDBC Compilation and Execution==

===Execution prerequisite===

Before executing an SQL statement, check with your Connect★ administrator to make sure that either the demonstration database is installed and has been defined to the SQL catalog file, CCACAT, or you have other available tables defined in CCACAT. (See [[Connect* to Model 204 connection#SQL catalog population|SQL catalog population]].)

===Online help===

Connect★ for JDBC includes HTML help files that provide complete documentation of the J204 JDBC driver. For detailed documentation, browse the index.HTML file in the \doc directory where the driver is installed.

===RCL and JDBC===

Java CallableStatements provide a means of calling stored procedures. Model 204 SQL does not support stored procedures; therefore, Connect★ for JDBC does not implement the CallableStatement interface.

Calling any CallableStatement method will result in an Unsupported Method SQLException.

An alternative to CallableStatement is the RCLStatement class, which allows execution of SOUL statements and procedures. You can use the following methods for RCL processing:
close()
createStatement()
execute()
executeQuery()
getResultSet()
getResultSetType()
getTransactionIsolation()
nativeSQL() 

===BLOB and CLOB support===

Connect★ for JDBC supports Model 204 BLOB and CLOB data types in SQL update and retrieval statements.

Use the following ResultSet methods to retrieve large object column data after SELECT statement execution.
BLOB
byte[] getBytes()
Object getObject()
InputStream getBinaryStream()
CLOB
byte[] getBytes()
Object getObject()
String getString()
InputStream getAsciiStream()
InputStream getBinaryStream()
java.io.Reader getCharacterStream()
InputStream getUnicodeStream()

In INSERT and UPDATE statements, use parameters for large object columns. First, create a prepared statement, then set the values of the parameters with the following PreparedStatement methods.
BLOB
setBytes()
setObject()
setBinaryStream()
CLOB
setBytes()
setObject()
setAsciiStream()
setBinaryStream()
setCharacterStream()
setUnicodeStream()

===j204.jar file===

You must include the j204.jar file in the classpath for both compilation and execution. See your Java documentation for a complete list of options.

Note that the j204.jar file can be placed anywhere as long as the classpath points to its directory.

====Compilation example====
javac -classpath c:\jdbc\yourClasses;c:\jdbc\j204.jar
yourProgram.java

====Execution example====
java -cp .;c:\jdbc\yourClasses;c:\jdbc\j204.jar yourProgram

===Debug tracing for JDBC===

To create a trace log file, use the TRACE=ALL parameter in the connection string. See [[#Connection parameters|Connection parameters]].

====J204Driver log file location====

For applications run under Windows 7, the driver places the log file in the user's home directory.
<ul>
<li>Under Windows 7, the directory would be: 
C:\Users\<var class="term">user_name</var>
</li>
<li>
Under Windows XP, the directory would be: 
C\Documents and Settings\<var class="term">user_name</var>
</li>
</ul>
For other operating systems, the log file is placed in the same directory as the j204.jar file.

==Connection pooling==

Connect★ version 7.5 and higher for JDBC offers a "connection pooling" class to interface with other pooling infrastructures provided by pooling packages and web application servers. This new feature allows for a pool of connections that remain active and open during execution of an SQL and RCL (SOUL) statement.

Using connection pooling helps eliminate the overhead of creating initial connections from scratch or trying to manage each connection using the JDBC API.

Each Connection Pool can create a pool of active connections maintainable throughout the connection cycle of the pooling service.

Connect★ version 7.5 and higher for JDBC has been tested with the JNDI, Apache DBCPTM, BoneCP, and C3PO pooling packages.

===Connection pooling example===

Below is an example of pooling connections using the [http://commons.apache.org/proper/commons-dbcp/ Apache Commons DBCPTM] component. There are other examples provided in the install directory of Connect★ for JDBC:
<nowiki>/**
* Example: Pooling Connection program using Apache DBCP (Database Connection
* Pooling) Package
*/

package com.cca.j204.tests;

import javax.sql.DataSource;
import java.sql.Connection;
import java.sql.Statement;
import java.sql.ResultSet;
import java.sql.SQLException;

// Using the Apache DBCP BasicDataSource.
// The example is using the following libraries:
// commons-dbcp-1.x.jar
// commons-pool-1.x.jar

import org.apache.commons.dbcp.BasicDataSource;

public class SimpleDBCPExample {

public static void main(String[] args) {

BasicDataSource basicDatasource = new BasicDataSource();
basicDatasource.setDriverClassName("com.cca.j204.J204Driver");
basicDatasource.setUsername("user");
basicDatasource.setPassword("password");
basicDatasource.setUrl("jdbc:j204://mainframe.domain.com:2403/rcl");
basicDatasource.setInitialSize(5); // Set up 5 connections at initialization

DataSource dataSource = basicDatasource;
String statement = "VIEW ALL;"; // SOUL Statement

// Show statistics before the connections are established
System.out.println("Statistics before the connections are established.");
showStatistics(dataSource);

// Now, we can use JDBC DataSource as we normally would.
Connection connectionHandle = null;
Statement statementHandle = null;
ResultSet results = null;

try {
System.out.println("Creating connection.");
connectionHandle = dataSource.getConnection();//Start all 5 connections at once.

// Show statistics while the connections are established
System.out.println("Statistics after initializing the connections.");
showStatistics(dataSource);

System.out.println("Creating statement.");
statementHandle = connectionHandle.createStatement();

System.out.println("Executing statement.");
results = statementHandle.executeQuery(statement);

System.out.println("Show Results:");
int numcols = results.getMetaData().getColumnCount();
while(results.next()) {
for(int i=1;i<=numcols;i++) {
System.out.print("\t" + results.getString(i));
}
System.out.println("");
}

// Show statistics while the connections are established
System.out.println("Statistics while the connections are established.");
showStatistics(dataSource);

results.close();
statementHandle.close();
connectionHandle.close();

// Show statistics after the connections have been closed
System.out.println("Statistics after the connections have been closed.");
showStatistics(dataSource);

// Clean up and close all of the pooled connections
basicDatasource.close();

} catch(SQLException ex1) {
System.out.println("SQLException in main(): " + ex1.getMessage());
}

}

// Print out the statistics from the BasicDataSource class
public static void showStatistics(DataSource ds) {
BasicDataSource bds = (BasicDataSource) ds;
System.out.println("Number of Active Connections: " + bds.getNumActive());
System.out.println("Number of Idle Connections: " + bds.getNumIdle());
}

}</nowiki>

The sample code generates this output:
<nowiki>
Statistics before the connections are established.
Number of Active Connections: 0
Number of Idle Connections: 0

Creating connection.

Statistics after initializing the connections.
Number of Active Connections: 0
Number of Idle Connections: 5

Creating statement.
Executing statement.

Show Results:

VERSION 7.4.0K RELEASE OF MODEL 204
CMSVERSN VERSION OF THE CMS INTERFACE
SYSOPT X'AB' SYSTEM OPTIONS
SYSOPT2 X'00' SYSTEM OPTIONS
OPSYS X'D209E8' OPERATING SYSTEM
SYSID RS26 SMF SYSTEM IDENTIFICATION
JOBNM M204MWD JOB NAME
STEPNM ONLINE STEP NAME
JOBSTEP MPONLINE JOB STEP NAME
JESID J0919076 JES JOB ID
LOCATION D204 LOCATION
LSERVPD 8176 LENGTH OF SCHEDULER PDL
NUSERS 432 NUMBER OF USERS
NSERVS 15 NUMBER OF SERVERS
SERVNSA X'00000000' NON SWAPPABLE SERVER AREAS
SERVNSSZ 0 NON SWAPPABLE SERVER AREA SIZE
NJBUFF 36 NUMBER OF JOURNAL BUFFERS

.... (continue output)

Statistics while the connections are established.
Number of Active Connections: 1
Number of Idle Connections: 4

Statistics after the connections have been closed.
Number of Active Connections: 0
Number of Idle Connections: 5 </nowiki>

==See also==

{{Template: Connect* topic list}}

[[Category: Connect*]]

URI (XmlDoc/XmlNode function)

2016-05-04T19:22:36Z

Mlarocca: /* Examples */

{{Template:XmlDoc/XmlNode:URI subtitle}}
<var>URI</var> returns the "Uniform Resource Identifier" (URI) associated with the name of the node that is the head of an [[XPath]] result.

==Syntax==
{{Template:XmlDoc/XmlNode:URI syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>%unicode</th>
<td>A <var>Unicode</var> string variable for the returned URI. Prior to <var class="product">[[Sirius Mods]]</var> Version 7.6, this variable is an EBCDIC string.</td></tr>

<tr><th>nr</th>
<td>An <var>XmlDoc</var> or <var>XmlNode</var>, used as the context node for the <var class="term">xpath</var> expression. If an <var>XmlDoc</var>, the <var>Root</var> node is the context node.</td></tr>

<tr><th>xpath</th>
<td>A <var>Unicode</var> string that is an [[XPath#XPath_syntax|XPath expression]] that results in a nodelist. The head of the nodelist is the node to process. Any other nodes in the nodelist are ignored.

This is an optional argument, and its default is a period (<tt>.</tt>), that is, the node referenced by the method object <var class="term">nr</var>.</td></tr>
</table>

==Usage notes==
<ul>
<li>The Uniform Resource Identifier (URI) of a node is defined to be:
<ul>
<li>The URI of the namespace declaration in scope for the prefix of the element-type or attribute name if there is one.
<li>The URI of the default namespace declaration in scope for an unprefix of element-type.
<li>The null string, otherwise.
</ul>

<li><var>URI</var> may only be used if the <var>XmlDoc</var>'s <var>[[Namespace (XmlDoc property)|Namespace]]</var> property is <var>On</var>.

<li>Namespace-aware applications should use the namespace URI rather than the prefix to identify elements.

<li>As of <var class="product">Sirius Mods</var> Version 7.3, the method's argument and result may include only non-null EBCDIC characters that translate to Unicode.

As of <var class="product">Sirius Mods</var> Version 7.6, these strings are <var>Unicode</var> or are converted to <var>Unicode</var>. For more information about the effects of this Version 7.6 change, see [[XmlDoc API#Strings and Unicode with the XmlDoc API|Strings and Unicode with the XmlDoc API]].
</ul>

==Examples==
In the following example, the URI of the first element
and the null string are printed:
begin
%d object xmlDoc
%d = new
%n1 object xmlNode
%n2 object xmlNode
%n1 = %d:[[AddElement_(XmlDoc/XmlNode_function)|addElement]]('foo:bar', , 'ftp:here')
print 'URI =' and %n1:URI
%n1 = %n1:addElement('junk')
print 'URI =' and %n1:URI
end

The example result follows:
URI = ftp:here
URI =


==Request-cancellation errors==
This list is not exhaustive: it does not include all the errors that are request cancelling.
<ul>
<li><var>XmlDoc</var> <var>Namespace</var> property value not <var>On</var>.
<li><var class="term">xpath</var> expression is invalid.
<li>Result of (<var class="term">xpath</var>) is empty.
<li>Insufficient free space exists in CCATEMP.
</ul>

==See also==
<ul>
<li>For more information about using XPath expressions, see [[XPath]].
<li>These methods also obtain information about the name of a node:
<ul>
<li><var>[[LocalName (XmlDoc/XmlNode function)|LocalName]]</var>
<li><var>[[Prefix (XmlDoc/XmlNode function)|Prefix]]</var>
<li><var>[[QName (XmlDoc/XmlNode function)|QName]]</var>
</ul>
</ul>

{{Template:XmlDoc/XmlNode:URI footer}}

Model 204 configurations and operating environments

2016-05-03T16:23:40Z

Mlarocca: /* Model 204 entities in above the bar storage */

This page provides an overview of <var class="product">Model 204</var>. The structure of the <var class="product">Model 204</var> database management system, basic <var class="product">Model 204</var> configurations, and the hardware and software environments required to run <var class="product">Model 204</var> are summarized for the view of the person managing Model 204 system resources. 

For a list of all the Model 204 system management topics, see [[:Category:System management|Category:System management]]. 

==About Model 204==

<var class="product">Model 204</var> is a complete database management system that provides facilities for the creation, control, query, and maintenance of database files. Data intensive batch and online application systems can be developed with <var class="product">Model 204</var>'s self-contained [[SOUL]] language (formerly called User Language) and embedded TP monitor. Application languages, such as Assembler, COBOL, PL/I, and FORTRAN can communicate with <var class="product">Model 204</var> functions through the <var class="product">[[Media:M204_HLIReference_V75.pdf|Model 204 Host Language Interface]]</var>. <var class="product">Model 204</var> supports SQL queries using the Horizon and CRAM interfaces.

<var class="product">Model 204</var> contains a system of [[Introduction_to_User_Language#Files|files]], [[File architecture overview#Summary|tables]], runtime and user [[Overview of Model 204 parameters|parameters]], and software that frees users from the physical structure of the data and allows convenient, controlled access to that data.

<ul>
<li> Sequential system and work files provide system input and output.</li>

<li> Tables store information necessary for running specific requests.</li>

<li> Runtime parameters handle execution-time and system-input-stream specifications.</li>

<li> User parameters control the environment of each online user. </li>
</ul>


A <var class="product">Model 204</var> database consists of files that utilize large fixed-length physical pages of 6184 bytes each. Each file is logically composed of four tables in which indexes and data are maintained. Entry order, unordered, sorted, and hash key file structures are supported. 

Organization and maintenance of the data files are discussed in the [[:Category:Model 204 files|Model 204 files]] topics. Access and manipulation of data files are discussed in the [[:Category:SOUL|SOUL]] topics and in the <var class="book">Rocket Model 204 Host Language Interface Reference Manual</var>. 

===Model 204 system management===

Rocket Software recommends that each installation designate a person to be the <var class="product">Model 204</var> System Manager. The System Manager's responsibilities include:

<ul>
<li> Installing and maintaining the Rocket <var class="product">Model 204</var> software</li>

<li> Setting up and maintaining the OS or DOS JCL or CMS EXECs and <var class="product">Model 204</var> parameters for the <var class="product">Model 204</var> configurations used at an installation</li>

<li> Setting up [[:Category:Security management|system security]]</li>

<li> Acting as a liaison with [[Contacting Rocket Software Technical Support|Rocket Technical Support]]. </li>
</ul>

The System Manager's position is usually a part-time job in a small to medium size database environment. Often the System Manager also has the responsibilities of File Manager, also known as <var class="product">Model 204</var> database administrator. If you are the System Manager only, Rocket Software strongly recommends that you study the Rocket <var class="product">Model 204</var> [[:Category:Model 204 files|Model 204 files]] topics as well as the [[:Category:System management|system management]] topics, because you will be working closely with the File Manager.

==Model 204 configurations==

The basic <var class="product">Model 204</var> configurations are listed in the table below. Various configurations, such as IFAM2 and ONLINE, can be combined to meet site requirements.

<table>
<caption>Model 204 configurations</caption>
<tr class="head">
<th>
Configuration
</th>
<th>
Description
</th>
</tr>
<tr>
<td>
BATCH204
</td>
<td>
Handles a single user in batch mode.
</td>
</tr>
<tr>
<td>
ONLINE
</td>
<td>
Supports a batch user and a number of online users. 
</td>
</tr>
<tr>
<td>
IFAM1
</td>
<td>
Supports host language calls to <var class="product">Model 204</var> files from multiple users. Programs are run as separate tasks in a single region,
partition, or virtual machine. 
</td>
</tr>
<tr>
<td>
IFAM2
</td>
<td>
Supports host language calls to <var class="product">Model 204</var> files from multiple users. Each program operates in its own region, partition, or virtual machine. 
</td>
</tr>
<tr>
<td>
IFAM4
</td>
<td>
Supports host language calls to <var class="product">Model 204</var> files from multiple users. Programs are run as separate tasks in a single region, partition, or virtual machine.
</td>
</tr>
<tr>
<td>
BATCH2
</td>
<td>
Establishes a User Language connection to a <var class="product">Model 204</var> ONLINE running in a separate region. 
</td>
</tr>
</table>

===Operating systems===

<var class="product">Model 204</var> uses the same basic system architecture, file architecture, and User Language with each compatible operating system. Unique system characteristics that must be considered when running <var class="product">Model 204</var> are discussed, where appropriate, throughout this manual.

<var class="product">Model 204</var> is compatible with all versions of z/OS, z/VM, and z/VSE currently supported by IBM. For details, see [[Model 204 system requirements]].

The <var class="product">Model 204</var> ONLINE configurations for each operating system are explained in detail in the appropriate Rocket <var class="product">Model 204</var> Installation Guides. Refer also to [[Defining the runtime environment (CCAIN)]], [[Defining the user environment (CCAIN)]], and [[Controlling system operations (CCAIN)]] for information on system and user commands and parameters.

==Operating environments==

<var class="product">Model 204</var> runs in an IBM mainframe environment with z/OS, z/VM, and z/VSE operating systems. 

===CPU===

<var class="product">Model 204</var> runs on all mainframes that support z/Architecture principles of operations. Mainframes with ESA/390 architecture are supported from 9672 RA4 (Generation 3) and Multiprize 2000 and up.

MP/204 is an optional enhancement to <var class="product">Model 204</var> that provides full support for multiprocessor hardware configurations under z/OS.

31-bit addressing is also supported in all operating environments. When running in 31-bit mode, <var class="product">Model 204</var> allocates several data structures above the 16-megabyte line.

<var class="product">Model 204</var> supports 64-bit real storage and captured UCB allocated above the 16-megabyte line for z/OS and z/VM operating systems.

===Direct Access Storage Devices (DASD)===

<var class="product">Model 204</var> supports the devices listed in this table:

<table>
<caption>DASD device types</caption>
<tr class="head">
<th>Type</th>
<th>Model</th>
</tr>

<tr>
<td>
CKD
</td>
<td>
3380, 3390
</td>
</tr>

<tr>
<td>
ECKD
</td>
<td>
9345
</td>
</tr>

<tr>
<td>
FBA
</td>
<td>
337x, 9332, 9335
</td>
</tr>
</table>

===Shared DASD and Global Resource Serialization===

A shared DASD environment is one in which disk volumes may be shared between operating systems. <var class="product">Model 204</var> is supported under the three IBM operating systems: z/OS, z/VM, and z/VSE. A number of customers run <var class="product">Model 204</var>, concurrently, under at least two of those three systems.

Many customers run <var class="product">Model 204</var> in the z/OS LPAR (Logical PARtition) environment where different versions of z/OS share disk volumes. In these systems, <var class="product">Model 204</var> jobs, ONLINE or BATCH, may be running concurrently in any of the defined LPARs and may be sharing disk volumes between those LPARs.

<var class="product">Model 204</var> file integrity in these multi-operating-system environments has always been provided through the Shared DASD Enqueue list, stored and maintained in the File Parameter List (FPL) page of each <var class="product">Model 204</var> file. Maintaining the Shared DASD Enqueue list, and therefore file integrity in a multi-operating-system environment, is totally dependent on the use of the device <code>RESERVE</code> macro. 

The <code>RESERVE</code> macro provides exclusive access to a device. Therefore, any <var class="product">Model 204</var> job running under any operating system will have exclusive access to a <var class="product">Model 204</var> file during file open. File open is the event that adds, updates, or removes entries in the SHARED DASD ENQUEUE list. These entries indicate which <var class="product">Model 204</var> job, virtual machine, or partition has the file open and whether that instance of <var class="product">Model 204</var> has share (read-only) or exclusive (update) access to the file. You can display these entries using the following command:

ENQCTL filename

It is therefore critical for <var class="product">Model 204</var> file integrity that the device <code>RESERVE</code> macro be allowed to function on all devices shared in a multi-operating-system environment where <var class="product">Model 204</var> jobs might run.

===ENQCTL command enhanced===

The <var>[[ENQCTL command|ENQCTL]]</var> command lists all entries in the shared DASD enqueue list that reside in a file's File Parameter List (FPL) — more than the previous maximum of eight entries. 

Also, formerly when a file could not be opened due to shared DASD enqueueing conflicts, a maximum of eight entries was listed using the <code>M204.0582</code> message number. With the enhancement to the <var>ENQCTL</var> command the <code>M204.0582</code> message is issued as many times as necessary.

===Cautions using Global Resource Serialization===

The IBM Global Resource Serialization (GRS) feature available under z/OS may be configured to suppress the use of the device RESERVE macro. If this suppression is enabled, <var class="product">Model 204</var> file integrity cannot be guaranteed and data will become corrupted.

For this reason, it is imperative that the GRS Resource Name List (RNL) be configured to allow the RESERVE macro to be passed, in the channel program constructed by <var class="product">Model 204</var>, to any device where a <var class="product">Model 204</var> file is allocated in a shared DASD environment. 

For additional information regarding <var class="product">Model 204</var> files and shared DASD, please see:

<ul>
<li><var>[[ENQCTL command|ENQCTL]]</var> command for shared DASD enqueue control</li>

<li>[[Defining the runtime environment (CCAIN)#Shared DASD locking conflicts|Shared DASD locking conflicts]]</li>

<li>[[Using the system scratch file (CCATEMP)#CCATEMP in system recovery|CCATEMP in system recovery]]</li>
</ul>

==64-bit architecture support==

<var class="product">Model 204</var> runs in 64-bit mode on z/OS and z/VM systems.

===Understanding above the bar storage===

In 64-bit mode z/OS and z/VM may create a region that has storage above the 2-gigabyte line called the bar. Address spaces with above the bar storage consist of three areas:

<table>
<tr class="head">
<th>
Storage location 
</th>
<th>
Used for...
</th>
</tr>

<tr>
<td>
In 0-2 gigabyte range 
</td>
<td>
Programs and data
</td>
</tr>

<tr>
<td>
Above 4 gigabytes
</td>
<td>
Data only
</td>
</tr>

<tr>
<td>
Note: In 2-4 gigabyte range
</td>
<td>
Unavailable for any purpose
</td>
</tr>
</table>

===Set the IBM MEMLIMIT system option===

To implement above the bar storage IBM requires that you set a limit on how much of that virtual storage each address space can use. This limit is called <code>MEMLIMIT</code>. If you do not set MEMLIMIT, the system default is 0, meaning no address space can use above the bar virtual storage. To allocate <var class="product">Model 204</var> data structures such as buffer pool above the bar, MEMLIMIT should be properly set when running this release.

IBM provides several options to override the system default. Use one of the following options when you install and run <var class="product">Model 204</var>:

<ul>
<li>SMF MEMLIMIT parameter</li>

<li>MEMLIMIT on JOB and EXEC statement</li>

<li>MEMLIMIT environment through IEFUSI</li>
</ul>

z/OS customers running on z/OS 1.10 and later are afforded a default of 2 Gigabytes of above the bar storage per address space, replacing the previous default of 0 Gigabytes. Thus customers running on this operating system level do not need to set MEMLIMIT or <code>REGION=0M</code> to acquire above the bar storage.

Refer to IBM documentation about MEMLIMIT and limiting above the bar storage use in z/Architecture to implement the option that best meets your site requirements.

The use of real storage below the 2-gigabyte address is not controlled by MEMLIMIT. Only the amount of virtual storage is controlled by MEMLIMIT.

===Model 204 entities in above the bar storage===
The following <var class="product">Model 204</var> entities can be accessed directly in above the bar storage:

<ul>
<li> Pages from Tables A, B, E, and X </li>

<li> Index, procedure, and existence bit map pages from Table D</li>

<li> CCATEMP pages with found sets, screens and images, and transaction backout log</li>

<li> NUMBUFG number of ATB buffers</li>

<li> Saved compiled APSY procedures</li>

<li> CCASERVR for swapped out users</li>

<li> FTBL (as of version 7.4)</li>

<li> GTBL, NTBL, QTBL (as of version 7.5)</li>

<li> RTBL, KTBL, STBL, VTBL, XTBL, ITBL, FSCB, TTBL, HTBFRS (as of version 7.6)</li>

</ul>

===Handling 64-bit statistics===

To support very long running <var class="product">Model 204</var> regions, Rocket Software has modified the capacity of statistical counters by increasing the size of some statistics and also exploiting 64-bit processing where appropriate. For any in-house or third-party support applications that process statistical counters, you will need to review the statistics generated.

As some of the statistics fields are now double words, check [[Using system statistics]] for the new layout of the System, Final, and Partial statistics. Also, additional Disk Buffer Monitor, MP/204, and File statistics have been updated.

Look at your in-house or third-party support applications to see if you need to make changes because of the increased length of some of the statistics. Make any changes necessary to your applications, then reassemble with this new release.

Even if your in-house or third-party support applications do not refer to any of these double word statistics, you must reassemble your applications since all statistics offsets have changed.

==Model 204 storage==

The <var class="product">Model 204</var> program acquires all its working storage space dynamically. Working storage includes server areas, resource locking tables, buffer space, and control blocks.

The region or partition in which <var class="product">Model 204</var> runs must be large enough to contain the <var class="product">Model 204</var> code and the dynamically acquired working storage space.

Information about tracking dynamic storage allocation is provided in [[Performance monitoring and
tuning]].

===z/VSE storage considerations===

The following considerations apply to a z/VSE environment: 

<ul>
<li> <var class="product">Model 204</var> allocates storage in the partition GETVIS area.

When running in z/VSE, the partition must be large enough to hold the executable phase (program) and have enough GETVIS area for <var class="product">Model 204</var> to allocate working storage.</li>

<li> If the JCL EXEC statement <code>SIZE</code> parameter is missing, the size of the GETVIS area is equal to the default size (48K, unless defined in the IPL procedures).</li>

<li> If there is insufficient storage, the SIZE parameter should specify partition space approximately equal to the program size, leaving a small (not less than 48K for z/VSE) partition GETVIS area.

In the case of an ONLINE system or an IFAM1 job, 48K of GETVIS area is not enough for an efficient system.

The SIZE parameter is strongly recommended for an ONLINE environment.
</li>

<li>The SIZE parameter is required when using IFAM1. If a PL/I Host Language program is used, <var class="product">Model 204</var> must take its dynamic storage from the partition GETVIS area through a SIZE parameter specification. </li>
</ul>

===CMS disk considerations===

Native CMS versions of <var class="product">Model 204</var> support files on variable-format disks and CMS-format disks. The disks can be partial- or full-volume minidisks, or dedicated volumes.

File location on the disks affects performance. Put all <var class="product">Model 204</var> files on variable-format disks for optimum access and performance.

<ul>
<li> Use variable-format disks for files that experience high levels of activity. The <var class="product">Model 204</var> CMS interface supports asynchronous I/O operations through SIO-level logic and associated interrupt handling facilities. As a result, significant overlap between I/O and processing is achieved when variable-format disks are used.

Files on variable-format disks must be preallocated. A primary allocation is required. Secondary extents can be specified to permit limited extension of the file. File allocation information is recorded in the Volume Table Of Contents (VTOC).</li>

<li> CMS-format disks affect performance by increasing I/O service time. </li>

<li> Additional arm motion and rotational delay caused by logical blocks of data spanning multiple physical blocks on a CMS-format disk extend the duration of I/O operations.</li>

<li> Synchronous DASD I/O operations (suspension of the virtual machine until the I/O operation completes) increase I/O service time. </li>
</ul>

Files on CMS-format disks do not require preallocation. Files increase dynamically as data is added, and are restricted in size only by the space available on the minidisk. New files are created automatically the first time they are referenced. Each CMS-formatted minidisk has its own Master File Directory (MFD) that contains allocation information for each file. When all the files are closed, the MFD maintained in virtual storage is transferred to disk. The CMS volume on which files exist is recorded in the MFD.

==Related Rocket Software products==

As the <var class="product">Model 204</var> system manager, you might be required to manage the following Rocket Software products, which can access <var class="product">Model 204</var> data.

===Analytics/204===

Analytics/204 is a PC-based visual data analysis tool that helps business users get to know their data, access their data, and trust their data, and without the need for IT assistance. Working in a Windows-based point-and-click environment, business users are able to:

<ul>
<li> Acquire a better understanding of the data, </li>

<li> Create subsets or segments of the data for targeted analytical or operational purposes, and </li>

<li> Display or export the data in whatever format is required for maximum decision-making. </li>
</ul>

<div id="Connect* and Horizon"></div>

===Connect★ and Horizon===

Connect★ offers a client/server environment. On the client side, people use the PC software already familiar to them. On the server side is <var class="product">Model 204</var>, ensuring high-performance database management. Connect★ unites the two through SQL. Alternatively, using Rocket Software's Remote Command Line facility, desktop applications can access <var class="product">Model 204</var> data through Rocket Software's [[SOUL]] language.

===JDBC for Model 204===

The JCBC for <var class="product">Model 204</var> product enables you to access <var class="product">Model 204</var> using the Java language. JDBC for <var class="product">Model 204</var> specifically supports Connect<var> </var> .

===MP/204===

[[Performance monitoring and tuning#Multiprocessing (MP/204)|MP/204]] enables a single copy of <var class="product">Model 204</var> to leverage multiprocessing configurations on IBM or compatible mainframes running z/OS/XA or z/OS/ESA. The result: significant performance enhancements in both system throughput and response times by utilizing parallel CPU processing.

===MQ/204===

MQ/204 provides SOUL extensions to manipulate MQSeries message queues and receive and send data throughout your enterprise. Application developers are increasingly turning to Message Queuing Middleware (MQM) for program-to-program communication. MQM is especially useful for supporting applications that are distributed across different platforms and have only intermittent or long-distance network connections between them.

===Parallel Query Option/204===

With Parallel Query Option/204 (PQO) you can raise the performance of <var class="product">Model 204</var> by a factor of two, three, four or more. PQO lets you break up massive queries into smaller pieces, which are then searched and sorted simultaneously in parallel. PQO finds answers faster because the requests access smaller sets of data. Requesters get their answers sooner and other users' queries don't wait as long in the queue. 

You can share data between production, test, and historical data regions. You can access <var class="product">Model 204</var> data residing on one region from any number of other <var class="product">Model 204</var> regions. Furthermore, PQO lets you distribute <var class="product">Model 204</var> regions within the same machine, on different machines, or across different IBM operating systems.

[[Category:System management]]
[[Category:Model 204 operational issues]]

SoftSpy installation guide

2016-04-28T19:39:31Z

Mlarocca: /* Set the Authorized Product Configuration */

==Introduction==

This page provides installation instructions for the
following products: 
<ul>
<li>SoftSpy for <var class="product">Model 204</var>, Version 7, Release 5.0 or Release 4.0</li>
<li>MUSE for <var class="product">Model 204</var>, Version 7, Release 5.0 or Release 4.0</li>
</ul>
Version 7 Release 5.0 of these products supports <var class="product">Model 204</var> Version 7 Release 5.0 and Model 204 Version 7 Release 4.0. 
Version 7 Release 4.0 of these products supports <var class="product">Model 204</var> Version 7 Release 4.0.

SoftSpy provides debugging features to help you develop, test, and maintain User Language applications. Add-on features include interactive debugging, performance tuning, quality assurance testing, and error audit options.

MUSE is a multi-use facility based on the <var class="product">Model 204</var> USE
command.

Installation of SoftSpy should be done by the organization responsible for the installation and maintenance of <var class="product">Model 204</var>. When performing the installation, you should have a copy of the Rocket <var class="product">Model 204</var> Installation Guide for your operating system. You should review all relevant sections of these pages before proceeding with the installation.

When you have completed the installation instructions detailed in this document, SoftSpy and MUSE will be installed. To install SoftSpy and MUSE in additional ONLINE or BATCH204 jobs, refer to [[#Additional_Installations|Additional Installations.]]

===Overview of Installation===

SoftSpy consists of <var class="product">Model 204</var> nucleus extensions and Model
204 User Language procedures. The SoftSpy installation process installs the
User Language procedures, and it modifies your <var class="product">Model 204</var> systems to make SoftSpy available for use.

This installation guide is organized into sections that provide instructions for each operating system, followed by sections that provide instructions common to all operating systems. 

The operating-system-specific topics (z/OS, z/VM, or z/VSE) describe:

<ul>
<li>Prerequisite <var class="product">Model 204</var> installation steps</li>
<li>Allocation of SoftSpy files</li>
<li>Required DD/DLBL/FILEDEF statements for SoftSpy files</li>
</ul>

Common installation sections are:
<ul>
<ul><li>[[#Updating_CCAIN|Updating CCAIN]]</li>
<li>[[#Online installation steps|Online installation steps]]</li>
<li>[[#Verifying the installation|Verifying the installation]] </li></ul>
</ul>
<div></div>

===SoftSpy and Model 204 version 7.4===
It is recommended that you install the SoftSpy version 7.5 SPYPROC file, because it is more robust than the 7.4 version.

The SoftSpy SOUL code (SPYPROC file) for 7.5 is compatible with Model 204 versions 7.4 and 7.5.

<ul>
<li>If you are currently running SoftSpy version 7.4 with Model 204 version 7.4, you can upgrade to SoftSpy 7.5 by downloading the SPYPROC file. (See the section "Downloading and installing SoftSpy 7.5 files" for your operating system later on this page.)</li>
<li>If you are installing SoftSpy for the first time with Model 204 version 7.4, you must install the SoftSpy object as described in [[SoftSpy version 7.4 installation files]] before downloading the 7.5 SPYPROC file.</li>
</ul>

==Installation on IBM z/OS==

This section describes the SoftSpy installation steps that are specific to the IBM z/OS operating system.

Complete the z/OS-specific part of the installation process before performing the installation steps in the following sections, which apply to all operating system environments:
<ul>
<li>Update CCAIN</li>
<li>Online Installation Steps</li>
<li>Verify the Installation</li>
</ul>
===Prerequisite: Installing Model 204===

Before installing this version of SoftSpy, you must have completed these <var class="product">Model 204</var> installation steps:

<ul>
<li>Install <var class="product">Model 204</var> nucleus</li>
<li>Install Dictionary/204</li></ul>

For details about Model 204 version 7.5, see [[Upgrading to Model 204 version 7.5 on IBM z/OS]].

For details about Model 204 version 7.4, see the <var class="book">[http://m204wiki.rocketsoftware.com/images/d/de/M204_V7R4_zOS_Install.pdf Rocket Model 204 Installation Guide for IBM z/OS, version 7.4]</var>.

Notes:
<ul><li>When you link-edit the Model 204 nucleus, ensure that the SSPY and MUSE text decks/CSECTs are linked in.</li>
<li>If you are running Model 204 version 7.4 and you have never installed SoftSpy before, you must [[SoftSpy version 7.4 installation files|install SoftSpy version 7.4]] before upgrading to SoftSpy version 7.5.</li>
</ul>

===Backing up data===

If you are upgrading from a previous version of SoftSpy, it is strongly recommended that you make a backup copy of your existing SPYPROC and SPYDATA files before proceeding. The upgrade process modifies these files, so a backup copy is required if you need to revert to the previous version.

===Downloading and installing SoftSpy 7.5 files on z/OS===

Note: You must have either a [[Rocket M204 user ID]] or a Sirius user ID to download the installation files.

To install the SoftSpy 7.5 files:
<ol>
<li>If you have not previously installed SoftSpy, modify and submit the modify the [[SoftSpy SPYALOC job stream|SPYALOC]] JCL job. This job allocates the <var class="product">Model 204</var> SoftSpy data sets SPYPROC, SPYDATA, and SPYTEMP. The following table shows space requirements for these data sets:
<table>
<tr>
<td>Database Name</td>
<td>Number of 6184-byte pages</td>
</tr>
<tr>
<td>SPYPROC</td>
<td>1000</td>
</tr>
<tr>
<td>SPYDATA</td>
<td >160</td>
</tr>
<tr>
<td>SPYTEMP</td>
<td>112</td>
</tr>
</table>
</li>
<li>SPYPROC, the SoftSpy procedure file, is distributed in a dump format. Download SPYPROC, in binary form, from the [https://m204.rocketsoftware.com/maint/ullist?nickname=ROCKET SOUL files download page] to a workstation file.</li>
<li>Upload the file from your workstation to your z/OS system.</li>
<li>RESTORE the file into a Model 204 SOUL file.</li>
</ol>

===z/OS installation next steps===
The steps in this section apply to both SoftSpy 7.4 and SoftSpy 7.5 installation on z/OS systems.
Once you have uploaded the files into the allocated data sets and converted them to z/OS standard format, continue the installation as follows.
<ol>

<li>Modify the ONLINE startup JCL.
<ul>
<li>If you are installing SoftSpy for the first time, add DD statements for the SPYDUMP, SPYPROC, SPYDATA, and SPYTEMP data sets to your ONLINE startup JCL.
Following are samples of these statements:
//SPYDUMP DD DSN=SYSM.M204.Vrrr.SPYPROC.DUMP,DISP=SHR
//SPYPROC DD DSN=SYSM.M204.Vrrr.SPYPROC.M204,DISP=SHR
//SPYDATA DD DSN=SYSM.M204.SPYDATA.M204,DISP=SHR
//SPYTEMP DD DSN=SYSM.M204.SPYTEMP.M204,DISP=SHR

where <var class="term">rrr</var> is the current release level, such as 750 or 740.</li>

For SoftSpy version 7.4, you will also need to add a DD statement for the ITSAUTH data set:
//ITSAUTH DD DSN=SYSM.M204.ITSAUTH.M204,DISP=SHR

<li>If you are upgrading from a previous version of SoftSpy, you only need to add DD statements for SPYDUMP and SPYPROC. The DD statements for SPYDATA, SPYTEMP, and ITSAUTH should already be present.</li>
</ul>

Notes: The SPYDUMP DD is only necessary to perform the installation and can be removed afterward. For 7.5, the ITSAUTH DD can be removed.</li>

<li>Make sure that the SYSOPT (system options) X'04' bit is off. This setting indicates that <var class="product">Model 204</var> data definition commands can only be executed from within the File Management Facility of Dictionary/204. (This facility is not used to
create and format the SPYDATA and SPYTEMP files and their fields as documented in [[#Online_Installation_Steps|Online installation steps]].) Normal SoftSpy
operation is not affected by the SYSOPT X'04' bit setting.</li>

<li>Continue the installation as described in [[#Updating CCAIN|Updating CCAIN.]]</li>
</ol>

==Installation on IBM z/VM==

This section describes the SoftSpy installation steps that are specific to the z/VM operating system.

Complete this part of the installation process before performing the installation steps in these sections, which apply to all operating system environments:
<ul>
<li>Updating CCAIN</li>
<li>Online Installation Steps</li>
<li>Verify the Installation</li>
</ul>

===Prerequisite: Installing Model 204===

Before installing this version of SoftSpy, you must have completed these <var class="product">Model 204</var> installation steps:
<ul>
<li>Install the <var class="product">Model 204</var> nucleus. </li>
<li>Install Dictionary/204.</li>
</ul>

For details about Model 204 version 7.5, see the Model 204 z/VM installation instructions in [[Upgrading to Model 204 version 7.5 on IBM z/VM CMS]].

For details about Model 204 version 7.4, see the <var class="book">[http://docs.rocketsoftware.com/nxt/gateway.dll/RKBnew556%2Fmodel%20204%2Fprevious%20versions%2Fv7.4%2Fm204_installzvm_v74.pdf Rocket Model 204 Installation Guide for IBM z/VM, version 7.4]</var>

Notes:
<ul><li>When you link-edit the Model 204 nucleus, ensure that the SSPY and MUSE text decks/CSECTs are linked in.</li>
<li>If you are running Model 204 version 7.4 and you have never installed SoftSpy before, you must [[SoftSpy version 7.4 installation files|install SoftSpy version 7.4]] before upgrading to SoftSpy version 7.5.</li>
</ul>

===Backing up data===
If you are upgrading from a previous version of SoftSpy, it is strongly recommended that you make a backup copy of your existing SPYPROC and SPYDATA files before proceeding. The upgrade process modifies these files, so a backup copy is required if you need to revert to the previous version.
===Downloading and installing SoftSpy 7.5 files on z/VM===

Note: You must have either a [[Rocket M204 user ID]] or a Sirius user ID to download the installation files.

To install the SoftSpy version 7.5 files:
<ol>
<li>SPYPROC, the SoftSpy procedure file, is distributed in a dump format. Download SPYPROC, in binary form, from the [https://m204.rocketsoftware.com/maint/ullist?nickname=ROCKET SOUL files download page] to a workstation file.</li>
<li>Upload the file from your workstation to your z/VM system.</li>
<li>RESTORE the file into a Model 204 SOUL file.</li>
</ol>

===z/VM installation next steps===
The steps in this section apply to both SoftSpy 7.4 and SoftSpy 7.5 installation on z/VM systems.
<ol>
<li>Run M204GEN to generate modules and saved segments, as you did when installing the <var class="product">Model 204</var> nucleus. For information, syntax, and rules for M204GEN, see the “M204GEN Command” section in the <var class="book">[http://docs.rocketsoftware.com/nxt/gateway.dll/RKBnew556%2Fmodel%20204%2Fprevious%20versions%2Fv7.4%2Fm204_installzvm_v74.pdf Rocket Model 204 Installation Guide for IBM z/VM, version 7.4]</var>.</li>
<li>Reapply all early warnings. For information, see the “Applying early warnings” section in the <var class="book">Rocket Model 204 Installation Guide for IBM z/VM, version 7.4</var>.</li>
<li>If the SPYPROC, SPYTEMP, and SPYDATA database files will reside on an OS format disk, allocate them at this time. If you are upgrading from a previous version of SoftSpy, you only need to allocate the SPYPROC database file.
<ol style="list-style-type:lower-alpha">
<li>SSPYFDEF is an exec that defines SoftSpy database files. SSPYFDEF resides on the MAINT204 193 disk. Edit SSPYFDEF to conform to your disk naming and file placement conventions. The following table shows space requirements:</li>
<table>
<tr>
<td>Database Name</td>
<td>Number of 6184 byte pages</td>
<td>Number of blocks on FBA devices</td>
</tr>
<tr>
<td>SPYPROC</td>
<td>1000</td>
<td>12500</td>
</tr>
<tr>
<td>SPYDATA</td>
<td>160</td>
<td>2133</td>
</tr>
<tr>
<td>SPYTEMP</td>
<td>112</td>
<td>1500</td>
</tr>
</table>
<li>To allocate SoftSpy files on OS format disks, type:
EXEC SSPYFDEF ALOCSSPY</li>
</ol>
</li>
<li>7.4 only: If the ITSAUTH data set will reside on an OS format minidisk, allocate it at this time.
ITSAUTH is a sequential file that contains authorization data and must be allocated to any job that uses SoftSpy with a DD name of ITSAUTH. ITSAUTH is 1 track in size and consists of fixed length 256 byte records. If the ITSAUTH stream will be on a CMS mini-disk, it does not have to be preallocated. On an OS format minidisk, allocate 8 blocks on FBA devices.
</li>
<li>Modify the ONLINE Startup EXEC. Note: ITSAUTH applies to version 7.4 only.
<ul>
<li>If you are installing SoftSpy for the first time, add FILEDEFs for the SPYDUMP, SPYPROC, SPYDATA, SPYTEMP, and ITSAUTH data sets to your
ONLINE startup JCL. Samples of these FILEDEFs are:
FILEDEF SPYPROC DISK SPYPROC DBVrrr filemode
FILEDEF SPYDUMP DISK SPYPROC DUMP *
FILEDEF SPYDATA DISK SPYDATA DATABASE filemode
FILEDEF SPYTEMP DISK SPYTEMP DATABASE filemode
FILEDEF ITSAUTH DISK ITSAUTH DATA filemode

where <var class="term">rrr</var> is the current release level, such as 750 or 740.

If the SoftSpy files are on OS format disks, use FILEDEFs of the following format:
FILEDEF SPYPROC <var class="term">filemode</var> DSN SPYPROC DBV<var class="term">rrr</var> M204
FILEDEF SPYDUMP DISK SPYPROC DUMP *
FILEDEF SPYDATA <var class="term">filemode</var> DSN SPYDATA M204
FILEDEF SPYTEMP <var class="term">filemode</var> DSN SPYTEMP M204
FILEDEF ITSAUTH <var class="term">filemode</var> DSN ITSAUTH DATA
where <var class="term">rrr</var> is the current release level, such as 750 or 740.
</li>
<li>The installation process placed SPYDUMP on the MAINT204 200 disk. Use this dump of SPYPROC for the restore during the installation
process.</li>
<li>If you are upgrading from a previous version of SoftSpy, you only need to add FILEDEFs for SPYDUMP and SPYPROC. The FILEDEFs for SPYDATA,
SPYTEMP, and ITSAUTH should already be present.</li>
</ul>
Note: The SPYDUMP FILEDEF is only necessary to perform the installation and can be removed afterward.
</li>
<li>Make sure that the SYSOPT (system options) X'04' bit is off.</li>
This setting indicates that <var class="product">Model 204</var> data definition commands can only be executed from within the File Management Facility of Dictionary/204. (This facility is not used to create and format the SPYDATA and SPYTEMP files and their fields as documented in [[#Online installation steps|Online installation steps]].) Normal SoftSpy operation is not affected by the SYSOPT X'04' bit setting.
<li>Continue the installation as described in [[#Updating_CCAIN|Updating CCAIN.]]</li>
</ol>

==Installation on IBM z/VSE==

This section describes the SoftSpy installation steps that are specific to the z/VSE operating system.

Complete this part of the installation process before performing the installation steps in the following sections, which apply to all operating system environments:
<ul><li>Updating CCAIN</li>
<li>Online Installation Steps</li>
<li>Verify the Installation</li></ul>

===Prerequisite: Installing Model 204===

Before installing this version of SoftSpy, you must have completed these <var class="product">Model 204</var> installation steps:
<ul>
<li>Install <var class="product">Model 204</var> nucleus</li>
<li>Install Dictionary/204</li></ul>

For details about Model 204 version 7.5, see [[Upgrading to Model 204 version 7.5 on IBM z/VSE]].

For details about Model 204 version 7.4, refer to the <var class="book">[http://docs.rocketsoftware.com/nxt/gateway.dll/RKBnew556%2Fmodel%20204%2Fprevious%20versions%2Fv7.4%2Fm204_installzvse_v74.pdf Rocket Model 204 Installation Guide for IBM z/VSE, version 7.4]</var>
Notes:
<ul><li>When you link-edit the Model 204 nucleus, ensure that the SSPY and MUSE text decks/CSECTs are linked in.</li>
<li>If you are running Model 204 version 7.4 and you have never installed SoftSpy before, you must [[SoftSpy version 7.4 installation files|install SoftSpy version 7.4]] before upgrading to SoftSpy version 7.5.</li>
</ul>

===Backing up data===
If you are upgrading from a previous version of SoftSpy, it is strongly recommended that you make a backup copy of your existing SPYPROC and SPYDATA files before proceeding. The upgrade process modifies these files, so a backup copy is required if you need to revert to the previous version.

===Downloading and installing SoftSpy 7.5 files on z/VSE===

This section describes how to download and modify the SoftSpy version 7.5 installation files.

Note: You must have either a [[Rocket M204 user ID]] or a Sirius user ID to download the installation files.

<ol>
<li>If you have not previously installed SoftSpy, modify and submit the [[SoftSpy SPYALOC job stream|SPYALOC]] JCL job. This job allocates the <var class="product">Model 204</var> SoftSpy data sets SPYPROC, SPYDATA, and SPYTEMP.</li>
<li>SPYPROC, the SoftSpy procedure file, is distributed in a dump format. Download SPYPROC, in binary form, from the [https://m204.rocketsoftware.com/maint/ullist?nickname=ROCKET SOUL files download page] to a workstation file.</li>
<li>Upload the file from your workstation to your z/VSE system.</li>
<li>RESTORE the file into a Model 204 SOUL file.For detailed instructions, see [http://m204wiki.rocketsoftware.com/index.php?title=Web_help_download_SOUL_files#How_can_the_dump_file_be_uploaded_to_the_mainframe.3F Downloading and restoring SOUL files].</li>
<li>Use the information in SPYPROC to determine size requirements for the dump file.
 Rocket Software provides an optional sample batch job, FTPSSPY, to assist in this transfer. FTPSSPY, cataloged in the JCL library in step 4, defines the file names and data set names used in subsequent installation jobs. If you choose to use FTPSSPY, modify this job as noted in its comments and submit it.
 Note: If you make changes to the names in FTPSSPY, you must use those names for all subsequent installation jobs; otherwise those jobs will fail.</li>
<li>Modify and submit [[Model 204 LINKONLN job stream for IBM z/VSE|LINKONLN]] and [[Upgrading to Model 204 version 7.5 on IBM z/VSE#Linking the BATCH204 phase|LINKB204]] to relink your BATCH204 and ONLINE phases.</li>
<li>Complete the installation process as described in the following section.</li>
</ol>

===z/VSE installation next steps===
The steps in this section apply to both SoftSpy 7.4 and SoftSpy 7.5 installation on z/VSE systems.
<ol>
<li>Allocate the SoftSpy databases and ITSAUTH data set. Note: ITSAUTH applies to version 7.4 only.
<ul>
<li>If upgrading from a prior version of SoftSpy, execute the
[[#SPYRINST JCL|SPYRINST]] job from the JCL library. This job will allocate the new SPYPROC
file.</li>
<li>
If performing a SoftSpy installation for the first time,
execute the [[#SPYINST JCL|SPYINST]] job from the JCL library. This job will allocate SPYPROC,
SPYDATA, SPYTEMP, and ITSAUTH files.</li>
</ul>
<table>
<tr><th>Database Name</th><th>Number of 6184 byte pages</th><th>Number of blocks on FBA devices</th></tr>
<tr><td>SPYPROC</td><td>1000</td><td>12500</td></tr>
<tr><td>SPYDATA</td><td>160</td><td>2133</td></tr>
<tr><td>SPYTEMP</td><td>112</td><td>1500</td></tr>
</table>
</li>
<li>Modify ONLINE Startup JCL.
<ul>
<li>If you are installing SoftSpy for the first time, add DLBL, EXTENT and ASSGN statements for the SPYDUMP, SPYPROC, SPYDATA, SPYTEMP, and ITSAUTH data sets to your ONLINE startup JCL. Following are samples of these statements:
 
// DLBL SPYPROC,'M204.SPYPROC',,DA
// EXTENT SYS021,volser
// ASSGN SYS021,DISK,VOL=volser,SHR
// DLBL SPYDATA,'M204.SPYDATA',,DA
// EXTENT SYS021,volser
// ASSGN SYS021,DISK,VOL=volser,SHR
// DLBL SPYTEMP,'M204.SPYTEMP',,DA
// EXTENT SYS021,volser
// ASSGN SYS021,DISK,VOL=volser,SHR
// DLBL SPYDUMP,'M204.SPYPROC.DUMP',,DA
// EXTENT SYS021,volser
// ASSGN SYS021,DISK,VOL=volser,SHR
// DLBL ITSAUTH,'M204.ITSAUTH',,SD
// EXTENT SYS021,volser
// ASSGN SYS021,DISK,VOL=volser,SHR

</li>
<li>If you are upgrading from a previous version of SoftSpy, then you only need to add DLBL, EXTENT and ASSGN statements for SPYDUMP and SPYPROC.
The DLBL, EXTENT and ASSGN statements for SPYDATA, SPYTEMP, and ITSAUTH should already be present.</li>
Note: The SPYDUMP DD is only necessary to perform the installation and can be removed afterward.</ul>
<li>Make sure that the SYSOPT (system options) X'04' bit is off.
 
The SYSOPT X'04' bit setting indicates that Model 204 data definition commands can only be executed from within the File Management Facility of Dictionary/204. (This facility is not used to create and format the SPYDATA and SPYTEMP files and their fields as documented in [[#Online installation steps|Online installation steps]].) Normal SoftSpy operation is not affected by the SYSOPT X'04' bit setting.</li>
<li>Continue the installation as described in "Updating CCAIN".</li>
</ol>

==Updating CCAIN==

This section describes the changes required to the CCAIN
input stream to install and use SoftSpy. Depending on your situation, the
following changes might be needed, as described in this section:
<ul>
<li>Adding IODEV=55 threads</li>
<li>Adjusting the NUSERS parameter</li>
<li>Ensuring that a large enough server is available</li>
<li>Adjusting the LENQTBL parameter</li>
<li>Adjusting the SPCORE parameter for SoftSpy operation</li>
<li>Adjusting the SPCORE parameter for MUSE operation</li>
</ul>
===Adding IODEV=55 threads===
Every concurrent end user SoftSpy session requires a
separate SoftSpy server thread. Each IODEV=55 statement that you add to the
CCAIN input stream will create a distinct SoftSpy server thread. The following
example illustrates the lines to be added to the CCAIN stream to create three
SoftSpy servers.

<nowiki>IODEV=55,AUTOSYS=C'',LIBUFF=255,LOBUFF=255,NORQS=5
IODEV=55,AUTOSYS=C'',LIBUFF=255,LOBUFF=255,NORQS=5
IODEV=55,AUTOSYS=C'',LIBUFF=255,LOBUFF=255,NORQS=5
</nowiki>
The settings shown for the AUTOSYS and NORQS parameter are
required for SoftSpy to work properly. The settings shown for LIBUFF and
LOBUFF are necessary to minimize SoftSpy server table usage.

In order to use SoftSpy from a particular full screen
thread, the size of the output page buffer (LOUTPB) must match the size of the
output page buffer of an available SoftSpy server thread. If you use different
values for LOUTPB for different full screen threads, then you should create
SoftSpy servers for each distinct value of LOUTPB.

===Adjusting the NUSERS parameter===

The NUSERS parameter needs to be increased by the number of IODEV=55 threads you have added to run SoftSpy servers. An increase in the NUSERS parameter might require a change to the size of the server data set. See the <var class="book">Rocket Model 204 System Manager's Guide</var> for a complete discussion of server data sets.

===Ensuring that a large enough server is available===
SoftSpy servers normally use a <var class="product">Model 204</var> SERVSIZE of
280,000. However, there are cases where a larger server is required. This is
because certain server tables whose sizes cannot be reset by SoftSpy contribute
to overall server size requirements. If the sum of the size of RTBL, LOUTPB,
and LFTBL exceeds 8,000 then a larger server will be required. The server size
requirement is increased beyond 280,000 by the amount that the specified sum
exceeds 8,000. Make sure that at least one in-core server is large enough to
support this requirement.

Information about setting LOUTPB is contained in [[#Adding_IODEV.3D55_threads|Adding
IODEV=55 threads]]. SoftSpy automatically sets LFTBL
to NGROUP*4 for each of the IODEV=55 threads. The size of RTBL depends on the
values of the NGROUP, NFILES, and NRMTFILE parameters. The size of RTBL is
usually the most important influence on increased server size requirements.

If the parallel query option of <var class="product">Model 204</var> is being used then
the size of RTBL is:

( NGROUP + 12 ) * ( NFILES +
NRMTFILE + 3 ) + NRMTFILE + 1 

Otherwise, the size of RTBL is:

( NGROUP + 12 ) * ( NFILES + 3 ) 

In either case, the size of RTBL is rounded up to the next
higher multiple of eight.

===Adjusting the LENQTBL parameter===

When SoftSpy servers are run, the LENQTBL parameter might need
to be increased. The size of the enqueue table is based on the product of
NUSERS and LENQTBL. When NUSERS is small, the value of LENQTBL might need to
be set to at least 500.

===Adjusting the SPCORE parameter for SoftSpy operation===

The SPCORE parameter specifies the amount of storage to be
set aside above and below the 16Mb line for operating system and run-time
dynamic storage requests. The value of this parameter might need to be
increased to accommodate the run-time requirements of SoftSpy. The storage
required can be calculated with the formulas:

[[File:SoftSpy_install_SPCORE_formula.jpg|250 px]]

where n is the number of threads running a SoftSpy
Server, and LOUTPBi is the size of the output page buffer for
the given server thread.

The additional SPCORE requirement is a. The value
derived for b represents the amount of storage that is allocated above
the 16M line and does not impact SPCORE.

To maintain the number of disk buffers, an increase in MVS
region size, CMS virtual machine size, or VSE partition size might be
necessary. If increasing the region size is not viable, you can reduce either the
number of disk buffers or the number of in-memory servers.

===Adjusting the SPCORE parameter for MUSE operation===

When MUSE is in use, additional storage is required. Although
SPCORE is not affected, region (or virtual machine) size could be impacted.

The amount of storage needed for MUSE is computed by summing
the storage requirements of each simultaneous user of MUSE. For each user, the
amount of storage needed by MUSE is:

muse_storage = header_storage
+ max_muse_streams * ( header_storage + 1088 )

where

header_storage = 110 + (
MAXHDR + MAXTRL ) * ( HTLEN + 5 )

and max_muse_streams is the maximum number of MUSE
output streams (created by MUSE OPEN(C) or USE) that will be open at any given
time. For example, if

max_muse_streams = 2

MAXHDR = MAXTRL = 5

HTLEN = 132

then

header_storage = 110 + ( 5 + 5 ) * ( 132 + 5 ) = 1480

muse_storage = 1480 + 2 * ( 1480 + 1088 ) = 6616

==Online installation steps==

This section describes SoftSpy installation steps that are
performed online from within <var class="product">Model 204</var>.

Requirement: These steps must be performed using a
<var class="product">Model 204</var> ONLINE that includes the SPYDUMP, SPYPROC, SPYDATA, SPYTEMP, and ITSAUTH data sets described in the installation section for each operating system.

Prerequisite: The CCAIN input stream for the ONLINE must have been updated as described in [[#Updating_CCAIN| Updating CCAIN]].

Perform the following steps, as described in this section:
<ol>
<li>Log on to <var class="product">Model 204</var>.</li>
<li>Stop the SoftSpy subsystem.</li>
<li>Create and restore the SPYPROC file.</li>
<li>Run the INSTALL.SOFTSPY procedure.</li>
<li>Set passwords for the SPYPROC and SPYDATA files</li>
<li>Set the authorized product configuration.</li>
</ol>

===Logging on to Model 204===

Log on to <var class="product">Model 204</var> using an account with system manager privileges.

LOGON accountname
password

===Temporarily removing IODEV=55 threads===

If SoftSpy has been previously installed, comment out the
IODEV=55 threads and reduce NUSERS by the number of threads that were commented
out.

Add these threads back in and change NUSERS accordingly
before attempting to run SOFTSPY.

===Stopping the SoftSpy subsystem===

If SoftSpy has been previously installed, all use of SoftSpy
must be terminated before you proceed. To terminate SoftSpy, issue the Model
204 command:

STOP SUBSYSTEM SOFTSPY

===Creating and restoring the SPYPROC file===

Create and restore the SPYPROC file using the commands
below:

CREATE FILE SPYPROC
END
OPEN FILE SPYPROC
IN SPYPROC INITIALIZE
RESTORE 128 FROM SPYDUMP

===Running the INSTALL.SOFTSPY procedure===
The creation of the SoftSpy subsystem and the formatting of SPYTEMP and SPYDATA is performed by the INSTALL.SOFTSPY procedure. 
<ol>
<li>To begin the process, enter the following commands:
OPEN SPYPROC
INCLUDE INSTALL.SOFTSPY
This procedure will prompt you for the information it needs to create the subsystem and to initialize or upgrade the SPYDATA file.</li>
<li>
The following prompt appears:

$$Is SOFTSPY currently installed on this ONLINE (Y/N)?
<ul>
<li>If SoftSpy has previously been installed, and you want to perform an upgrade style installation of the new version, respond Y. This will cause access control lists and macros from the previous version contained in the SPYDATA file to be preserved.
</li>
<li>Otherwise, respond N.
</li>
</ul>
</li>
<li>
If you are performing an upgrade style installation, the following prompt appears:
$$Enter READ password for SPYDATA:

Enter a read password (one with at least X'8041' privdef privileges) for the SPYDATA file. If the SPYDATA file cannot be opened with read access using the specified password, the installation process will terminate with an error message.</li>

<li>The following prompt appears:
$$Enter READ/WRITE password for CCASYS:

Enter a read/write password (one with at least X'00C1' privdef privileges) for the CCASYS file. This allows the procedure to perform all required subsystem management for the SoftSpy subsystem. If the CCASYS file cannot be opened with read/write access, the installation process will terminate with an error message.</li>

<li>If a subsystem with the name SOFTSPY is defined that is not the SoftSpy subsystem, the following prompt appears:
$$A subsystem named SOFTSPY already exists. Replace (Y/N)?
<ul>
<li>If you want to replace the existing SoftSpy subsystem with the new
SoftSpy subsystem, respond Y.</li>
<li>If not, respond N. A response of N will terminate the installation process.</li>
</ul>
</li>
<li>The following prompt appears:
$$Enter an Administrator User ID. Press <ENTER> when finished.
Enter the <var class="product">Model 204</var> account of anyone who is to be given <var class="product">Model 204</var> ADMIN SCLASS privileges for the SoftSpy subsystem. Users added will supplement those added by previous installations of SoftSpy. The users in this SCLASS will be able to use the SoftSpy EDIT CONFIG command. Refer to the <var class="book">Rocket SoftSpy Reference Manual</var> for a discussion of EDIT CONFIG.

Subsequent changes to the list of users with ADMIN privileges for the subsystem must be made using the <var class="product">Model 204</var>
Subsystem Management Facility. Refer to the <var class="book">Rocket Model 204 System Manager's Guide</var> for more information.

The user id will be checked for compliance with <var class="product">Model 204</var> conventions but will not be validated for existence in the CCASTAT file. The User ID prompt will appear repeatedly until you respond by pressing the Enter key without entering a User ID. The Model 204 account of the user who is running this procedure is included in the list automatically.</li>
<li>If you are performing an upgrade style installation, you might receive the prompt:
Macro <var class="term">macro_identifier</var> already exists.

1. Replace with NEW version.
2. Discard NEW version.
3. Rename NEW version.
4. Rename OLD version.

$$Please choose an option:

This prompt is issued when a SoftSpy macro being installed has the same name as an existing macro and the new macro is different from the
existing macro.
<ul>
<li>Enter 1 if you want the new version to replace the existing version.</li>
<li>Enter 2 if you want to discard the new version.</li>
<li>Enter 3 to save the new version under a different name.</li>
<li>Enter 4 to rename the existing macro and save the new version with the name displayed.</li>
</ul>

An invalid response will cause the prompt to be redisplayed.

The following prompt appears:
$$Please enter new name or press <ENTER> to accept: "<var class="term">macro_identifier</var>_BAK"

If you select option 3 or 4, you will be prompted for a new name for the new or old version of the macro, respectively. You can respond
with any valid SoftSpy macro name or press ENTER to accept the suggested name <var class="term">macro_identifier</var>_BAK. If <var class="term">macro_identifier</var>_BAK exists, the suggested name will have additional _BAK strings appended to it until a unique name can be presented.
</li>
</ol>

===Set Passwords for the SPYPROC and SPYDATA Files===

The SPYPROC, SPYDATA, and SPYTEMP files are set to private at the end of the successful execution of the INSTALL.SOFTSPY procedure. A read password for the SPYDATA file will be required to install future upgrades to SoftSpy, and a procedure execution password for the SPYPROC file will be required if you need to reinitialize the SPYTEMP file. It is recommended that you assign passwords for these files. The <var class="product">Model 204</var> <var>LOGCTL</var> command is used to add passwords to CCASTAT, as shown in the following example:

LOGCTL A :SPYDATA
READ,X'8441'
<ENTER>
LOGCTL A :SPYPROC
EXECUTE,X'8021'
<ENTER>


In the above example, the password <code>READ</code> is
assigned as the read password for the SPYDATA file, and the password
<code>EXECUTE</code> is assigned as the procedure execution password for the
SPYPROC file. The <code><ENTER></code> notation indicates that the command expects
further input, and the enter key is pressed to take the default. See [[LOGCTL command: Modifying file entries in the password table]] for a complete discussion of the <var>LOGCTL</var> syntax and parameters.

===Set the Authorized Product Configuration===

<ol>
<li>Enter the following command to invoke the SoftSpy configuration editor:
SPY EDIT CONFIG

The editor displays a screen similar to the following figure.

EDIT CONFIG Definition Screen

[[File:SoftSpy_EDIT_CONFIG1.JPG|450 px]]
</li>
<li>Press the FORWARD PF key (PF8) to display the authorization entry screen.
This screen is used to authorize your use of SoftSpy.

EDIT CONFIG Authorization Entry Screen
[[File:SoftSpy_EDIT_CONFIG2.JPG|450 px]]
</li>
<li>Update this screen with any new configuration information, expiration date, and authorization key provided with your installation materials. If your authorization key is for an expiration date that has passed, you must contact Technical Support to obtain a new authorization key. </li>
<li>Once you have made any required changes, press the SAVE PF key (PF6) to save the configuration. Saving the configuration information will write it out to the SPYDATA file. It will also activate SoftSpy servers running in IODEV=55 threads.</li>
<li>Press the QUIT PF key (PF3) to exit the SoftSpy configuration editor. All authorized products should now be ready for use.</li>
</ol>

==Verifying the installation==

This section describes the process of verifying that SoftSpy
and MUSE are correctly installed and available for general use. 

===Verify SoftSpy operation===

<ol>
<li>
To test that SoftSpy server(s) are enabled issue the command:

SPY ON

When SoftSpy has been successfully
turned on, the following message will be displayed prior to the <var class="product">Model 204</var>
command prompt. (There will be a short delay prior to the message while the
SoftSpy User Language code precompiles.)

SPY ON
SPY.021: For the exclusive use of SoftSpy Trial
> 

</li>
<li>Create an ad hoc procedure like the one shown below or include any
existing procedure that you have available.

BEGIN
FOR %I FROM 1 TO 5
%J = %I * %I
PRINT %I AND 'SQUARED IS' AND %J
END FOR
END
</li>

The SoftSpy interactive evaluation screen will now be displayed on your terminal:
SoftSpy Interactive Evaluation Screen
[[File:SoftSpy_Interactive_Evaluation_screen.jpg|450 px]]
<li>Type the command:
WATCH %I, %J
so that you can monitor the values of the percent variables as they change during evaluation. Use PF4 to single step through the procedure or PF5 to run the procedure to its end. You can also refer to the <var class="book">Rocket SoftSpy Reference Manual</var> to try some of the other features of SoftSpy.</li>
<li>At the completion of this test, turn off SoftSpy by issuing the command:
SPY OFF

You can issue the SPY OFF command from
either the <var class="product">Model 204</var> command prompt or from the command area just above the PF key labels on the SoftSpy screen.
</li></ol>

If you experience any difficulties, contact [[Contacting_Rocket_Software_Technical_Support|Technical Support]].

===Verify MUSE operation===

You can run two simple tests to verify that MUSE is
available for use: 

<ol>
<li>To verify command-level MUSE, enter the following command at the Model
204 command prompt:
MUSE CLOSE *
If no errors are issued, then command-level MUSE is active, and ready for use.</li>
<li>To verify statement-level MUSE, enter and run the following request:

BEGIN
MUSE CLOSE *
END

If this simple request compiles and evaluates without errors, then statement-level MUSE is active and ready for use.</li>
</ol>
If you experience any difficulties, contact [[Contacting_Rocket_Software_Technical_Support|Technical Support]].

==Customizing SoftSpy==

This section describes the process of customizing SoftSpy
for site-specific needs.

===Customize the SoftSpy configuration===

SoftSpy uses configuration information to determine the
access authority of end users during SoftSpy sessions. The configuration can
be modified only by those <var class="product">Model 204</var> users whose user identifiers have been
included in the SoftSpy ADMIN SCLASS through subsystem management. The initial
installation process will prompt you for a list of those user identifiers and
perform the required subsystem management tasks. If you want to modify the
list of users who are authorized to perform configuration changes, you must use
<var class="product">Model 204</var> Subsystem Management.

The SoftSpy configuration lets you limit end user access to
certain SoftSpy features. This is done by associating an Access Control List
(ACL) with a SoftSpy privilege through the EDIT CONFIG command. An ACL is a
list of <var class="product">Model 204</var> users who are to be granted privileges. The following table
shows which privileges can be limited and the name of the ACL associated with
each at the completion of an initial installation.

<table>
<tr>
<td>Privilege Name</td>
<td>Associated ACL</td>
<td>Meaning</td>
</tr>
<tr>
<td>M204 Ad Hoc</td>
<td>ADMIN</td>
<td>User can issue M204 command from SoftSpy command line or user macro.</td>
</tr>
<tr>
<td>M204 Macro</td>
<td>null</td>
<td>User can issue M204 command from system macros.</td>
</tr>
<tr>
<td>Read ACL</td>
<td>ADMIN</td>
<td>User can read access control lists.</td>
</tr>
<tr>
<td>Read MACRO</td>
<td>null</td>
<td>User can read system macros.</td>
</tr>
<tr>
<td>SoftSpy Server</td>
<td>ADMIN</td>
<td>User can issue the SPY SERVER command.</td>
</tr>
<tr>
<td>Spy ON</td>
<td>null</td>
<td>User can issue the SPY ON command.</td>
</tr>
<tr>
<td>Update ACL</td>
<td>ADMIN</td>
<td>User can update access control lists.</td>
</tr>
<tr>
<td>Update MACRO</td>
<td>ADMIN</td>
<td>User can update system macros.</td>
</tr>
</table>
<var class="product">Model 204</var> users who are in the ADMIN SCLASS can use the
SoftSpy EDIT CONFIG command to change the name of the ACL associated with any of the commands listed above. When an end user attempts to use the command, the newly associated ACL will be checked. A null ACL name indicates that all end users may use the command.

ACLs are constructed and maintained using the EDIT ACL
command. Initially, the only users who can perform this function are those
that were entered during the installation process. The ADMIN ACL is
constructed during an initial installation with the same user identifiers that
are put into the SoftSpy Subsystem ADMIN SCLASS.
<h3>Customize SoftSpy Environments</h3>

The Rocket SoftSpy Reference Manual provides
instructions for customizing SoftSpy environments to meet local needs. You can
change the following environments:
<ul>
<li>
Base environment </li>
<li>Interactive Debug environment</li>
<li>Interactive Performance Tuning environment</li>
<li>Interactive Quality Assurance Testing environment</li>
</ul>

Each of these environments can be customized at two levels:
<ul><li>For all users of SoftSpy, or,</li>
<li>For individual users (by <var class="product">Model 204</var> User ID).</li>
</ul>

You can customize items such as PFKEY settings and data
display columns.

The <var class="book">Rocket SoftSpy Reference Manual</var> also
describes how to make SoftSpy skip over the interactive execution of selected
subsystems that are used as tools (such as SSTEST). You can customize SoftSpy to
skip over any number of selected subsystems.

Additionally, the <var class="book">Rocket SoftSpy Reference Manual</var>
provides a complete listing of the SoftSpy macros, which you can customize as
needed.

==System Manager Considerations==
SoftSpy uses background tasks called <var class="term">SoftSpy servers</var> that normally run in IODEV=55 threads to assist in program monitoring. When a User Language program is being executed under the control of SoftSpy, the program is
run in the user's normal server, and one of the server threads is used by SoftSpy to control and monitor the execution of the program. There must be one server thread for each simultaneous user of SoftSpy.

===SoftSpy and the MONITOR Command===

SoftSpy uses two wait type codes displayed by using the MONITOR command. The codes appear in the WT column that contains the wait type for a user.

The wait code values are: 
<table class="noBorder">
<tr>
<th>38</th> <td>Execution is suspended and the SoftSpy server is awaiting a request from a user.</td></tr>
<tr>
<th>39</th> <td>A user is suspended while a SoftSpy server is performing operations for the user.</td></tr>
</table>

Both of these wait type codes are swappable but not bumpable.

===SoftSpy files===

SoftSpy uses four different files. The usage of each file
is summarized below.

<table>
<tr><th>File</th> <th>Description</th></tr>
<tr>
<td>SPYPROC</td>
<td>This file contains procedures and help information used by SoftSpy. It is never updated, and it can be shared between several different online systems. If this file is corrupted it can be restored from the installation materials.</td>
</tr>
<tr>
<td>SPYDATA</td>
<td>This file contains various types of data that must be retained. This includes configuration information, Access Control Lists (ACLs) and copies of all SoftSpy macros. A base version of this file is created by the installation process, but the information in this file is modified when configuration, ACL, or macro changes are made. Periodic backups of this file should be made for recovery purposes. A separate instance of this file is required for each online system.</td>
</tr>
<tr>
<td>SPYTEMP</td>
<td>This file serves as a scratch pad for information during the execution of SoftSpy. Currently defined window descriptions, copies of macros being edited, and PF key settings are examples of the information saved in SPYTEMP. The CREATE.SPYTEMP procedure in SPYPROC can be used to recreate this file if necessary. A separate instance of this file is required for each online system.</td>
</tr>
<tr>
<td>ITSAUTH</td>
<td>This file contains authorization data. It is a simple sequential file containing 256 byte fixed length records. It is refreshed when the SoftSpy
configuration is saved using the SPY EDIT CONFIG command. If SoftSpy will be used in multiple online and batch systems, ITSAUTH should be shared among them.</td>
</tr>
</table>

==Additional Installations==
This section discusses the procedures to follow when you
have already installed the current version of SoftSpy and MUSE successfully,
and you wish to install them again in different ONLINE or BATCH204 jobs. These
procedures are designed to speed up the process for a system manager who is
very familiar with SoftSpy and MUSE installation and wants to save time. However,
it is never a problem to perform the entire installation process again.

===Install SoftSpy in additional ONLINE jobs===

If you are installing SoftSpy in additional ONLINEs under the same operating system and <var class="product">Model 204</var> release after an initial installation, you can use an abbreviated procedure.

The SPYPROC file is never updated and can be shared by multiple ONLINEs running SoftSpy. Therefore, you can omit the [[#Creating and restoring the SPYPROC file|Creating and restoring the SPYPROC file]] step on subsequent ONLINEs.

The DDs/DLBLs/ FILEDEFs for SPYPROC and ITSAUTH for each ONLINE can point to the same data set.

Each ONLINE must have its own SPYTEMP and SPYDATA files.

The INSTALL.SOFTSPY procedure must be run in each ONLINE to add the subsystem definition to CCASYS and to create and initialize SPYTEMP and SPYDATA.

===Install MUSE in additional ONLINE and BATCH204 jobs===

You might want to use MUSE in <var class="product">Model 204</var> ONLINE or
BATCH204 jobs in addition to the job where SoftSpy was initially installed.
For these additional job streams, add a DD/FILEDEF/DLBL for the previously
created ITSAUTH data set to the job stream.

==VSE JCL==
The following JCL files are used for SoftSpy installation on z/VSE systems:
<table class="noBorder">
<tr><th>SPYINST</th> <td>allocates SoftSpy system files</td></tr>
<tr><th>SPYRINST</th> <td>allocates SPYPROC and SPYDUMP files</td></tr>
</table>
In the JCL files below, the variable xxx has been substituted for the release number; for example:
// LIBDEF PROC,SEARCH=M204LIB.Vxxx
Replace <var class="term">xxx</var> with 750 or 740, as applicable; for example:
// LIBDEF PROC,SEARCH=M204LIB.V740
===SPYINST JCL===
// JOB SPYINST
* ********************************************************************
* Rocket Model 204
*
* ********************************************************************
/* SPYINST allocates SoftSpy system files.
/* Note that in the allocate step the DLBL and EXTENTs are
/* stated explicitly for each SoftSpy system file, while in
/* the create step the SoftSpy proc is used. The allocate
/* step cannot have the direct access (DA) code present on
/* the DLBL statements, and the create step (and the online
/* job) must have the (DA) code present.
/* *
/* Make sure that the explicit DLBL and EXTENT statements in
/* the allocate step match the proc in all aspects except
/* the DA codes.
/*
/* ***************************************************************
/* ***************************************************************
/*
/* Add assign statements as needed:
/* *
/* // ASSGN SYS000,X'CUU'
/*
/* The JCL as it is provided assumes you have made
/* standard assignments for the logical units (SYS000)
/* you reference in your EXTENT statements.
/* *
/* ***************************************************************
/* To adapt this stream to your particular installation the
/* following changes should be made:
/*
/* (1) Modify the job statement to conform to your standards.
/*
/* (2) Change the DLBL and EXTENT to reflect your dataset
/* names and locations as in other MODEL 204 jobs.
/* assign SYS008 to a printer for the audit trail, or
/* add DLBL and EXTENT statements for ccaaudit.
/*
/* ***************************************************************
/*
/* ***************************************************************
/* step alloc: MODEL204 allocate of all SoftSpy system files *
/* ************************************************************** *
/*
// EXEC PROC=M204JCL DLBL for JCL sublibrary
// LIBDEF PROC,SEARCH=M204LIB.<var class="term">xxx</var>
// EXEC PROC=M204V<var class="term">xxx</var> DLBL for V<var class="term">xxx</var> M204 library
// EXEC PROC=M204SYS DLBLS FOR CCASTAT, CCATEMP
// LIBDEF PHASE,SEARCH=M204LIB.V<var class="term">xxx</var>
// DLBL SPYPROC,'M204.SPYPROC',99/366,SD
// EXTENT SYS000,volser,,,0000,000 (AT LEAST 400 PAGES)
// DLBL SPYDATA,'M204.SPYDATA',99/366,SD
// EXTENT SYS000,volser,,,0000,000 (AT LEAST 150 PAGES)
// DLBL SPYTEMP,'M204.SPYTEMP',99/366,SD
// EXTENT SYS000,volser,,,0000,000 (AT LEAST 100 PAGES)
// DLBL ITSAUTH,'M204.ITSAUTH',99/366,SD
// EXTENT SYS000,volser,,,0000,000 (AT LEAST 7 PAGES)
// ASSGN SYS000,DISK,VOL=volser,SHR
// ASSGN SYS008,PRINTER
// EXEC ALLOCATE,SIZE=AUTO
ALLOCATE FILE(SPYPROC,SPYDATA,SPYTEMP,ITSAUTH)
/*
// EXEC PROC=M204JCL DLBL for JCL sublibrary
// LIBDEF PROC,SEARCH=M204LIB.V<var class="term">xxx</var>
// EXEC LIBR
ACCESS S=M204LIB.V<var class="term">xxx</var>
CATALOG SFTSPY.PROC REPLACE=YES
// DLBL SPYDUMP,'M204.SPYPROC.DUMP',,SD
// EXTENT SYS000,volser
// DLBL SPYPROC,'M204.SPYPROC',,DA
// EXTENT SYS000,volser
// DLBL SPYDATA,'M204.SPYDATA',,DA
// EXTENT SYS000,volser
// DLBL SPYTEMP,'M204.SPYTEMP',,DA
// EXTENT SYS000,volser
// DLBL ITSAUTH,'M204.ITSAUTH',,DA
// EXTENT SYS000,volser
/+
/*
/& 

===SPYRINST JCL===
// JOB SPYRINST
* ********************************************************************
* Rocket Model 204
*
* ********************************************************************
/* SPYRINST allocates SPYPROC and SPYDUMP files.
/* *
/* Note that in the allocate step the DLBL and EXTENTs are
/* stated explicitly for each SoftSpy system file, while in
/* the create step the SoftSpy proc is used. The allocate
/* step cannot have the direct access (DA) code present on
/* the DLBL statements, and the create step (and the online
/* job) must have the (DA) code present.
/*
/* Make sure that the explicit DLBL and EXTENT statements in
/* the allocate step match the proc in all aspects except
/* the DA codes.
/*
/* ***************************************************************
/* ***************************************************************
/* *
/* Add assign statements as needed:
/*
/* // ASSGN SYS000,X'CUU'
/*
/* The jcl as it is provided assumes you have made
/* standard assignments for the logical units (SYS000)
/* you reference in your EXTENT statements.
/*
/* ***************************************************************
/* To adapt this stream to your particular installation the
/* following changes should be made:
/*
/* (1) Modify the job statement to conform to your standards.
/*
/* (2) Change the DLBL and EXTENT to reflect your dataset
/* names and locations as in other MODEL 204 jobs.
/* Assign SYS008 to a printer for the audit trail, or
/* add DLBL and EXTENT statements for ccaaudit.
/*
/* ***************************************************************
/*
/* ***************************************************************
/* step alloc: MODEL204 allocate of all SoftSpy system files
/* ***************************************************************
/*
// EXEC PROC=M204JCL DLBL for JCL sublibrary
// LIBDEF PROC,SEARCH=M204LIB.V<var class="term">xxx</var>
// EXEC PROC=M204V<var class="term">xxx</var> DLBL for V<var class="term">xxx</var> M204 library
// EXEC PROC=M204SYS DLBLS FOR CCASTAT, CCATEMP
// LIBDEF PHASE,SEARCH=M204LIB.V<var class="term">xxx</var>
// DLBL SPYPROC,'M204.SPYPROC',exp date,SD
// EXTENT SYS000,volser,,,0000,000 (AT LEAST 400 PAGES)
// ASSGN SYS008,PRINTER
// EXEC ALLOCATE,SIZE=AUTO
ALLOCATE FILE(SPYPROC)
/*
// EXEC PROC=M204JCL DLBL for JCL sublibrary
// LIBDEF PROC,SEARCH=M204LIB.V<var class="term">xxx</var>
// EXEC LIBR
ACCESS S=M204LIB.V<var class="term">xxx</var>
CATALOG SFTSPY.PROC REPLACE=YES
// DLBL SPYDUMP,'M204.SPYPROC.DUMP',,SD
// EXTENT SYS000,volser
// DLBL SPYPROC,'M204.SPYPROC',,DA
// EXTENT SYS000,volser
// DLBL SPYDATA,'M204.SPYDATA',,DA
// EXTENT SYS000,volser
// DLBL SPYTEMP,'M204.SPYTEMP',,DA
// EXTENT SYS000,volser
// DLBL ITSAUTH,'M204.ITSAUTH',,DA
// EXTENT SYS000,volser
/+
/*
/&


[[Category:SoftSpy]]
[[Category:Installation]]

Upgrading to Model 204 version 7.5 on IBM z/OS

2016-04-04T13:27:15Z

Mlarocca: /* Requirements */

<div class="toclimit-3">__TOC__</div>
==Overview==
This page describes the steps required to upgrade from Rocket Model 204 version 7.4 to version 7.5, on the IBM® z/OS® operating system.

For information on the new features available in version 7.5, see the [[Release notes for Model 204 version 7.5|7.5 Release notes]].

<table><tr><td>In order to upgrade to Model 204 version 7.5, you must have version 7.4 and [[#Before you begin|various Early Warnings]] installed on your system.. </td></tr></table>

To upgrade to version 7.5 simply download, upload, and link the 7.5 object modules available from the downloads page to install the 7.5 components.

==Before you begin==
<ul>
<li>In order to upgrade to version 7.5, you must have version 7.4 and Early Warnings for Dictionary/204 through 740DI016 installed on your system.
Note: If you plan to use v7.4 CRAM with your v7.5 installation, you will need to apply all 7.4 maintenance. See [[#CRAM|CRAM]] for details.</li>
For information on Early Warnings, log in to the [http://www.rocketsoftware.com/support Rocket Customer Portal].</li>
<li>For system requirements for version 7.5, see the [[Release notes for Model 204 version 7.5#Operating system requirements|7.5 Release notes]].</li>
<li>You must have either a [[Rocket M204 user ID]] or a Sirius user ID to download the installation files.</li>
<li>The object library has the authorization zap (covering your licensed processors) preapplied, so you do not need to get a new authorization zap from the website. (The preapplied zap will authorize Model 204 itself and any separately purchased products such as SirScan.)</li>
<li>The object library also has the maintenance zaps (as of the time the stream was
prepared) preapplied, so you do not need to apply any maintenance as part of this installation. (You will only need to apply any new maintenance when it becomes available for this release.)</li>
</ul>
<div id="steps"></div>

==Overview of upgrading steps==

Review the following high-level summary of steps before you begin downloading the <var class="product">Model 204</var> version 7.5 files.

For an example, see [[#Example_workflow_for_7.5:_download_through_installation|Example workflow for 7.5: download through installation]].

<ol>
<li>Use your [[Rocket M204 user ID]] to [[#downloading|download]] the Model 204 object library and the Model 204 macro library.</li>

<li>[[#uploading|Upload]] the downloaded components to the z/OS system on the IBM mainframe.</li>

<li>[[#bldLibs|Build]] the RKOBJLIB object library and RKMACLIB macro library. (Once you have built these libraries, do not modify them.)</li>

<li>Submit the job to [[#allocating|allocate the other data sets]] required for installation.</li>

<li>If you have your own user $functions (FUNU), you must do the following steps:
<ol style="list-style-type:lower-alpha;">
<li>[[#FUNU_7.5|Modify FUNU for 64-bit addressing]] considerations and store the modified source in your local source library.</li>
<li>If you have any user-defined messages (MSGU), store them in your local source library.</li>
<li>[[#asmFUNU|Assemble]] FUNU (and MSGU, if applicable), with the output object file stored in your local object library.</li>
</ol>
</li>

<li>If you use an external authorizer (such as RACF) for <var class="product">Model 204</var>, [[#secparm|assemble the xxxxPARM security module]] (such as RACFPARM). The object file is then stored in your local object library.</li>

<li>If you use the [[#ul_db2|UL/DB2 interface]], preprocess and assemble the USQL module.</li>

<li>If you use other customized modules, such as CDTB, modify them as needed and [[#asm|assemble]] them.</li>

<li>Link the [[#lkonln|ONLINE]] load module.</li>

<li>If you use the [[#link_ifam1|IFAM1]] and [[#link_ifam4|IFAM4]] load modules, link them.</li>

<li>Link the <var class="product">Model 204</var> [[#lkutils|utility load modules]].</li>

<li>If you use the [[#cics|CICS interface]], customize it, and then assemble and link the CICS modules.</li>

<li>If you use the [[#tso|TSO]] interface, assemble and link-edit the TSO source modules.</li>

<li>If you use [[#softspy|SoftSpy]], upgrade it for 7.5.</li>
</ol>

==Object and macro libraries==
{{Template:Model 204 installation components}}

==Building the object and macro libraries==
To build the object and macro libraries, you must download the object library and macro library; upload each library to the mainframe; and copy, modify, and run the NEW204LB job.
<div id="downloading"></div>
===Downloading===

<ol>
<li>Using your [[Rocket M204 user ID]] and password, log in to the [https://model204.rocketsoftware.com/maint/objlist Model 204 object file download page].</li>
<li>Click the Download object file link beside the object library that you want to download.</li>
<li>Go to the [https://model204.rocketsoftware.com/maint/maclist Model 204 macro library download page].</li>
<li>Click the Download macro library link beside the macro library that you want to download.</li>
</ol>

<div id="uploading"></div>

===Uploading===

Once the object file and macro library are downloaded to your workstation, upload them to the z/OS system on the IBM mainframe. You can use any file transfer mechanism, including FTP and IND$FILE.

Specify these characteristics for the upload files:

<table class="noBorder">
<tr><td>transfer format:</td> <td>binary</td></tr>
<tr><td>record format:</td> <td>FB</td></tr>
<tr><td>record size:</td> <td>80 for object and macro libraries</td></tr>
<tr><td>block size:</td> <td>6400 for object and macro libraries</td></tr>
<tr><td>storage size for both:</td> <td>primary: 10 CYL; secondary: 5 CYL</td></tr>
</table>

For details on how to download and upload, see [[Downloading and uploading Model 204 installation components]].
<div id="bldLibs"></div>

===Building the object and macro libraries (NEW204LB job stream)===


After you upload the object and macro library input streams to the mainframe, build the object and macro libraries:

<ol>
<li>Access the [http://sirius.sirius-software.com/download/new204lb.txt NEW204LB job stream] text file.

<li>Copy the job stream file into a local TSO library for editing.

<li>On the first line of the job stream, modify the JOB card according to your local job card parameters.

<li>On the final four lines, marked <code>2 <<</code> ... <code>5 <<</code> on the right:
<ol style="list-style-type:lower-alpha;">
<li>Modify the <code>VERSION=</code> parameter, specifying the two-digit version of <var class="product">Model 204</var> you are installing, such as 75.
<li>Modify the <code>HLQ=</code> parameter, specifying the high-level qualifiers of all <var class="product">Model 204</var> installation data sets.
<li>Modify the <code>OBJINP=</code> parameter, using the DSN of the object library input file that you uploaded to the mainframe.
<li>Modify the <code>MACINP=</code> parameter, using the DSN of the macro library input file that you uploaded to the mainframe.
</ol>
<li>Submit the <code>NEW204LB</code> job to build the object library ("RKOBJLIB") and macro library ("RKMACLIB") on your z/OS system.</li>
</ol>

<div id="notouch"></div>
Attention: Once you have built RKOBJLIB and RKMACLIB on your z/OS system, do not modify them in any way. 

For example, do not store other members into the object library; it should only contain the members as supplied in a download from the web site. Place object files that you might assemble (such as FUNU or RACFPARM) into your local object library.

====RKOBJLIB README file====
README, a member of RKOBJLIB, contains details on the object files and installation steps. Once you have built RKOBJLIB, you can use README as an installation checklist if desired.

<div id="allocating"></div>

==Data sets for Model 204 upgrading==

There are three data sets used when upgrading to Model 204 7.5:

<ul>
<li>data set for the Model 204 load modules
<li>data set for the local source library
<li>data set for the local object library
</ul>
The data set for the load modules will contain, after linking, the modules for the Model 204 product, including: ONLINE, IFAM1, and IFAM4.

The local source library is used to store the customized source for modules such as FUNU, MSGU, and ACF2PARM, RACFPARM, or TOPSPARM.

When the source is assembled, it is stored in the local object library.

One of the members of the RKOBJLIB object library is named [[Model 204 data set allocation job stream for IBM z/OS|JALINSJ]], which is a job stream to allocate data sets for the installation. <code>JALINSJ</code> contains information about naming conventions for the data sets.

===Allocating data sets (JALINSJ job stream)===

<ol>
<li>Copy <code>JALINSJ</code> into a local TSO library.
<li>Edit your copy of <code>JALINSJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>JALINSJ</code> job to allocate the data set.
</ol>

<div id="lkonln"></div>

==Linking the Model 204 ONLINE load module==


<div id="onlnTable"></div>
<blockquote class="note">
Notes: 
<ul>
<li>If you use customized modules (such as FUNU, MSGU, ACF2PARM, RACFPARM, TOPSPARM, CDTB, or UL/DB2), you must [[#FUNU_7.5|modify]] them (if needed) and [[#asm|assemble]] them before you link the ONLINE/IFAM1/IFAM4 load modules.</li>
<li>There is not a separate link step for BATCH204. It is not maintained as a separate module; the same module as ONLINE is used, with a BATCH204 alias.</li>
<li>The INCLUDE TCPLIB(SNMPGSYS) statement for Horizon TCP/IP in the Online-link-edit job is no longer required and has been eliminated.</li>
<li>A number of INLUDE LELIB(CEE*) statements have also been eliminated from the Online-link-edit job. These were required to support several mathematical $functions but those $functions have been rewritten in Assembly language and are now automatically part of the Online load module.</li>
<li> The INCLUDE IBMLIB(IEFSD095) statement is still required if block printing on separator pages is desired. Usually the IBMLIB DD points to DSN=SYS1.AOSB0</li>
</ul>
</blockquote>

One of the members of the RKOBJLIB object library is [[Model 204 ONLINE link job stream for z/OS|LKONLNJ]], which is a job stream to link the <var class="product">Model 204</var> ONLINE load module.

<div id="LKONLNJ"></div>
===Linking ONLINE (LKONLNJ job stream)===


<ol>
<li>Copy the <code>LKONLNJ</code> job stream from RKOBJLIB into a local TSO library.
<li>Edit your copy of <code>LKONLNJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with 1-4 followed by <code><<</code>. The numbers correspond to numbered steps in the comments.
<li>As needed, edit the lines after <code>SYSLIN DD *</code> that are marked with <code><<</code>. See the comments at the top of the <code>SYSLIN</code> sections (A-C) for instructions.
</ul>
<li>Submit the <code>LKONLNJ</code> job to link the ONLINE load module.
</ol>

Concise editing instructions are provided in the <code>LKONLNJ</code> file itself. More details about link-editing the ONLINE load module are provided in the following table.

<table class="thJustBold">
<tr><th>1</th><td>You must specify a value for the HLQ symbolic parameter in the EXEC LKM204P statement. The value of HLQ corresponds to the high-level qualifier used for the DSN for:
<ul>
<li> the downloaded object library</li>
<li>the Model204 load library</li>
<li>other data sets that are required for installation</li>
</ul></td></tr>
<tr><th>2</th><td>One of the modifications is always required, based on whether the ONLINE is to use RSQL (for Connect*) or not.

Uncomment only one of the following statements:
<ul>
<li>To link an ONLINE that uses RSQL, you must uncomment the INCLUDE RKOBJ204(LKSQLONL) statement.
<li>To link an ONLINE that does not use RSQL, you must uncomment the INCLUDE RKOBJ204(LKNOSONL) statement.
</ul>
</td></tr>
<tr><th>3</th><td>If you use an external authorizer, such as RACF or ACF2, you must:
<ul>
<li>[[#asm|Assemble the xxxPARM]] for your external authorizer to add the object file (such as RACFPARM or ACF2PARM) to your local object library.
<li>In the SYSLIN DD *, uncomment the appropriate INCLUDE statement(s) for your external authorizer. <blockquote class="note">Notes:
<ul><li>Uncomment either the "static" or "dynamic" INCLUDE statement, depending on your configuration.<li>If you use ACF2, there are two INCLUDE statements to be uncommented; one refers to your system ACF2 library. You must also provide the DSN for the ACF2 library in the ACF2 symbolic parameter in the EXEC LKM204P statement.</ul>
</blockquote>
</ul>
</td></tr>

<tr><th>4</th><td>If you have other programs that you assemble for your Model 204 ONLINE module, for example, [[#FUNU|FUNU]], assemble them into your local object library. You do not need to add additional INCLUDE statements for FUNU or other locally assembled object files; they are already in the include streams from RKOBJLIB.
</td></tr>

<tr><th>5</th><td>If you have an MQ series load library, set the MQ symbolic parameter to the correct DSN in the EXEC LKM204P statement. This allows you to use the MQ Series feature of <var class="product">Model 204</var>, either if you are already authorized for it, or to support a trial of it, without requiring relinking of the load module. You must also uncomment the INCLUDE MQ statement in the SYSLIN input.
</td></tr>

</table>

<div id="link_ifam1"></div>

==Linking the Model 204 IFAM1 load module==


One of the members of the RKOBJLIB object library is [http://m204wiki.rocketsoftware.com/index.php/Model_204_IFAM1_link_job_stream_for_IBM_z/OS?title=Model_204_IFAM1_link_job_stream_for_IBM_z/OS&target=blank LKIFAM1J], which is a job stream to link the <var class="product">Model 204</var> IFAM1 load module.

===Linking IFAM1 (LKIFAM1J job stream)===
<ol>
<li>Copy the <code>LKIFAM1J</code> job stream from RKOBJLIB into a local TSO library.
<li>Edit your copy of <code>LKIFAM1J</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>LKIFAM1J</code> job to link the IFAM1 load module.
</ol>

<div id="link_ifam4"></div>

==Linking the Model 204 IFAM4 load module==


One of the members of the RKOBJLIB object library is [http://m204wiki.rocketsoftware.com/index.php/Model_204_IFAM4_link_job_stream_for_IBM_z/OS?title=Model_204_IFAM4_link_job_stream_for_IBM_z/OS&target=blank LKIFAM4J], which is a job stream to link the <var class="product">Model 204</var> IFAM4 load module.

===Linking IFAM4 (LKIFAM4J job stream)===

<ol>
<li>Copy the <code>LKIFAM4J</code> job stream from RKOBJLIB into a local TSO library.
<li>Edit your copy of <code>LKIFAM4J</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>LKIFAM4J</code> job to link the IFAM4 load module.
</ol>

<div id="lkutils"></div>


==Linking the Model 204 utility load modules==


Most of the utility load modules from Model 204 version 7.4 will continue to perform correctly when used with version 7.5.

However, you must use the 7.5 version of the following utilities, which are sensitive to the Model 204 journal and checkpoint format:
<table>
<tr><td>AUDIT204</td> <td>Extract from journal, with report stats and analysis</td></tr>
<tr><td>MERGEJ</td> <td>Merge concurrent journal streams</td></tr>
<tr><td>UTILC</td> <td>Information from checkpoint stream</td></tr>
<tr><td>UTILJ</td> <td>Information from journal stream; add EOF markers</td></tr>
</table>

===Linking the utility load modules (LKALLUTJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 utilities link job stream for IBM z/OS|LKALLUTJ]], a job stream to link the <var class="product">Model 204</var> utility load modules.
<ol>
<li>Copy <code>LKALLUTJ</code> into a local TSO library.
<li>Edit your copy of <code>LKALLUTJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the line after <code>EXEC LKALLUTP</code> at the bottom of the job stream
</ul>
</ul>
<li>Submit the <code>LKALLUTJ</code> job to link the utility load modules.
</ol>

<div id="asm"></div>
==Assembling customized modules into your local object library (LOCAL.OBJLIB)==

Copy the customized source module (such as, FUNU, MSGU, ACF2PARM, RACFPARM, TOPSPARM, CDTB, or UL/DB2) from your current release into your local source library, if you have not already done so.
The local source library is not version-specific, so modules copied into it can be used for future installations.

One of the members of the RKOBJLIB object library is [[Model 204 local member assembly job stream for IBM z/OS|JASMJ]], a job stream to assemble a member from your Model 204 local source library into your local object library (LOCAL.OBJLIB).

===Assembling customized modules (JASMJ job stream)===
<ol>
<li>Copy <code>JASMJ</code> into a local TSO library.
<li>Edit your copy of <code>JASMJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the ASM line at the bottom of the job stream
</ul>
<li>Provide the member name to assemble (such as FUNU, MSGU, RACFPARM) on the <code>MEM=</code> line.
</ul>
<li>Submit the <code>JASMJ</code> job to assemble the module into your local object library.
</ol>

<div id="lkcram"></div>
<div id="secparm"></div>

==Setting up the security module==

This section assumes that if you are using a [[Security interfaces overview|security interface]] such as CA-ACF2, RACF, or CA-Top Secret, you have already installed it with Model 204 version 7.4.

You will use the xxxxPARM provided with Model 204 release v7.4.

<ol>
<li>Review the Model 204 7.4 installation section for your interface to ensure that you have completed all of the steps:
<ul>
<li>[[CA-ACF2_MVS_interface#Installing_the_Model_204_CA-ACF2_MVS_Interface|CA-ACF2 (MVS)]]</li>
<li>[[CA-ACF2_VM_interface#Installing_the_CA-ACF2_VM_Interface|CA-ACF2 (VM)]]</li>
<li>[[Security_Server_(formerly_RACF)_interface#Installing_the_Security_Server_Interface|RACF]]</li>
<li>[[CA-Top_Secret_interface#Installing_the_CA-Top_Secret_Interface|CA-Top Secret]]</li>
</ul>
</li>
<li> [[#asm|Assemble]] the security module:
ACF2PARM, RACFPARM, or TOPSPARM.</li>
<li>Optional. Link the security module as described below if you want it to be dynamically loaded.</li>
</ol>

===Linking the security module (LKSECRJ job stream)===

Dynamic loading lets you modify the security parameters without having to relink Model 204, which would be required if the parameter module were linked into Model 204 directly.

If you want Model 204 to dynamically load your security module during Model 204 ACF2, RACF, or TOPSECRET interface initialization, then you must link the corresponding security parameter module.

One of the members of the RKOBJLIB object library is <code>LKSECRJ</code>, a job stream to link-edit the security parameter module.

<ol>
<li>Copy [[Model 204 security module link job stream for IBM z/OS|LKSECRJ]] into a local TSO library.
<li>Edit your copy of <code>LKSECRJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>LKSECRJ</code> job to link-edit the security parameter module (ACF2PARM, RACFPARM, or TOPSPARM).
</ol>
<div id="cics"></div>

==CICS interface installation==

The Model 204 CICS interface allows CICS complete access to Model 204 facilities and supports CICS pseudo conversational programs.
Note: It is not necessary to install the CICS interface if it has been installed for a previous version of Model 204. The load modules from the older version are compatible with version 7.5 of Model 204.

===Requirements===
<ul>
<li>CICS Transaction Server support
Rocket M204 supports the CICS Transaction Server versions 4.1, 4.2 and 5.3.</li>
<li>Supporting TPROCESS COBOL applications
If your CICS TPROCESS application was originally linked with AMODE=24, you must relink the CICS TPROCESS application specifying AMODE=31 because AMODE=24 is not supported.</li>
</ul>

===CICS interface overview===
For an overview of the CICS interface, including storage requirements and a listing of CICS interface components, see [[CICS interface]].

===Installing the CICS interface===

<ol>
<li>Customize the interface by copying the CICFG copy member from RKMACLIB into your local source library and editing it as needed.
For information on customizations needed for using the CICS Standard Mapping Service, see [[CICS interface]].</li>
<li>Update the CICS System Definition (CSD) using one of the following methods:
<ul><li>Resource Definition Online (CEDA). The supplied member CEDAM204 in RKMACLIB provides an example of the required PCT, PPT, and PLT definitions.</li>
<li>The IBM DFHSCDUP offline utility, to process the definitions in batch.</li>
</ul>
<li>[[#CICS_alloc|Allocate]] a CICS user library.</li>
<li>[[#CICS_asm|Assemble and link]] the CICS modules.</li>
</ol>

===Updating the CICS System Definition (CSD)===
You can update the CSD by using either CEDA or the DFHCSDUP utility and the CEDAM204 member of RKMACLIB. Use the values in the following table, where appropriate, for the method you choose. Information about
using CEDA follows the table.

CICS System Definition values
<table>
<tr class="head"><th>User program</th> <th>Program name</th> <th>Transaction ID</th> <th>Modifiable CICFG symbol</th>
<th>TWA size</th></tr>
<tr><td>IFAM2 pseudo conversational</td> <td>DFHPSF</td> <td>DFHPSF is accessed by using a CICS LINK. It is never
invoked with a transaction ID from a terminal.</td> <td /> <td /><tr>
<tr><td>Full-screen interface</td> <td>M204PSFS</td> <td>M204</td> <td>&TRN</td> <td>88</td></tr>
<tr><td>Screen copy transaction</td> <td>M204CRPS</td> <td>U204</td> <td /> <td /></tr>
<tr><td>Screen print transaction</td> <td>M204PRNT</td> <td>P204</td> <td>&COP</td> <td>88</td></tr>
</table>
CEDA (the Resource Definition Online transaction) or the DFHCSDUP utility defines the transactions and programs to the CSD file.

If you are not using the CEDAM204 member, then define the transactions and programs by using CEDA
and the values in the previous table, as in the following example:
CEDA DEFine PROG(program_name)
GRoup(group_name)
LANGuage(ASSEMBLER)
RELoad(NO)
RESident(NO) (Except for DFHPSF, RESident(YES))
RSL(PUBLIC)
STatus(ENABLED)

CEDA DEFine TRANsaction(trans_ID)
GRoup(group_name)
PROgram(program_name)
TWASIZE(twa_size_value)
.
.
.
RSL(PUBLIC)
.
.
.

CEDA CHeck GRoup(group_name) 

You can use a transaction ID for a user program that is different from the value
shown in the previous table. However, if you do so, you must change the associated
CICFG symbol shown in the table.

As shown in the preceding example, group_name is any valid group name for the
user site.

 Note: Remember to add the groups to the GRPLIST for the particular CICS
region. If the groups are not added, they are not installed during each CICS initialization.

<div id="CICS_alloc"></div>

===Allocating a CICS user library (JALCICSJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 CICS user library allocation job stream for IBM z/OS|JALCICSJ]], a job stream to allocate an empty CICS user library. You must allocate the CICS user library before assembling and linking the CICS modules.
<ol>
<li>Copy <code>JALCICSJ</code> into a local TSO library.</li>
<li>Edit your copy of <code>JACICSJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.</li>
<li>Supply your installation high level qualifier(s) in the following lines marked with <<:
<ul>
<li>for hlq in the JCLLIB ORDER=(hlq.... line after the JOB card </li>
<li>after HLQ=, on the line after EXEC LKALLUTP at the bottom of the job stream </li>
</ul>
</ul>
</li>
<li>Submit the <code>JALCICSJ</code> job to allocate the CICS user library.</li>
</ol>

<div id="CICS_asm"></div>
===Assembling and linking CICS modules (LKCICSJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 CICS module assembly job stream for_ IBM z/OS|LKCICSJ]], a job stream to assemble and link the <var class="product">Model 204</var> CICS modules.
<ol>
<li>Copy <code>LKCICSJ</code> into a local TSO library.
<li>Edit your copy of <code>LKCICSJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your Model 204 installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the line after <code>EXEC JALCICSP</code> at the bottom of the job stream
</ul>
</ul>
<li>Submit the <code>LKCICSJ</code> job to assemble and link the CICS module.
</ol>

<div id="tso"></div>

==TSO interface installation==

Note: It is not necessary to install the TSO interface if it has been installed for a previous version of Model 204. The load modules from the older version are compatible with version 7.5 of Model 204.

The Model 204 TSO Interface enables the TSO user to communicate with a Model 204 Online.

The TSO Interface consists of two assembly language modules, TSFS and TSUL, whose source is located in the macro library. The modules are completely reentrant, reusable, and refreshable. Installation requires assembly and link-editing of the TSO source modules.

===Installing the TSO interface===

<ol>
<li>If you are using TSO extensions, modify TSFS in the local source library by changing:
&TSOV SETC 'TSO' 
to:
&TSOV SETC 'TSOE'</li>
Changing the &TSOV SETC 'TSO' code in TSFS causes assembly of the NOEDIT form of the TPUT macro in the TSFS module. The NOEDIT form, required for 3270 extended data streams, allows proper handling of colors or highlighting in TSO extensions. NOEDIT is recommended for all TSO extensions.
<li>Assemble and link the TSO modules, using the <code>LKTSOJ</code> job.</li>
</ol>

===Assembling TSO modules (LKTSOJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 TSO module assembly job stream for IBM z/OS|LKTSOJ]], a job stream to assemble and link the <var class="product">Model 204</var> TSO modules.
<ol>
<li>Copy <code>LKTSOJ</code> into a local TSO library.
<li>Edit your copy of <code>LKTSOJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the line after <code>EXEC LKALLUTP</code> at the bottom of the job stream
</ul>
</ul>
<li>Submit the <code>LKTSOJ</code> job to assemble and link the TSO modules.
</ol>
<div id="FUNU"></div>

==CRAM==
RKOBJLIB also contains LKCRAMJ, the job stream to link the CRAM load modules.

Versions 7.4 and later of the CRAM load modules are completely compatible with version 7.5 of Model 204. Deploying a new version of CRAM can be an intensive process, and because you have version 7.4 installed, it is not necessary. You can safely bypass linking the 7.5 CRAM modules. However, if you do not link the 7.5 CRAM modules, you will need to apply additional 7.4 maintenance.

Your CRAM installation options are:
<ul>
<li>Install 7.5 XDM by running LKCRAMJ to link the 7.5 CRAM modules.</li>
<li>
Install 7.4 XDM and then apply Early Warnings for Model 204. (You can do this by applying Autofix release EW3044, which includes these Early Warnings as well as Early Warnings for Dictionary/204 through 740DI016.)

Sharing 7.1 XDM requires maintenance through 710EW172.
</li>
</ul>

==FUNU and optional MSGU==


This section lists installation considerations if you have your own user-written $functions module (FUNU).

Note: If you have your own FUNU or MSGU module, you must assemble it before linking the ONLINE/IFAM1/IFAM4 load modules.

<div id="FUNU_7.5"></div>
===FUNU changes for version 7.5===


{{Template:FUNU changes for 7.5}}

<div id="asmFUNU"></div>

===FUNU (and MSGU) assembly===


Copy the source from RKMACLIB into your local source library.

After making any changes required for this version of <var class="product">Model 204</var>, run <code>JASMJ</code> to [[#asm|assemble]] FUNU into your local object library.

If needed, modify and run <code>JASMJ</code> to assemble MSGU.

You do not need to insert any INCLUDE statements for either FUNU nor MSGU; they are already present in the INCLUDE member (LKSQLONL or LKNOSONL) provided in the downloaded object library.

<div id="ul_db2"></div>

==Installing the UL/DB2 interface (JAUSQLJ job stream)==

To support the UL/DB2 interface, USQL code is delivered in source for you to preprocess for your version of DB2. If you use the UL/DB2 interface, assemble the source as described below before linking the ONLINE/IFAM1/IFAM4 load modules.

<ol>
<li>Copy [[Model 204 UL/DB2 job stream for IBM z/OS|JAUSQLJ]] into a local TSO library.
<li>Edit your copy of <code>JAUSQLJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>on the line after <code>EXEC JAUSQLP</code> at the bottom of the job stream set:
<ul>
<li><code>HLQ=</code>high level qualifier of all Model 204 installation DSNs</li>
<li><code>DB2HLQ=</code>high level qualifier for your DB2 maclib.</li>
</ul>
</ul>
</ul>
<li>Submit the <code>JAUSQLJ</code> job to preprocess and assemble the USQL module. The JAUSQLJ job executes the following two steps:
<ul>
<li>Run USQL (contained in RKMACLIB) through the DB2 preprocessor to process the EXEC SQL statements. This step produces two data sets: the DBRM and the expanded USQL source. The DBRM is saved as USQLDBRM in the local object library. The expanded USQL source is passed to step two for assembly.</li>
<li>Assemble expanded USQL source into local object library.</li>
</ul>
<li>Bind the DBRM as the plan with a site-specific plan name.</li>
</ol>
For more information on UL/DB2, see the <var class="book">Rocket Model 204 User Language/DATABASE 2 Interface Guide</var>.

<div id="softspy"></div>

==Upgrading SoftSpy for 7.5==

To upgrade SoftSpy for version 7.5, download, upload, and restore the SoftSpy procedure file, SPYPROC, which is distributed in a dump format.

<ol>
<li>Download SPYPROC, in binary form, from the [https://m204.rocketsoftware.com/maint/ullist?nickname=ROCKET SOUL files download page] to a workstation file.</li>
<li>Upload the file from your workstation to your z/OS system.</li>
<li>RESTORE the file into a Model 204 SOUL file.</li>
</ol>
For detailed instructions, see [http://m204wiki.rocketsoftware.com/index.php?title=Web_help_download_SOUL_files#How_can_the_dump_file_be_uploaded_to_the_mainframe.3F Downloading and restoring SOUL files].

==Verifying Model 204 7.5 on your system==
To perform an initial verification that your upgrade to 7.5 was successful, issue the following commands from the Model 204 command line.
<table>
<tr class="head"><th>Command</th> <th>You should see...</th></tr>
<tr><td>ROCKET</td> <td>A list of authorized M204 products (including 7.5) currently on your system.</td></tr>
<tr><td>DISPLAY ZAPS</td> <td>A list of Model 204 zaps (including 7.5 zaps) on your system.</td></tr>
<tr><td>DICTADMIN</td> <td>The Dictionary Administration subsystem, displaying <code>Release 7.5</code> on its menu screens.</td></tr>
<tr><td>SUBSYSMGMT</td> <td>The Application Subsystem facility, displaying <code>VER 7 REL 5</code> on its menu screens.</td></tr>
</table>

==Example workflow for 7.5: download through installation==
This example shows one typical installation workflow: the site does not use RSQL, it uses the RACF external authorizer, and it does not have its own FUNU. The IBM system MQ loadlib is <code>MQSERIES.SCSQLOAD</code> (this is typical in z/OS).
The high-level qualifier in this example is MYBUILD.

The other item needed is the member name <code>MYBLDOB</code>, which is chosen arbitrarily for this example, and the following DSNs:
<ul>
<li><code>MYBUILD.M204V75.RKOBJLIB.DISTRIB</code>
<li><code>MYBUILD.M204V75.RKOBJLIB</code>
<li><code>MYBUILD.M204V75.RKMACLIB.DISTRIB</code>
<li><code>MYBUILD.M204V75.RKMACLIB</code>
<li><code>MYBUILD.M204V75.LOCAL.OBJLIB</code>
<li><code>MYBUILD.M204V75.LOADLIB</code>
</ul>
===Build RKOBJLIB===
<ol>

<li>Download the object library (M204V75.OBJ) from the downloads page.

<li>Upload to the mainframe, in binary format, with settings FB/80/6400, as <code>MYBUILD.M204V75.RKOBJLIB.DISTRIB</code>.

<li>Download the macro library (M204V75_ZOS.MAC) from the downloads page.

<li>Upload to the mainframe, in binary format, with settings FB/80/6400, as <code>MYBUILD.M204V75.RKMACLIB.DISTRIB</code>.

<li>Create the member MYBLDOB in my TSO library from a [http://sirius-software.com/download/new204lb.txt download] of the job stream to build the object and macro libraries, using the following at the end of the job stream:
//BLD EXEC NEW204LB,VERSION=75,
// HLQ=MYBUILD,
// OBJINP=MYBUILD.M204V75.RKOBJLIB.DISTRIB,
// MACINP=MYBUILD.M204V75.RKMACLIB.DISTRIB


<li>Run MYBLDOB from my TSO library. MYBLDOB deletes and then creates <code>MYBUILD.M204V75.RKOBJLIB</code> and
<code>MYBUILD.M204V75.RKMACLIB</code>.

<li>Upload to the mainframe, in binary format, with settings FB/80/6400, as <code>MYBUILD.M204V75.RKMACLIB.DISTRIB</code>.

<li>Create the member MYBLDDS in my TSO library by copying
the job stream from [[Model 204 data set allocation job stream for IBM z/OS|JALINSJ]], using the following at the end of the job stream:
//BLD EXEC JALINSP,
// HLQ=MYBUILD


<li>Run MYBLDDS from my TSO library. MYBLDDS allocates an empty loadlib data set for the Model 204 load modules, an empty local source library for the customized source files, and an empty local object library for the customized local object modules, with the following names: <code>MYBUILD.M204V75.LOADLIB</code>, <code>MYBUILD.M204.LOCAL.SRCLIB</code> and <code>MYBUILD.M204V75.LOCAL.OBJLIB</code>.

</ol>

===Assemble and link===
<ol >
<li>Copy the RACFPARM source to the <code>MYBUILD.M204.LOCAL.SRCLIB</code> and make any necessary modifications.
<li>Create the member JASMSECJ in my TSO library by copying
the job stream from [[Model 204 local member assembly job stream for IBM z/OS|JASMJ]], using the following at the end of the job stream:
//ASM EXEC JASMP,HLQ=MYBUILD,
// MEM=RACFPARM


<li>Run JASMSECJ from my TSO library; this assembles the RACFPARM source file in the <code>MYBUILD.M204.LOCAL.SRCLIB</code> and stores the object in <code>MYBUILD.M204V75.LOCAL.OBJLIB</code>.

<li>Copy the member LKONLNJ from <code>MYBUILD.M204V75.RKOBJLIB</code> to my TSO library, and customize LKONLN as follows:
<ul>
<li>Make these changes at the top of the job stream:
// JCLLIB ORDER=(MYBUILD.M204V75.RKOBJLIB)
//LKONLN EXEC LKM204P,
// HLQ=MYBUILD,
// MQ=MQSERIES.SCSQLOAD

<li>Uncomment the <code>INCLUDE</code> line for LKNOSONL (that is, without RSQL).
<li>Uncomment the <code>INCLUDE</code> line for MQ.
<li>Uncomment the <code>INCLUDE</code> line for my external authorizer module (such as RACFOS and RACFPARM).
<li>Submit the LKONLNJ job from my TSO library, this creates ONLINE (and BATCH204 alias) in MYBUILD.M204V75.LOADLIB.
</ul>

<li>Perform a simple smoke test: run BATCH204 with 'DISPLAY ZAPS' and 'ROCKET' commands.

<li>To link the utilities, copy member LKALLUTJ from <code>MYBUILD.M204V75.RKOBJLIB</code> to my TSO library, and see all <code><<</code> lines to customize for my site; submit the LKALLUTJ job.

<li>Ensure that any JCL that performs deferred index sorting for <var class="product">Model 204</var> version 7.5
(typically, FLOD jobs) uses the new <code>MYBUILD.M204V75.LOADLIB</code> for the E15 (OI15OS) and E35 (OI35OS) sort exits.
</ol>

==See also==
<ul>
<li>[[Upgrading to Model 204 version 7.5 on IBM z/VM CMS]]
<li>[[Upgrading to Model 204 version 7.5 on IBM z/VSE]]
</ul>

==Additional information==
Refer to the <var class="book">[[Media:M204_V7R4_zOS_Install.pdf|Rocket Model 204 Installation Guide for IBM z/OS, version 7.4]]</var>, for additional installation information.

[[Category:Installation]]

Upgrading to Model 204 version 7.5 on IBM z/OS

2015-10-23T19:49:33Z

Mlarocca: /* CRAM */

<div class="toclimit-3">__TOC__</div>
==Overview==
This page describes the steps required to upgrade from Rocket Model 204 version 7.4 to version 7.5, on the IBM® z/OS® operating system.

For information on the new features available in version 7.5, see the [[Release notes for Model 204 version 7.5|7.5 Release notes]].

<table><tr><td>In order to upgrade to Model 204 version 7.5, you must have version 7.4 and [[#Before you begin|various Early Warnings]] installed on your system.. </td></tr></table>

To upgrade to version 7.5 simply download, upload, and link the 7.5 object modules available from the downloads page to install the 7.5 components.

==Before you begin==
<ul>
<li>In order to upgrade to version 7.5, you must have version 7.4 and Early Warnings for Dictionary/204 through 740DI016 installed on your system.
Note: If you plan to use v7.4 CRAM with your v7.5 installation, you will need to apply all 7.4 maintenance. See [[#CRAM|CRAM]] for details.</li>
For information on Early Warnings, log in to the [http://www.rocketsoftware.com/support Rocket Customer Portal].</li>
<li>For system requirements for version 7.5, see the [[Release notes for Model 204 version 7.5#Operating system requirements|7.5 Release notes]].</li>
<li>You must have either a [[Rocket M204 user ID]] or a Sirius user ID to download the installation files.</li>
<li>The object library has the authorization zap (covering your licensed processors) preapplied, so you do not need to get a new authorization zap from the website. (The preapplied zap will authorize Model 204 itself and any separately purchased products such as SirScan.)</li>
<li>The object library also has the maintenance zaps (as of the time the stream was
prepared) preapplied, so you do not need to apply any maintenance as part of this installation. (You will only need to apply any new maintenance when it becomes available for this release.)</li>
</ul>
<div id="steps"></div>

==Overview of upgrading steps==

Review the following high-level summary of steps before you begin downloading the <var class="product">Model 204</var> version 7.5 files.

For an example, see [[#Example_workflow_for_7.5:_download_through_installation|Example workflow for 7.5: download through installation]].

<ol>
<li>Use your [[Rocket M204 user ID]] to [[#downloading|download]] the Model 204 object library and the Model 204 macro library.</li>

<li>[[#uploading|Upload]] the downloaded components to the z/OS system on the IBM mainframe.</li>

<li>[[#bldLibs|Build]] the RKOBJLIB object library and RKMACLIB macro library. (Once you have built these libraries, do not modify them.)</li>

<li>Submit the job to [[#allocating|allocate the other data sets]] required for installation.</li>

<li>If you have your own user $functions (FUNU), you must do the following steps:
<ol style="list-style-type:lower-alpha;">
<li>[[#FUNU_7.5|Modify FUNU for 64-bit addressing]] considerations and store the modified source in your local source library.</li>
<li>If you have any user-defined messages (MSGU), store them in your local source library.</li>
<li>[[#asmFUNU|Assemble]] FUNU (and MSGU, if applicable), with the output object file stored in your local object library.</li>
</ol>
</li>

<li>If you use an external authorizer (such as RACF) for <var class="product">Model 204</var>, [[#secparm|assemble the xxxxPARM security module]] (such as RACFPARM). The object file is then stored in your local object library.</li>

<li>If you use the [[#ul_db2|UL/DB2 interface]], preprocess and assemble the USQL module.</li>

<li>If you use other customized modules, such as CDTB, modify them as needed and [[#asm|assemble]] them.</li>

<li>Link the [[#lkonln|ONLINE]] load module.</li>

<li>If you use the [[#link_ifam1|IFAM1]] and [[#link_ifam4|IFAM4]] load modules, link them.</li>

<li>Link the <var class="product">Model 204</var> [[#lkutils|utility load modules]].</li>

<li>If you use the [[#cics|CICS interface]], customize it, and then assemble and link the CICS modules.</li>

<li>If you use the [[#tso|TSO]] interface, assemble and link-edit the TSO source modules.</li>

<li>If you use [[#softspy|SoftSpy]], upgrade it for 7.5.</li>
</ol>

==Object and macro libraries==
{{Template:Model 204 installation components}}

==Building the object and macro libraries==
To build the object and macro libraries, you must download the object library and macro library; upload each library to the mainframe; and copy, modify, and run the NEW204LB job.
<div id="downloading"></div>
===Downloading===

<ol>
<li>Using your [[Rocket M204 user ID]] and password, log in to the [https://model204.rocketsoftware.com/maint/objlist Model 204 object file download page].</li>
<li>Click the Download object file link beside the object library that you want to download.</li>
<li>Go to the [https://model204.rocketsoftware.com/maint/maclist Model 204 macro library download page].</li>
<li>Click the Download macro library link beside the macro library that you want to download.</li>
</ol>

<div id="uploading"></div>

===Uploading===

Once the object file and macro library are downloaded to your workstation, upload them to the z/OS system on the IBM mainframe. You can use any file transfer mechanism, including FTP and IND$FILE.

Specify these characteristics for the upload files:

<table class="noBorder">
<tr><td>transfer format:</td> <td>binary</td></tr>
<tr><td>record format:</td> <td>FB</td></tr>
<tr><td>record size:</td> <td>80 for object and macro libraries</td></tr>
<tr><td>block size:</td> <td>6400 for object and macro libraries</td></tr>
<tr><td>storage size for both:</td> <td>primary: 10 CYL; secondary: 5 CYL</td></tr>
</table>

For details on how to download and upload, see [[Downloading and uploading Model 204 installation components]].
<div id="bldLibs"></div>

===Building the object and macro libraries (NEW204LB job stream)===


After you upload the object and macro library input streams to the mainframe, build the object and macro libraries:

<ol>
<li>Access the [http://sirius.sirius-software.com/download/new204lb.txt NEW204LB job stream] text file.

<li>Copy the job stream file into a local TSO library for editing.

<li>On the first line of the job stream, modify the JOB card according to your local job card parameters.

<li>On the final four lines, marked <code>2 <<</code> ... <code>5 <<</code> on the right:
<ol style="list-style-type:lower-alpha;">
<li>Modify the <code>VERSION=</code> parameter, specifying the two-digit version of <var class="product">Model 204</var> you are installing, such as 75.
<li>Modify the <code>HLQ=</code> parameter, specifying the high-level qualifiers of all <var class="product">Model 204</var> installation data sets.
<li>Modify the <code>OBJINP=</code> parameter, using the DSN of the object library input file that you uploaded to the mainframe.
<li>Modify the <code>MACINP=</code> parameter, using the DSN of the macro library input file that you uploaded to the mainframe.
</ol>
<li>Submit the <code>NEW204LB</code> job to build the object library ("RKOBJLIB") and macro library ("RKMACLIB") on your z/OS system.</li>
</ol>

<div id="notouch"></div>
Attention: Once you have built RKOBJLIB and RKMACLIB on your z/OS system, do not modify them in any way. 

For example, do not store other members into the object library; it should only contain the members as supplied in a download from the web site. Place object files that you might assemble (such as FUNU or RACFPARM) into your local object library.

====RKOBJLIB README file====
README, a member of RKOBJLIB, contains details on the object files and installation steps. Once you have built RKOBJLIB, you can use README as an installation checklist if desired.

<div id="allocating"></div>

==Data sets for Model 204 upgrading==

There are three data sets used when upgrading to Model 204 7.5:

<ul>
<li>data set for the Model 204 load modules
<li>data set for the local source library
<li>data set for the local object library
</ul>
The data set for the load modules will contain, after linking, the modules for the Model 204 product, including: ONLINE, IFAM1, and IFAM4.

The local source library is used to store the customized source for modules such as FUNU, MSGU, and ACF2PARM, RACFPARM, or TOPSPARM.

When the source is assembled, it is stored in the local object library.

One of the members of the RKOBJLIB object library is named [[Model 204 data set allocation job stream for IBM z/OS|JALINSJ]], which is a job stream to allocate data sets for the installation. <code>JALINSJ</code> contains information about naming conventions for the data sets.

===Allocating data sets (JALINSJ job stream)===

<ol>
<li>Copy <code>JALINSJ</code> into a local TSO library.
<li>Edit your copy of <code>JALINSJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>JALINSJ</code> job to allocate the data set.
</ol>

<div id="lkonln"></div>

==Linking the Model 204 ONLINE load module==


<div id="onlnTable"></div>
<blockquote class="note">
Notes: 
<ul>
<li>If you use customized modules (such as FUNU, MSGU, ACF2PARM, RACFPARM, TOPSPARM, CDTB, or UL/DB2), you must [[#FUNU_7.5|modify]] them (if needed) and [[#asm|assemble]] them before you link the ONLINE/IFAM1/IFAM4 load modules.</li>
<li>There is not a separate link step for BATCH204. It is not maintained as a separate module; the same module as ONLINE is used, with a BATCH204 alias.</li>
</ul>
</blockquote>

One of the members of the RKOBJLIB object library is [[Model 204 ONLINE link job stream for z/OS|LKONLNJ]], which is a job stream to link the <var class="product">Model 204</var> ONLINE load module.

<div id="LKONLNJ"></div>
===Linking ONLINE (LKONLNJ job stream)===


<ol>
<li>Copy the <code>LKONLNJ</code> job stream from RKOBJLIB into a local TSO library.
<li>Edit your copy of <code>LKONLNJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with 1-4 followed by <code><<</code>. The numbers correspond to numbered steps in the comments.
<li>As needed, edit the lines after <code>SYSLIN DD *</code> that are marked with <code><<</code>. See the comments at the top of the <code>SYSLIN</code> sections (A-C) for instructions.
</ul>
<li>Submit the <code>LKONLNJ</code> job to link the ONLINE load module.
</ol>

Concise editing instructions are provided in the <code>LKONLNJ</code> file itself. More details about link-editing the ONLINE load module are provided in the following table.

<table class="thJustBold">
<tr><th>1</th><td>You must specify a value for the HLQ symbolic parameter in the EXEC LKM204P statement. The value of HLQ corresponds to the high-level qualifier used for the DSN for:
<ul>
<li> the downloaded object library</li>
<li>the Model204 load library</li>
<li>other data sets that are required for installation</li>
</ul></td></tr>
<tr><th>2</th><td>One of the modifications is always required, based on whether the ONLINE is to use RSQL (for Connect*) or not.

Uncomment only one of the following statements:
<ul>
<li>To link an ONLINE that uses RSQL, you must uncomment the INCLUDE RKOBJ204(LKSQLONL) statement.
<li>To link an ONLINE that does not use RSQL, you must uncomment the INCLUDE RKOBJ204(LKNOSONL) statement.
</ul>
</td></tr>
<tr><th>3</th><td>If you use an external authorizer, such as RACF or ACF2, you must:
<ul>
<li>[[#asm|Assemble the xxxPARM]] for your external authorizer to add the object file (such as RACFPARM or ACF2PARM) to your local object library.
<li>In the SYSLIN DD *, uncomment the appropriate INCLUDE statement(s) for your external authorizer. <blockquote class="note">Notes:
<ul><li>Uncomment either the "static" or "dynamic" INCLUDE statement, depending on your configuration.<li>If you use ACF2, there are two INCLUDE statements to be uncommented; one refers to your system ACF2 library. You must also provide the DSN for the ACF2 library in the ACF2 symbolic parameter in the EXEC LKM204P statement.</ul>
</blockquote>
</ul>
</td></tr>

<tr><th>4</th><td>If you have other programs that you assemble for your Model 204 ONLINE module, for example, [[#FUNU|FUNU]], assemble them into your local object library. You do not need to add additional INCLUDE statements for FUNU or other locally assembled object files; they are already in the include streams from RKOBJLIB.
</td></tr>

<tr><th>5</th><td>If you have an MQ series load library, set the MQ symbolic parameter to the correct DSN in the EXEC LKM204P statement. This allows you to use the MQ Series feature of <var class="product">Model 204</var>, either if you are already authorized for it, or to support a trial of it, without requiring relinking of the load module. You must also uncomment the INCLUDE MQ statement in the SYSLIN input.
</td></tr>

</table>

<div id="link_ifam1"></div>

==Linking the Model 204 IFAM1 load module==


One of the members of the RKOBJLIB object library is [http://m204wiki.rocketsoftware.com/index.php/Model_204_IFAM1_link_job_stream_for_IBM_z/OS?title=Model_204_IFAM1_link_job_stream_for_IBM_z/OS&target=blank LKIFAM1J], which is a job stream to link the <var class="product">Model 204</var> IFAM1 load module.

===Linking IFAM1 (LKIFAM1J job stream)===
<ol>
<li>Copy the <code>LKIFAM1J</code> job stream from RKOBJLIB into a local TSO library.
<li>Edit your copy of <code>LKIFAM1J</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>LKIFAM1J</code> job to link the IFAM1 load module.
</ol>

<div id="link_ifam4"></div>

==Linking the Model 204 IFAM4 load module==


One of the members of the RKOBJLIB object library is [http://m204wiki.rocketsoftware.com/index.php/Model_204_IFAM4_link_job_stream_for_IBM_z/OS?title=Model_204_IFAM4_link_job_stream_for_IBM_z/OS&target=blank LKIFAM4J], which is a job stream to link the <var class="product">Model 204</var> IFAM4 load module.

===Linking IFAM4 (LKIFAM4J job stream)===

<ol>
<li>Copy the <code>LKIFAM4J</code> job stream from RKOBJLIB into a local TSO library.
<li>Edit your copy of <code>LKIFAM4J</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>LKIFAM4J</code> job to link the IFAM4 load module.
</ol>

<div id="lkutils"></div>


==Linking the Model 204 utility load modules==


Most of the utility load modules from Model 204 version 7.4 will continue to perform correctly when used with version 7.5.

However, you must use the 7.5 version of the following utilities, which are sensitive to the Model 204 journal and checkpoint format:
<table>
<tr><td>AUDIT204</td> <td>Extract from journal, with report stats and analysis</td></tr>
<tr><td>MERGEJ</td> <td>Merge concurrent journal streams</td></tr>
<tr><td>UTILC</td> <td>Information from checkpoint stream</td></tr>
<tr><td>UTILJ</td> <td>Information from journal stream; add EOF markers</td></tr>
</table>

===Linking the utility load modules (LKALLUTJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 utilities link job stream for IBM z/OS|LKALLUTJ]], a job stream to link the <var class="product">Model 204</var> utility load modules.
<ol>
<li>Copy <code>LKALLUTJ</code> into a local TSO library.
<li>Edit your copy of <code>LKALLUTJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the line after <code>EXEC LKALLUTP</code> at the bottom of the job stream
</ul>
</ul>
<li>Submit the <code>LKALLUTJ</code> job to link the utility load modules.
</ol>

<div id="asm"></div>
==Assembling customized modules into your local object library (LOCAL.OBJLIB)==

Copy the customized source module (such as, FUNU, MSGU, ACF2PARM, RACFPARM, TOPSPARM, CDTB, or UL/DB2) from your current release into your local source library, if you have not already done so.
The local source library is not version-specific, so modules copied into it can be used for future installations.

One of the members of the RKOBJLIB object library is [[Model 204 local member assembly job stream for IBM z/OS|JASMJ]], a job stream to assemble a member from your Model 204 local source library into your local object library (LOCAL.OBJLIB).

===Assembling customized modules (JASMJ job stream)===
<ol>
<li>Copy <code>JASMJ</code> into a local TSO library.
<li>Edit your copy of <code>JASMJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the ASM line at the bottom of the job stream
</ul>
<li>Provide the member name to assemble (such as FUNU, MSGU, RACFPARM) on the <code>MEM=</code> line.
</ul>
<li>Submit the <code>JASMJ</code> job to assemble the module into your local object library.
</ol>

<div id="lkcram"></div>
<div id="secparm"></div>

==Setting up the security module==

If you use a [[Security_interfaces_overview|security interface]] such as ACF2, RACF, or Top Secret:

<ol>
<li> [[#asm|Assemble]] the security module:
ACF2PARM, RACFPARM, or TOPSPARM.</li>
<li>Optional. Link the security module as described below if you want it to be dynamically loaded.</li>
</ol>

===Linking the security module (LKSECRJ job stream)===

Dynamic loading lets you modify the security parameters without having to relink Model 204, which would be required if the parameter module were linked into Model 204 directly.

If you want Model 204 to dynamically load your security module during Model 204 ACF2, RACF, or TOPSECRET interface initialization, then you must link the corresponding security parameter module.

One of the members of the RKOBJLIB object library is <code>LKSECRJ</code>, a job stream to link-edit the security parameter module.

<ol>
<li>Copy [[Model 204 security module link job stream for IBM z/OS|LKSECRJ]] into a local TSO library.
<li>Edit your copy of <code>LKSECRJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>LKSECRJ</code> job to link-edit the security parameter module (ACF2PARM, RACFPARM, or TOPSPARM).
</ol>
<div id="cics"></div>

==CICS interface installation==

The Model 204 CICS interface allows CICS complete access to Model 204 facilities and supports CICS pseudo conversational programs.
Note: It is not necessary to install the CICS interface if it has been installed for a previous version of Model 204. The load modules from the older version are compatible with version 7.5 of Model 204.

===Requirements===
<ul>
<li>CICS Transaction Server support
Rocket M204 supports the CICS Transaction Server versions 3.1, 3.2, 4.1, and 4.2.</li>
<li>Supporting TPROCESS COBOL applications
If your CICS TPROCESS application was originally linked with AMODE=24, you must relink the CICS TPROCESS application specifying AMODE=31 because AMODE=24 is not supported.</li>
</ul>

===CICS interface overview===
For an overview of the CICS interface, including storage requirements and a listing of CICS interface components, see [[CICS interface]].

===Installing the CICS interface===

<ol>
<li>Customize the interface by copying the CICFG copy member from RKMACLIB into your local source library and editing it as needed.
For information on customizations needed for using the CICS Standard Mapping Service, see [[CICS interface]].</li>
<li>Update the CICS System Definition (CSD) using one of the following methods:
<ul><li>Resource Definition Online (CEDA). The supplied member CEDAM204 in RKMACLIB provides an example of the required PCT, PPT, and PLT definitions.</li>
<li>The IBM DFHSCDUP offline utility, to process the definitions in batch.</li>
</ul>
<li>[[#CICS_alloc|Allocate]] a CICS user library.</li>
<li>[[#CICS_asm|Assemble and link]] the CICS modules.</li>
</ol>

===Updating the CICS System Definition (CSD)===
You can update the CSD by using either CEDA or the DFHCSDUP utility and the CEDAM204 member of RKMACLIB. Use the values in the following table, where appropriate, for the method you choose. Information about
using CEDA follows the table.

CICS System Definition values
<table>
<tr class="head"><th>User program</th> <th>Program name</th> <th>Transaction ID</th> <th>Modifiable CICFG symbol</th>
<th>TWA size</th></tr>
<tr><td>IFAM2 pseudo conversational</td> <td>DFHPSF</td> <td>DFHPSF is accessed by using a CICS LINK. It is never
invoked with a transaction ID from a terminal.</td> <td /> <td /><tr>
<tr><td>Full-screen interface</td> <td>M204PSFS</td> <td>M204</td> <td>&TRN</td> <td>88</td></tr>
<tr><td>Screen copy transaction</td> <td>M204CRPS</td> <td>U204</td> <td /> <td /></tr>
<tr><td>Screen print transaction</td> <td>M204PRNT</td> <td>P204</td> <td>&COP</td> <td>88</td></tr>
</table>
CEDA (the Resource Definition Online transaction) or the DFHCSDUP utility defines the transactions and programs to the CSD file.

If you are not using the CEDAM204 member, then define the transactions and programs by using CEDA
and the values in the previous table, as in the following example:
CEDA DEFine PROG(program_name)
GRoup(group_name)
LANGuage(ASSEMBLER)
RELoad(NO)
RESident(NO) (Except for DFHPSF, RESident(YES))
RSL(PUBLIC)
STatus(ENABLED)

CEDA DEFine TRANsaction(trans_ID)
GRoup(group_name)
PROgram(program_name)
TWASIZE(twa_size_value)
.
.
.
RSL(PUBLIC)
.
.
.

CEDA CHeck GRoup(group_name) 

You can use a transaction ID for a user program that is different from the value
shown in the previous table. However, if you do so, you must change the associated
CICFG symbol shown in the table.

As shown in the preceding example, group_name is any valid group name for the
user site.

 Note: Remember to add the groups to the GRPLIST for the particular CICS
region. If the groups are not added, they are not installed during each CICS initialization.

<div id="CICS_alloc"></div>

===Allocating a CICS user library (JALCICSJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 CICS user library allocation job stream for IBM z/OS|JALCICSJ]], a job stream to allocate an empty CICS user library. You must allocate the CICS user library before assembling and linking the CICS modules.
<ol>
<li>Copy <code>JALCICSJ</code> into a local TSO library.</li>
<li>Edit your copy of <code>JACICSJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.</li>
<li>Supply your installation high level qualifier(s) in the following lines marked with <<:
<ul>
<li>for hlq in the JCLLIB ORDER=(hlq.... line after the JOB card </li>
<li>after HLQ=, on the line after EXEC LKALLUTP at the bottom of the job stream </li>
</ul>
</ul>
</li>
<li>Submit the <code>JALCICSJ</code> job to allocate the CICS user library.</li>
</ol>

<div id="CICS_asm"></div>
===Assembling and linking CICS modules (LKCICSJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 CICS module assembly job stream for_ IBM z/OS|LKCICSJ]], a job stream to assemble and link the <var class="product">Model 204</var> CICS modules.
<ol>
<li>Copy <code>LKCICSJ</code> into a local TSO library.
<li>Edit your copy of <code>LKCICSJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your Model 204 installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the line after <code>EXEC JALCICSP</code> at the bottom of the job stream
</ul>
</ul>
<li>Submit the <code>LKCICSJ</code> job to assemble and link the CICS module.
</ol>

<div id="tso"></div>

==TSO interface installation==

Note: It is not necessary to install the TSO interface if it has been installed for a previous version of Model 204. The load modules from the older version are compatible with version 7.5 of Model 204.

The Model 204 TSO Interface enables the TSO user to communicate with a Model 204 Online.

The TSO Interface consists of two assembly language modules, TSFS and TSUL, whose source is located in the macro library. The modules are completely reentrant, reusable, and refreshable. Installation requires assembly and link-editing of the TSO source modules.

===Installing the TSO interface===

<ol>
<li>If you are using TSO extensions, modify TSFS in the local source library by changing:
&TSOV SETC 'TSO' 
to:
&TSOV SETC 'TSOE'</li>
Changing the &TSOV SETC 'TSO' code in TSFS causes assembly of the NOEDIT form of the TPUT macro in the TSFS module. The NOEDIT form, required for 3270 extended data streams, allows proper handling of colors or highlighting in TSO extensions. NOEDIT is recommended for all TSO extensions.
<li>Assemble and link the TSO modules, using the <code>LKTSOJ</code> job.</li>
</ol>

===Assembling TSO modules (LKTSOJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 utilities link job stream for IBM z/OS|LKTSOJ]], a job stream to assemble and link the <var class="product">Model 204</var> TSO modules.
<ol>
<li>Copy <code>LKTSOJ</code> into a local TSO library.
<li>Edit your copy of <code>LKTSOJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the line after <code>EXEC LKALLUTP</code> at the bottom of the job stream
</ul>
</ul>
<li>Submit the <code>LKTSOJ</code> job to assemble and link the TSO modules.
</ol>
<div id="FUNU"></div>

==CRAM==
RKOBJLIB also contains LKCRAMJ, the job stream to link the CRAM load modules.

Versions 7.4 and later of the CRAM load modules are completely compatible with version 7.5 of Model 204. Deploying a new version of CRAM can be an intensive process, and because you have version 7.4 installed, it is not necessary. You can safely bypass linking the 7.5 CRAM modules. However, if you do not link the 7.5 CRAM modules, you will need to apply additional 7.4 maintenance.

Your CRAM installation options are:
<ul>
<li>Install 7.5 XDM by running LKCRAMJ to link the 7.5 CRAM modules.</li>
<li>
Install 7.4 XDM and then apply Early Warnings for Model 204. (You can do this by applying Autofix release EW3044, which includes these Early Warnings as well as Early Warnings for Dictionary/204 through 740DI016.)
</li>
<li>
Sharing 7.1 XDM requires maintenance through 710EW172.
</li>
</ul>

==FUNU and optional MSGU==


This section lists installation considerations if you have your own user-written $functions module (FUNU).

Note: If you have your own FUNU or MSGU module, you must assemble it before linking the ONLINE/IFAM1/IFAM4 load modules.

<div id="FUNU_7.5"></div>
===FUNU changes for version 7.5===


{{Template:FUNU changes for 7.5}}

<div id="asmFUNU"></div>
===FUNU (and MSGU) assembly===


Copy the source from RKMACLIB into your local source library.

After making any changes required for this version of <var class="product">Model 204</var>, run <code>JASMJ</code> to [[#asm|assemble]] FUNU into your local object library.

If needed, modify and run <code>JASMJ</code> to assemble MSGU.

You do not need to insert any INCLUDE statements for either FUNU nor MSGU; they are already present in the INCLUDE member (LKSQLONL or LKNOSONL) provided in the downloaded object library.

<div id="ul_db2"></div>

==Installing the UL/DB2 interface (JAUSQLJ job stream)==

To support the UL/DB2 interface, USQL code is delivered in source for you to preprocess for your version of DB2. If you use the UL/DB2 interface, assemble the source as described below before linking the ONLINE/IFAM1/IFAM4 load modules.

<ol>
<li>Copy [[Model 204 UL/DB2 job stream for IBM z/OS|JAUSQLJ]] into a local TSO library.
<li>Edit your copy of <code>JAUSQLJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>on the line after <code>EXEC JAUSQLP</code> at the bottom of the job stream set:
<ul>
<li><code>HLQ=</code>high level qualifier of all Model 204 installation DSNs</li>
<li><code>DB2HLQ=</code>high level qualifier for your DB2 maclib.</li>
</ul>
</ul>
</ul>
<li>Submit the <code>JAUSQLJ</code> job to preprocess and assemble the USQL module. The JAUSQLJ job executes the following two steps:
<ul>
<li>Run USQL (contained in RKMACLIB) through the DB2 preprocessor to process the EXEC SQL statements. This step produces two data sets: the DBRM and the expanded USQL source. The DBRM is saved as USQLDBRM in the local object library. The expanded USQL source is passed to step two for assembly.</li>
<li>Assemble expanded USQL source into local object library.</li>
</ul>
<li>Bind the DBRM as the plan with a site-specific plan name.</li>
</ol>
For more information on UL/DB2, see the <var class="book">Rocket Model 204 User Language/DATABASE 2 Interface Guide</var>.

<div id="softspy"></div>

==Upgrading SoftSpy for 7.5==

To upgrade SoftSpy for version 7.5, download, upload, and restore the SoftSpy procedure file, SPYPROC, which is distributed in a dump format.

<ol>
<li>Download SPYPROC, in binary form, from the [https://m204.rocketsoftware.com/maint/ullist?nickname=ROCKET SOUL files download page] to a workstation file.</li>
<li>Upload the file from your workstation to your z/OS system.</li>
<li>RESTORE the file into a Model 204 SOUL file.</li>
</ol>
For detailed instructions, see [http://m204wiki.rocketsoftware.com/index.php?title=Web_help_download_SOUL_files#How_can_the_dump_file_be_uploaded_to_the_mainframe.3F Downloading and restoring SOUL files].

==Verifying Model 204 7.5 on your system==
To perform an initial verification that your upgrade to 7.5 was successful, issue the following commands from the Model 204 command line.
<table>
<tr class="head"><th>Command</th> <th>You should see...</th></tr>
<tr><td>ROCKET</td> <td>A list of authorized M204 products (including 7.5) currently on your system.</td></tr>
<tr><td>DISPLAY ZAPS</td> <td>A list of Model 204 zaps (including 7.5 zaps) on your system.</td></tr>
<tr><td>DICTADMIN</td> <td>The Dictionary Administration subsystem, displaying <code>Release 7.5</code> on its menu screens.</td></tr>
<tr><td>SUBSYSMGMT</td> <td>The Application Subsystem facility, displaying <code>VER 7 REL 5</code> on its menu screens.</td></tr>
</table>

==Example workflow for 7.5: download through installation==
This example shows one typical installation workflow: the site does not use RSQL, it uses the RACF external authorizer, and it does not have its own FUNU. The IBM system MQ loadlib is <code>MQSERIES.SCSQLOAD</code> (this is typical in z/OS).
The high-level qualifier in this example is MYBUILD.

The other item needed is the member name <code>MYBLDOB</code>, which is chosen arbitrarily for this example, and the following DSNs:
<ul>
<li><code>MYBUILD.M204V75.RKOBJLIB.DISTRIB</code>
<li><code>MYBUILD.M204V75.RKOBJLIB</code>
<li><code>MYBUILD.M204V75.RKMACLIB.DISTRIB</code>
<li><code>MYBUILD.M204V75.RKMACLIB</code>
<li><code>MYBUILD.M204V75.LOCAL.OBJLIB</code>
<li><code>MYBUILD.M204V75.LOADLIB</code>
</ul>
===Build RKOBJLIB===
<ol>

<li>Download the object library (M204V75.OBJ) from the downloads page.

<li>Upload to the mainframe, in binary format, with settings FB/80/6400, as <code>MYBUILD.M204V75.RKOBJLIB.DISTRIB</code>.

<li>Download the macro library (M204V75_ZOS.MAC) from the downloads page.

<li>Upload to the mainframe, in binary format, with settings FB/80/6400, as <code>MYBUILD.M204V75.RKMACLIB.DISTRIB</code>.

<li>Create the member MYBLDOB in my TSO library from a [http://sirius-software.com/download/new204lb.txt download] of the job stream to build the object and macro libraries, using the following at the end of the job stream:
//BLD EXEC NEW204LB,VERSION=75,
// HLQ=MYBUILD,
// OBJINP=MYBUILD.M204V75.RKOBJLIB.DISTRIB,
// MACINP=MYBUILD.M204V75.RKMACLIB.DISTRIB


<li>Run MYBLDOB from my TSO library. MYBLDOB deletes and then creates <code>MYBUILD.M204V75.RKOBJLIB</code> and
<code>MYBUILD.M204V75.RKMACLIB</code>.

<li>Upload to the mainframe, in binary format, with settings FB/80/6400, as <code>MYBUILD.M204V75.RKMACLIB.DISTRIB</code>.

<li>Create the member MYBLDDS in my TSO library by copying
the job stream from [[Model 204 data set allocation job stream for IBM z/OS|JALINSJ]], using the following at the end of the job stream:
//BLD EXEC JALINSP,
// HLQ=MYBUILD


<li>Run MYBLDDS from my TSO library. MYBLDDS allocates an empty loadlib data set for the Model 204 load modules, an empty local source library for the customized source files, and an empty local object library for the customized local object modules, with the following names: <code>MYBUILD.M204V75.LOADLIB</code>, <code>MYBUILD.M204.LOCAL.SRCLIB</code> and <code>MYBUILD.M204V75.LOCAL.OBJLIB</code>.

</ol>

===Assemble and link===
<ol >
<li>Copy the RACFPARM source to the <code>MYBUILD.M204.LOCAL.SRCLIB</code> and make any necessary modifications.
<li>Create the member JASMSECJ in my TSO library by copying
the job stream from [[Model 204 local member assembly job stream for IBM z/OS|JASMJ]], using the following at the end of the job stream:
//ASM EXEC JASMP,HLQ=MYBUILD,
// MEM=RACFPARM


<li>Run JASMSECJ from my TSO library; this assembles the RACFPARM source file in the <code>MYBUILD.M204.LOCAL.SRCLIB</code> and stores the object in <code>MYBUILD.M204V75.LOCAL.OBJLIB</code>.

<li>Copy the member LKONLNJ from <code>MYBUILD.M204V75.RKOBJLIB</code> to my TSO library, and customize LKONLN as follows:
<ul>
<li>Make these changes at the top of the job stream:
// JCLLIB ORDER=(MYBUILD.M204V75.RKOBJLIB)
//LKONLN EXEC LKM204P,
// HLQ=MYBUILD,
// MQ=MQSERIES.SCSQLOAD

<li>Uncomment the <code>INCLUDE</code> line for LKNOSONL (that is, without RSQL).
<li>Uncomment the <code>INCLUDE</code> line for MQ.
<li>Uncomment the <code>INCLUDE</code> line for my external authorizer module (such as RACFOS and RACFPARM).
<li>Submit the LKONLNJ job from my TSO library, this creates ONLINE (and BATCH204 alias) in MYBUILD.M204V75.LOADLIB.
</ul>

<li>Perform a simple smoke test: run BATCH204 with 'DISPLAY ZAPS' and 'ROCKET' commands.

<li>To link the utilities, copy member LKALLUTJ from <code>MYBUILD.M204V75.RKOBJLIB</code> to my TSO library, and see all <code><<</code> lines to customize for my site; submit the LKALLUTJ job.

<li>Ensure that any JCL that performs deferred index sorting for <var class="product">Model 204</var> version 7.5
(typically, FLOD jobs) uses the new <code>MYBUILD.M204V75.LOADLIB</code> for the E15 (OI15OS) and E35 (OI35OS) sort exits.
</ol>

==See also==
<ul>
<li>[[Upgrading to Model 204 version 7.5 on IBM z/VM CMS]]
<li>[[Upgrading to Model 204 version 7.5 on IBM z/VSE]]
</ul>

==Additional information==
Refer to the [http://m204wiki.rocketsoftware.com/images/d/de/M204_V7R4_zOS_Install.pdf Rocket Model 204 Installation Guide for IBM z/OS, version 7.4], for additional installation information.

[[Category:Installation]]

XDMSSN parameter

2015-09-22T19:24:08Z

Mlarocca: /* Summary */

{{Template:XDMSSN parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>Current setting of the z/OS subsystem name linked into the IGCLM244 module
<dt>Parameter type
<dd>System
<dt>Where set
<dd>Cannot be reset
<dt>Related products
<dd>All
<dt>Introduced
<dd><var class="product">Model 204 V6.1</var>
</dl>

==Description==
The XDMSSN parameter passes a z/OS subsystem name that bypasses the IGCLM244 value.
This parameter is available for z/OS with XDM only and can pass the subsystem name inside the channel parameter in the form: 
subsystem

[[Category:System parameters]]
[[Category:Parameters]]

SERVGA parameter

2015-06-29T14:54:03Z

Mlarocca: /* Description */

{{Template:SERVGA parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>0
<dt>Parameter type
<dd>System
<dt>Where set
<dd>On User 0's parameter line
<dt>Related products
<dd>All
<dt>Introduced
<dd><var class="product">Model 204 V7.5</var>
</dl>

==Description==

The <var>SERVGA</var> parameter controls which server tables are allocated in the ATB-swappable-server area.
In Model 204 7.5 and later, only QTBL and NTBL (in bold below) can alternatively be placed above-the-bar in a swappable area. 
Each server table to be allocated in that area is controlled by a bit in <var>SERVGA</var>; if the bit is on, the corresponding server table is allocated in the ATB-swappable-server area.

The bits are:
<table class="thJustBold">
<tr><th>Bit</th><th>Server table placed above the bar</th></tr>
<tr><td><code>X'02000000'</code></td><td>FTBL</td></tr>

<tr><td><code>X'00800000'</code></td><td>GTBL — requires version 7.5 or later of <var class="product">Model 204</var>.</td></tr>

<tr><td><code>X'00004000'</code></td><td>'''NTBL''' — requires version 7.5 or later of <var class="product">Model 204</var>.</td></tr>

<tr><td><code>X'00002000'</code></td><td>'''QTBL''' — requires version 7.5 or later of <var class="product">Model 204</var>.</td></tr>

<tr><td><code>X'01000000'</code></td><td>XTBL — requires version 7.6 or later of <var class="product">Model 204</var>.</td></tr>

<tr><td><code>X'00400000'</code></td><td>ITBL — requires version 7.6 or later of <var class="product">Model 204</var>.</td></tr>

<tr><td><code>X'00100000'</code></td><td>FSCB — requires version 7.6 or later of <var class="product">Model 204</var>.</td></tr>

<tr><td><code>X'00080000'</code></td><td>STBL — requires version 7.6 or later of <var class="product">Model 204</var>.</td></tr>

<tr><td><code>X'00040000'</code></td><td>VTBL — requires version 7.6 or later of <var class="product">Model 204</var>.</td></tr>

<tr><td><code>X'00020000'</code></td><td>TTBL — requires version 7.6 or later of <var class="product">Model 204</var>.</td></tr>

<tr><td><code>X'00010000'</code></td><td>HTBFRS — requires version 7.6 or later of <var class="product">Model 204</var>.</td></tr>
</table>

<var>[[SERVGSZ parameter|SERVGSZ]]</var> is the amount of space in bytes required for the swappable above-the-bar server tables per server. The total amount of storage allocated for swappable above-the-bar server areas equals <var>SERVGSZ</var> rounded to 4K and multiplied by <var>[[NSERVS parameter|NSERVS]]</var>.
When sizing <var>SERVGSZ</var>, it should accomodate the largest swappable above-the-bar table sizes that might be needed.

The above mentioned tables can alternatively be placed above-the-bar in a non-swappable area. This can be indicated with the <var>[[SERVNSA parameter|SERVNSA]]</var> and <var>[[SERVNSSZ parameter|SERVNSSZ]]</var> parameters. The bits corresponding to the tables should not be set in both <var>SERVNSA</var> and <var>SERVGA</var> — if they are, an error message is issued and the Online fails to come up.

{{Template:SERVGA/SERVGSZ common}}

[[Category:System parameters]]
[[Category:Parameters]]

Upgrading to Model 204 version 7.5 on IBM z/OS

2015-03-04T15:16:30Z

Mlarocca: /* Assembling customized modules into your local object library (LOCAL.OBJLIB) */

<div class="toclimit-3">__TOC__</div>
==Overview==
This page describes the steps required to upgrade from Rocket Model 204 version 7.4 to version 7.5, on the IBM z/OS operating system.

<table><tr><td>In order to upgrade to Model 204 version 7.5, you must have version 7.4 and [[#Before you begin|various Early Warnings]] installed on your system.. </td></tr></table>

To upgrade to version 7.5 simply download, upload, and link the 7.5 object modules available from the downloads page to install the 7.5 components.

==Before you begin==
<ul>
<li>In order to upgrade to version 7.5, you must have version 7.4 and Early Warnings for Dictionary/204 through 740DI016 installed on your system.
For information on Early Warnings, log in to the [http://www.rocketsoftware.com/support Rocket Customer Portal].
Note: If you plan to use v7.4 CRAM with your v7.5 installation, you will need to apply all 7.4 maintenance. See [[#CRAM|CRAM]] for details.</li>
For information on Early Warnings, log in to the [http://www.rocketsoftware.com/support Rocket Customer Portal].</li>
<li>For system requirements for version 7.5, see the [[Release notes for Model 204 version 7.5#Operating system requirements|7.5 Release notes]].</li>
<li>You must have either a [[Rocket M204 user ID]] or a Sirius user ID to download the installation files.</li>
<li>The object library has the authorization zap (covering your licensed processors) preapplied, so you do not need to get a new authorization zap from the website. (The preapplied zap will authorize Model 204 itself and any separately purchased products such as MP/204 and SirScan.)</li>
<li>The object library also has the maintenance zaps (as of the time the stream was
prepared) preapplied, so you do not need to apply any maintenance as part of this installation. (You will only need to apply any new maintenance when it becomes available for this release.)</li>
</ul>
<div id="steps"></div>

==Overview of upgrading steps==

Review the following high-level summary of steps before you begin downloading the <var class="product">Model 204</var> version 7.5 files.

For an example, see [[#Example_workflow_for_7.5:_download_through_installation|Example workflow for 7.5: download through installation]].

<ol>
<li>Use your [[Rocket M204 user ID]] to [[#downloading|download]] the Model 204 object library and the Model 204 macro library.</li>

<li>[[#uploading|Upload]] (FTP) the downloaded components to the z/OS system on the IBM mainframe.</li>

<li>[[#bldLibs|Build]] the RKOBJLIB object library and RKMACLIB macro library. (Once you have built these libraries, do not modify them.)</li>

<li>Submit the job to [[#allocating|allocate the other data sets]] required for installation.</li>

<li>If you have your own user $functions (FUNU), you must do the following steps:
<ol style="list-style-type:lower-alpha;">
<li>[[#FUNU_7.5|Modify FUNU for 64-bit addressing]] considerations and store the modified source in your local source library.</li>
<li>If you have any user-defined messages (MSGU), store them in your local source library.</li>
<li>[[#asmFUNU|Assemble]] FUNU (and MSGU, if applicable), with the output object file stored in your local object library.</li>
</ol>
</li>

<li>If you use an external authorizer (such as RACF) for <var class="product">Model 204</var>, [[#secparm|assemble the xxxxPARM security module]] (such as RACFPARM). The object file is then stored in your local object library.</li>

<li>If you use the [[#ul_db2|UL/DB2 interface]], preprocess and assemble the USQL module.</li>

<li>If you use other customized modules, such as CDTB, modify them as needed and [[#asm|assemble]] them.</li>

<li>Link the [[#lkonln|ONLINE]] load module.</li>

<li>If you use the [[#link_ifam1|IFAM1]] and [[#link_ifam4|IFAM4]] load modules, link them.</li>

<li>Link the <var class="product">Model 204</var> [[#lkutils|utility load modules]].</li>

<li>If you use the [[#cics|CICS interface]], customize it, and then assemble and link the CICS modules.</li>

<li>If you use the [[#tso|TSO]] interface, assemble and link-edit the TSO source modules.</li>

<li>If you use [[#softspy|SoftSpy]], upgrade it for 7.5.</li>
</ol>

==Object and macro libraries==
{{Template:Model 204 installation components}}

==Building the object and macro libraries==
To build the object and macro libraries, you must download the object library and macro library; upload (FTP) each library to the mainframe; and copy, modify, and run the NEW204LB job.
<div id="downloading"></div>
===Downloading===

<ol>
<li>Using your [[Rocket M204 user ID]] and password, log in to the [https://model204.rocketsoftware.com/maint/objlist Model 204 object file download page].</li>
<li>Click the Download object file link beside the object library that you want to download.</li>
<li>Go to the [https://model204.rocketsoftware.com/maint/maclist Model 204 macro library download page].</li>
<li>Click the Download macro library link beside the macro library that you want to download.</li>
</ol>

<div id="uploading"></div>

===Uploading (FTP)===

Once the object file and macro library are downloaded to your workstation, FTP them to the z/OS system on the IBM mainframe.

Specify these characteristics for the upload files:

<table class="noBorder">
<tr><td>transfer format:</td> <td>binary</td></tr>
<tr><td>record format:</td> <td>FB</td></tr>
<tr><td>record size:</td> <td>80 for object and macro libraries</td></tr>
<tr><td>block size:</td> <td>6400 for object and macro libraries</td></tr>
<tr><td>storage size for both:</td> <td>primary: 10 CYL; secondary: 5 CYL</td></tr>
</table>

For details on how to download and upload, see [[Downloading and uploading Model 204 installation components]].
<div id="bldLibs"></div>

===Building the object and macro libraries (NEW204LB job stream)===


After you upload the object and macro library input streams to the mainframe, build the object and macro libraries:

<ol>
<li>Access the [http://sirius.sirius-software.com/download/new204lb.txt NEW204LB job stream] text file.

<li>Copy the job stream file into a local TSO library for editing.

<li>On the first line of the job stream, modify the JOB card according to your local job card parameters.

<li>On the final four lines, marked <code>2 <<</code> ... <code>5 <<</code> on the right:
<ol style="list-style-type:lower-alpha;">
<li>Modify the <code>VERSION=</code> parameter, specifying the two-digit version of <var class="product">Model 204</var> you are installing, such as 75.
<li>Modify the <code>HLQ=</code> parameter, specifying the high-level qualifiers of all <var class="product">Model 204</var> installation data sets.
<li>Modify the <code>OBJINP=</code> parameter, using the DSN of the object library input file that you uploaded to the mainframe.
<li>Modify the <code>MACINP=</code> parameter, using the DSN of the macro library input file that you uploaded to the mainframe.
</ol>
<li>Submit the <code>NEW204LB</code> job to build the object library ("RKOBJLIB") and macro library ("RKMACLIB") on your z/OS system.</li>
</ol>

<div id="notouch"></div>
Attention: Once you have built RKOBJLIB and RKMACLIB on your z/OS system, do not modify them in any way. 

For example, do not store other members into the object library; it should only contain the members as supplied in a download from the web site. Place object files that you might assemble (such as FUNU or RACFPARM) into your local object library.

====RKOBJLIB README file====
README, a member of RKOBJLIB, contains details on the object files and installation steps. Once you have built RKOBJLIB, you can use README as an installation checklist if desired.

<div id="allocating"></div>

==Data sets for Model 204 upgrading==

There are three data sets used when upgrading to Model 204 7.5:

<ul>
<li>data set for the Model 204 load modules
<li>data set for the local source library
<li>data set for the local object library
</ul>
The data set for the load modules will contain, after linking, the modules for the Model 204 product, including: ONLINE, IFAM1, and IFAM4.

The local source library is used to store the customized source for modules such as FUNU, MSGU, and ACF2PARM, RACFPARM, or TOPSPARM.

When the source is assembled, it is stored in the local object library.

One of the members of the RKOBJLIB object library is named [[Model 204 data set allocation job stream for IBM z/OS|JALINSJ]], which is a job stream to allocate data sets for the installation. <code>JALINSJ</code> contains information about naming conventions for the data sets.

===Allocating data sets (JALINSJ job stream)===

<ol>
<li>Copy <code>JALINSJ</code> into a local TSO library.
<li>Edit your copy of <code>JALINSJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>JALINSJ</code> job to allocate the data set.
</ol>

<div id="lkonln"></div>

==Linking the Model 204 ONLINE load module==


<div id="onlnTable"></div>
<blockquote class="note">
Notes: 
<ul>
<li>If you use customized modules (such as FUNU, MSGU, ACF2PARM, RACFPARM, TOPSPARM, CDTB, or UL/DB2), you must [[#FUNU_7.5|modify]] them (if needed) and [[#asm|assemble]] them before you link the ONLINE/IFAM1/IFAM4 load modules.</li>
<li>There is not a separate link step for BATCH204. It is not maintained as a separate module; the same module as ONLINE is used, with a BATCH204 alias.</li>
</ul>
</blockquote>

One of the members of the RKOBJLIB object library is [[Model 204 ONLINE link job stream for z/OS|LKONLNJ]], which is a job stream to link the <var class="product">Model 204</var> ONLINE load module.

<div id="LKONLNJ"></div>
===Linking ONLINE (LKONLNJ job stream)===


<ol>
<li>Copy the <code>LKONLNJ</code> job stream from RKOBJLIB into a local TSO library.
<li>Edit your copy of <code>LKONLNJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with 1-4 followed by <code><<</code>. The numbers correspond to numbered steps in the comments.
<li>As needed, edit the lines after <code>SYSLIN DD *</code> that are marked with <code><<</code>. See the comments at the top of the <code>SYSLIN</code> sections (A-C) for instructions.
</ul>
<li>Submit the <code>LKONLNJ</code> job to link the ONLINE load module.
</ol>

Concise editing instructions are provided in the <code>LKONLNJ</code> file itself. More details about link-editing the ONLINE load module are provided in the following table.

<table class="thJustBold">
<tr><th>1</th><td>You must specify a value for the HLQ symbolic parameter in the EXEC LKM204P statement. The value of HLQ corresponds to the high-level qualifier used for the DSN for:
<ul>
<li> the downloaded object library</li>
<li>the Model204 load library</li>
<li>other data sets that are required for installation</li>
</ul></td></tr>
<tr><th>2</th><td>One of the modifications is always required, based on whether the ONLINE is to use RSQL (for Connect*) or not.

Uncomment only one of the following statements:
<ul>
<li>To link an ONLINE that uses RSQL, you must uncomment the INCLUDE RKOBJ204(LKSQLONL) statement.
<li>To link an ONLINE that does not use RSQL, you must uncomment the INCLUDE RKOBJ204(LKNOSONL) statement.
</ul>
</td></tr>
<tr><th>3</th><td>If you use an external authorizer, such as RACF or ACF2, you must:
<ul>
<li>[[#asm|Assemble the xxxPARM]] for your external authorizer to add the object file (such as RACFPARM or ACF2PARM) to your local object library.
<li>In the SYSLIN DD *, uncomment the appropriate INCLUDE statement(s) for your external authorizer. <blockquote class="note">Notes:
<ul><li>Uncomment either the "static" or "dynamic" INCLUDE statement, depending on your configuration.<li>If you use ACF2, there are two INCLUDE statements to be uncommented; one refers to your system ACF2 library. You must also provide the DSN for the ACF2 library in the ACF2 symbolic parameter in the EXEC LKM204P statement.</ul>
</blockquote>
</ul>
</td></tr>

<tr><th>4</th><td>If you have other programs that you assemble for your Model 204 ONLINE module, for example, [[#FUNU|FUNU]], assemble them into your local object library. You do not need to add additional INCLUDE statements for FUNU or other locally assembled object files; they are already in the include streams from RKOBJLIB.
</td></tr>

<tr><th>5</th><td>If you have an MQ series load library, set the MQ symbolic parameter to the correct DSN in the EXEC LKM204P statement. This allows you to use the MQ Series feature of <var class="product">Model 204</var>, either if you are already authorized for it, or to support a trial of it, without requiring relinking of the load module. You must also uncomment the INCLUDE MQ statement in the SYSLIN input.
</td></tr>

</table>

<div id="link_ifam1"></div>

==Linking the Model 204 IFAM1 load module==


One of the members of the RKOBJLIB object library is [http://m204wiki.rocketsoftware.com/index.php/Model_204_IFAM1_link_job_stream_for_IBM_z/OS?title=Model_204_IFAM1_link_job_stream_for_IBM_z/OS&target=blank LKIFAM1J], which is a job stream to link the <var class="product">Model 204</var> IFAM1 load module.

===Linking IFAM1 (LKIFAM1J job stream)===
<ol>
<li>Copy the <code>LKIFAM1J</code> job stream from RKOBJLIB into a local TSO library.
<li>Edit your copy of <code>LKIFAM1J</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>LKIFAM1J</code> job to link the IFAM1 load module.
</ol>

<div id="link_ifam4"></div>

==Linking the Model 204 IFAM4 load module==


One of the members of the RKOBJLIB object library is [http://m204wiki.rocketsoftware.com/index.php/Model_204_IFAM4_link_job_stream_for_IBM_z/OS?title=Model_204_IFAM4_link_job_stream_for_IBM_z/OS&target=blank LKIFAM4J], which is a job stream to link the <var class="product">Model 204</var> IFAM4 load module.

===Linking IFAM4 (LKIFAM4J job stream)===

<ol>
<li>Copy the <code>LKIFAM4J</code> job stream from RKOBJLIB into a local TSO library.
<li>Edit your copy of <code>LKIFAM4J</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>LKIFAM4J</code> job to link the IFAM4 load module.
</ol>

<div id="lkutils"></div>


==Linking the Model 204 utility load modules==


Most of the utility load modules from Model 204 version 7.4 will continue to perform correctly when used with version 7.5.

However, you must use the 7.5 version of the following utilities, which are sensitive to the Model 204 journal and checkpoint format:
<table>
<tr><td>AUDIT204</td> <td>Extract from journal, with report stats and analysis</td></tr>
<tr><td>MERGEJ</td> <td>Merge concurrent journal streams</td></tr>
<tr><td>UTILC</td> <td>Information from checkpoint stream</td></tr>
<tr><td>UTILJ</td> <td>Information from journal stream; add EOF markers</td></tr>
</table>

===Linking the utility load modules (LKALLUTJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 utilities link job stream for IBM z/OS|LKALLUTJ]], a job stream to link the <var class="product">Model 204</var> utility load modules.
<ol>
<li>Copy <code>LKALLUTJ</code> into a local TSO library.
<li>Edit your copy of <code>LKALLUTJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the line after <code>EXEC LKALLUTP</code> at the bottom of the job stream
</ul>
</ul>
<li>Submit the <code>LKALLUTJ</code> job to link the utility load modules.
</ol>

<div id="asm"></div>
==Assembling customized modules into your local object library (LOCAL.OBJLIB)==

Copy the customized source module (such as, FUNU, MSGU, ACF2PARM, RACFPARM, TOPSPARM, CDTB, or UL/DB2) from your current release into your local source library, if you have not already done so.
The local source library is not version-specific, so modules copied into it can be used for future installations.

One of the members of the RKOBJLIB object library is [[Model 204 local member assembly job stream for IBM z/OS|JASMJ]], a job stream to assemble a member from your Model 204 local source library into your local object library (LOCAL.OBJLIB).

===Assembling customized modules (JASMJ job stream)===
<ol>
<li>Copy <code>JASMJ</code> into a local TSO library.
<li>Edit your copy of <code>JASMJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the ASM line at the bottom of the job stream
</ul>
<li>Provide the member name to assemble (such as FUNU, MSGU, RACFPARM) on the <code>MEM=</code> line.
</ul>
<li>Submit the <code>JASMJ</code> job to assemble the module into your local object library.
</ol>

<div id="lkcram"></div>
<div id="secparm"></div>

==Setting up the security module==

If you use a [[Security_interfaces_overview|security interface]] such as ACF2, RACF, or Top Secret:

<ol>
<li> [[#asm|Assemble]] the security module:
ACF2PARM, RACFPARM, or TOPSPARM.</li>
<li>Optional. Link the security module as described below if you want it to be dynamically loaded.</li>
</ol>

===Linking the security module (LKSECRJ job stream)===

Dynamic loading lets you modify the security parameters without having to relink Model 204, which would be required if the parameter module were linked into Model 204 directly.

If you want Model 204 to dynamically load your security module during Model 204 ACF2, RACF, or TOPSECRET interface initialization, then you must link the corresponding security parameter module.

One of the members of the RKOBJLIB object library is <code>LKSECRJ</code>, a job stream to link-edit the security parameter module.

<ol>
<li>Copy [[Model 204 security module link job stream for IBM z/OS|LKSECRJ]] into a local TSO library.
<li>Edit your copy of <code>LKSECRJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Edit the lines, near the top of the job stream, marked with numbers followed by <code><<</code>. The numbers correspond to numbered steps in the comments following these lines.
</ul>
<li>Submit the <code>LKSECRJ</code> job to link-edit the security parameter module (ACF2PARM, RACFPARM, or TOPSPARM).
</ol>
<div id="cics"></div>

==CICS interface installation==

The Model 204 CICS interface allows CICS complete access to Model 204 facilities and supports CICS pseudo conversational programs.
Note: It is not necessary to install the CICS interface if it has been installed for a previous version of Model 204. The load modules from the older version are compatible with version 7.5 of Model 204.

===Requirements===
<ul>
<li>CICS Transaction Server support
Rocket M204 supports the CICS Transaction Server versions 3.1, 3.2, 4.1, and 4.2.</li>
<li>Supporting TPROCESS COBOL applications
If your CICS TPROCESS application was originally linked with AMODE=24, you must relink the CICS TPROCESS application specifying AMODE=31 because AMODE=24 is not supported.</li>
</ul>

===CICS interface overview===
For an overview of the CICS interface, including storage requirements and a listing of CICS interface components, see [[CICS interface]].

===Installing the CICS interface===

<ol>
<li>Customize the interface by copying the CICFG copy member from RKMACLIB into your local source library and editing it as needed.
For information on customizations needed for using the CICS Standard Mapping Service, see [[CICS interface]].</li>
<li>Update the CICS System Definition (CSD) using one of the following methods:
<ul><li>Resource Definition Online (CEDA). The supplied member CEDAM204 in RKMACLIB provides an example of the required PCT, PPT, and PLT definitions.</li>
<li>The IBM DFHSCDUP offline utility, to process the definitions in batch.</li>
</ul>
<li>[[#CICS_alloc|Allocate]] a CICS user library.</li>
<li>[[#CICS_asm|Assemble and link]] the CICS modules.</li>
</ol>

===Updating the CICS System Definition (CSD)===
You can update the CSD by using either CEDA or the DFHCSDUP utility and the CEDAM204 member of RKMACLIB. Use the values in the following table, where appropriate, for the method you choose. Information about
using CEDA follows the table.

CICS System Definition values
<table>
<tr class="head"><th>User program</th> <th>Program name</th> <th>Transaction ID</th> <th>Modifiable CICFG symbol</th>
<th>TWA size</th></tr>
<tr><td>IFAM2 pseudo conversational</td> <td>DFHPSF</td> <td>DFHPSF is accessed by using a CICS LINK. It is never
invoked with a transaction ID from a terminal.</td> <td /> <td /><tr>
<tr><td>Full-screen interface</td> <td>M204PSFS</td> <td>M204</td> <td>&TRN</td> <td>88</td></tr>
<tr><td>Screen copy transaction</td> <td>M204CRPS</td> <td>U204</td> <td /> <td /></tr>
<tr><td>Screen print transaction</td> <td>M204PRNT</td> <td>P204</td> <td>&COP</td> <td>88</td></tr>
</table>
CEDA (the Resource Definition Online transaction) or the DFHCSDUP utility defines the transactions and programs to the CSD file.

If you are not using the CEDAM204 member, then define the transactions and programs by using CEDA
and the values in the previous table, as in the following example:
CEDA DEFine PROG(program_name)
GRoup(group_name)
LANGuage(ASSEMBLER)
RELoad(NO)
RESident(NO) (Except for DFHPSF, RESident(YES))
RSL(PUBLIC)
STatus(ENABLED)

CEDA DEFine TRANsaction(trans_ID)
GRoup(group_name)
PROgram(program_name)
TWASIZE(twa_size_value)
.
.
.
RSL(PUBLIC)
.
.
.

CEDA CHeck GRoup(group_name) 

You can use a transaction ID for a user program that is different from the value
shown in the previous table. However, if you do so, you must change the associated
CICFG symbol shown in the table.

As shown in the preceding example, group_name is any valid group name for the
user site.

 Note: Remember to add the groups to the GRPLIST for the particular CICS
region. If the groups are not added, they are not installed during each CICS initialization.

<div id="CICS_alloc"></div>

===Allocating a CICS user library (JALCICSJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 CICS user library allocation job stream for IBM z/OS|JALCICSJ]], a job stream to allocate an empty CICS user library. You must allocate the CICS user library before assembling and linking the CICS modules.
<ol>
<li>Copy <code>JALCICSJ</code> into a local TSO library.</li>
<li>Edit your copy of <code>JACICSJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.</li>
<li>Supply your installation high level qualifier(s) in the following lines marked with <<:
<ul>
<li>for hlq in the JCLLIB ORDER=(hlq.... line after the JOB card </li>
<li>after HLQ=, on the line after EXEC LKALLUTP at the bottom of the job stream </li>
</ul>
</ul>
</li>
<li>Submit the <code>JALCICSJ</code> job to allocate the CICS user library.</li>
</ol>

<div id="CICS_asm"></div>
===Assembling and linking CICS modules (LKCICSJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 CICS module assembly job stream for_ IBM z/OS|LKCICSJ]], a job stream to assemble and link the <var class="product">Model 204</var> CICS modules.
<ol>
<li>Copy <code>LKCICSJ</code> into a local TSO library.
<li>Edit your copy of <code>LKCICSJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your Model 204 installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the line after <code>EXEC JALCICSP</code> at the bottom of the job stream
</ul>
</ul>
<li>Submit the <code>LKCICSJ</code> job to assemble and link the CICS module.
</ol>

<div id="tso"></div>

==TSO interface installation==

Note: It is not necessary to install the TSO interface if it has been installed for a previous version of Model 204. The load modules from the older version are compatible with version 7.5 of Model 204.

The Model 204 TSO Interface enables the TSO user to communicate with a Model 204 Online.

The TSO Interface consists of two assembly language modules, TSFS and TSUL, whose source is located in the macro library. The modules are completely reentrant, reusable, and refreshable. Installation requires assembly and link-editing of the TSO source modules.

===Installing the TSO interface===

<ol>
<li>If you are using TSO extensions, modify TSFS in the local source library by changing:
&TSOV SETC 'TSO' 
to:
&TSOV SETC 'TSOE'</li>
Changing the &TSOV SETC 'TSO' code in TSFS causes assembly of the NOEDIT form of the TPUT macro in the TSFS module. The NOEDIT form, required for 3270 extended data streams, allows proper handling of colors or highlighting in TSO extensions. NOEDIT is recommended for all TSO extensions.
<li>Assemble and link the TSO modules, using the <code>LKTSOJ</code> job.</li>
</ol>

===Assembling TSO modules (LKTSOJ job stream)===

One of the members of the RKOBJLIB object library is [[Model 204 utilities link job stream for IBM z/OS|LKTSOJ]], a job stream to assemble and link the <var class="product">Model 204</var> TSO modules.
<ol>
<li>Copy <code>LKTSOJ</code> into a local TSO library.
<li>Edit your copy of <code>LKTSOJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>after <code>HLQ=</code>, on the line after <code>EXEC LKALLUTP</code> at the bottom of the job stream
</ul>
</ul>
<li>Submit the <code>LKTSOJ</code> job to assemble and link the TSO modules.
</ol>
<div id="FUNU"></div>

==CRAM==
RKOBJLIB also contains LKCRAMJ, the job stream to link the CRAM load modules.

Versions 7.4 and later of the CRAM load modules are completely compatible with version 7.5 of Model 204. Deploying a new version of CRAM can be an intensive process, and because you have version 7.4 installed, it is not necessary. You can safely bypass linking the 7.5 CRAM modules. However, if you do not link the 7.5 CRAM modules, you will need to apply additional 7.4 maintenance.

Your CRAM installation options are:
<ul>
<li>Install 7.5 XDM by running LKCRAMJ to link the 7.5 CRAM modules.</li>
<li>
Install 7.4 XDM and then apply Early Warnings for Model 204 through 740EW172. (You can do this by applying Autofix release EW3044, which includes these Early Warnings as well as Early Warnings for Dictionary/204 through 740DI016.)
</li>
</ul>

==FUNU and optional MSGU==


This section lists installation considerations if you have your own user-written $functions module (FUNU).

Note: If you have your own FUNU or MSGU module, you must assemble it before linking the ONLINE/IFAM1/IFAM4 load modules.

<div id="FUNU_7.5"></div>
===FUNU changes for version 7.5===


{{Template:FUNU changes for 7.5}}

<div id="asmFUNU"></div>
===FUNU (and MSGU) assembly===


Copy the source from RKMACLIB into your local source library.

After making any changes required for this version of <var class="product">Model 204</var>, run <code>JASMJ</code> to [[#asm|assemble]] FUNU into your local object library.

If needed, modify and run <code>JASMJ</code> to assemble MSGU.

You do not need to insert any INCLUDE statements for either FUNU nor MSGU; they are already present in the INCLUDE member (LKSQLONL or LKNOSONL) provided in the downloaded object library.

<div id="ul_db2"></div>

==Installing the UL/DB2 interface (JAUSQLJ job stream)==

To support the UL/DB2 interface, USQL code is delivered in source for you to preprocess for your version of DB2. If you use the UL/DB2 interface, assemble the source as described below before linking the ONLINE/IFAM1/IFAM4 load modules.

<ol>
<li>Copy [[Model 204 UL/DB2 job stream for IBM z/OS|JAUSQLJ]] into a local TSO library.
<li>Edit your copy of <code>JAUSQLJ</code> for your configuration:
<ul>
<li>Replace the first line with a JOB card.
<li>Supply your installation high level qualifier(s) in the following lines marked with <code><<</code>:
<ul>
<li>for <code>hlq</code> in the <code>JCLLIB ORDER=(hlq.</code>... line after the <code>JOB</code> card
<li>on the line after <code>EXEC JAUSQLP</code> at the bottom of the job stream set:
<ul>
<li><code>HLQ=</code>high level qualifier of all Model 204 installation DSNs</li>
<li><code>DB2HLQ=</code>high level qualifier for your DB2 maclib.</li>
</ul>
</ul>
</ul>
<li>Submit the <code>JAUSQLJ</code> job to preprocess and assemble the USQL module. The JAUSQLJ job executes the following two steps:
<ul>
<li>Run USQL (contained in RKMACLIB) through the DB2 preprocessor to process the EXEC SQL statements. This step produces two data sets: the DBRM and the expanded USQL source. The DBRM is saved as USQLDBRM in the local object library. The expanded USQL source is passed to step two for assembly.</li>
<li>Assemble expanded USQL source into local object library.</li>
</ul>
<li>Bind the DBRM as the plan with a site-specific plan name.</li>
</ol>
For more information on UL/DB2, see the <var class="book">Rocket Model 204 User Language/DATABASE 2 Interface Guide</var>.

<div id="softspy"></div>

==Upgrading SoftSpy for 7.5==

To upgrade SoftSpy for version 7.5, download, upload, and restore the SoftSpy procedure file, SPYPROC, which is distributed in a dump format.

<ol>
<li>Download SPYPROC, in binary form, from the [https://m204.rocketsoftware.com/maint/ullist?nickname=ROCKET SOUL files download page] to a workstation file.</li>
<li>Upload (FTP) the file from your workstation to your z/OS system.</li>
<li>RESTORE the file into a Model 204 SOUL file.</li>
</ol>
For detailed instructions, see [http://m204wiki.rocketsoftware.com/index.php?title=Web_help_download_SOUL_files#How_can_the_dump_file_be_uploaded_to_the_mainframe.3F Downloading and restoring SOUL files].

==Verifying Model 204 7.5 on your system==
To perform an initial verification that your upgrade to 7.5 was successful, issue the following commands from the Model 204 command line.
<table>
<tr class="head"><th>Command</th> <th>You should see...</th></tr>
<tr><td>ROCKET</td> <td>A list of authorized M204 products (including 7.5) currently on your system.</td></tr>
<tr><td>DISPLAY ZAPS</td> <td>A list of Model 204 zaps (including 7.5 zaps) on your system.</td></tr>
<tr><td>DICTADMIN</td> <td>The Dictionary Administration subsystem, displaying <code>Release 7.5</code> on its menu screens.</td></tr>
<tr><td>SUBSYSMGMT</td> <td>The Application Subsystem facility, displaying <code>VER 7 REL 5</code> on its menu screens.</td></tr>
</table>

==Example workflow for 7.5: download through installation==
This example shows one typical installation workflow: the site does not use RSQL, it uses the RACF external authorizer, and it does not have its own FUNU. The IBM system MQ loadlib is <code>MQSERIES.SCSQLOAD</code> (this is typical in z/OS).
The high-level qualifier in this example is MYBUILD.

The other item needed is the member name <code>MYBLDOB</code>, which is chosen arbitrarily for this example, and the following DSNs:
<ul>
<li><code>MYBUILD.M204V75.RKOBJLIB.DISTRIB</code>
<li><code>MYBUILD.M204V75.RKOBJLIB</code>
<li><code>MYBUILD.M204V75.RKMACLIB.DISTRIB</code>
<li><code>MYBUILD.M204V75.RKMACLIB</code>
<li><code>MYBUILD.M204V75.LOCAL.OBJLIB</code>
<li><code>MYBUILD.M204V75.LOADLIB</code>
</ul>
===Build RKOBJLIB===
<ol>

<li>Download the object library (M204V75.OBJ) from the downloads page.

<li>Upload to the mainframe, in binary format, with settings FB/80/6400, as <code>MYBUILD.M204V75.RKOBJLIB.DISTRIB</code>.

<li>Download the macro library (M204V75_ZOS.MAC) from the downloads page.

<li>Upload to the mainframe, in binary format, with settings FB/80/6400, as <code>MYBUILD.M204V75.RKMACLIB.DISTRIB</code>.

<li>Create the member MYBLDOB in my TSO library from a [http://sirius-software.com/download/new204lb.txt download] of the job stream to build the object and macro libraries, using the following at the end of the job stream:
//BLD EXEC NEW204LB,VERSION=75,
// HLQ=MYBUILD,
// OBJINP=MYBUILD.M204V75.RKOBJLIB.DISTRIB,
// MACINP=MYBUILD.M204V75.RKMACLIB.DISTRIB


<li>Run MYBLDOB from my TSO library. MYBLDOB deletes and then creates <code>MYBUILD.M204V75.RKOBJLIB</code> and
<code>MYBUILD.M204V75.RKMACLIB</code>.

<li>Upload to the mainframe, in binary format, with settings FB/80/6400, as <code>MYBUILD.M204V75.RKMACLIB.DISTRIB</code>.

<li>Create the member MYBLDDS in my TSO library by copying
the job stream from [[Model 204 data set allocation job stream for IBM z/OS|JALINSJ]], using the following at the end of the job stream:
//BLD EXEC JALINSP,
// HLQ=MYBUILD


<li>Run MYBLDDS from my TSO library. MYBLDDS allocates an empty loadlib data set for the Model 204 load modules, an empty local source library for the customized source files, and an empty local object library for the customized local object modules, with the following names: <code>MYBUILD.M204V75.LOADLIB</code>, <code>MYBUILD.M204.LOCAL.SRCLIB</code> and <code>MYBUILD.M204V75.LOCAL.OBJLIB</code>.

</ol>

===Assemble and link===
<ol >
<li>Copy the RACFPARM source to the <code>MYBUILD.M204.LOCAL.SRCLIB</code> and make any necessary modifications.
<li>Create the member JASMSECJ in my TSO library by copying
the job stream from [[Model 204 local member assembly job stream for IBM z/OS|JASMJ]], using the following at the end of the job stream:
//ASM EXEC JASMP,HLQ=MYBUILD,
// MEM=RACFPARM


<li>Run JASMSECJ from my TSO library; this assembles the RACFPARM source file in the <code>MYBUILD.M204.LOCAL.SRCLIB</code> and stores the object in <code>MYBUILD.M204V75.LOCAL.OBJLIB</code>.

<li>Copy the member LKONLNJ from <code>MYBUILD.M204V75.RKOBJLIB</code> to my TSO library, and customize LKONLN as follows:
<ul>
<li>Make these changes at the top of the job stream:
// JCLLIB ORDER=(MYBUILD.M204V75.RKOBJLIB)
//LKONLN EXEC LKM204P,
// HLQ=MYBUILD,
// MQ=MQSERIES.SCSQLOAD

<li>Uncomment the <code>INCLUDE</code> line for LKNOSONL (that is, without RSQL).
<li>Uncomment the <code>INCLUDE</code> line for MQ.
<li>Uncomment the <code>INCLUDE</code> line for my external authorizer module (such as RACFOS and RACFPARM).
<li>Submit the LKONLNJ job from my TSO library, this creates ONLINE (and BATCH204 alias) in MYBUILD.M204V75.LOADLIB.
</ul>

<li>Perform a simple smoke test: run BATCH204 with 'DISPLAY ZAPS' and 'ROCKET' commands.

<li>To link the utilities, copy member LKALLUTJ from <code>MYBUILD.M204V75.RKOBJLIB</code> to my TSO library, and see all <code><<</code> lines to customize for my site; submit the LKALLUTJ job.

<li>Ensure that any JCL that performs deferred index sorting for <var class="product">Model 204</var> version 7.5
(typically, FLOD jobs) uses the new <code>MYBUILD.M204V75.LOADLIB</code> for the E15 (OI15OS) and E35 (OI35OS) sort exits.
</ol>

==See also==
<ul>
<li>[[Upgrading to Model 204 version 7.5 on IBM z/VM CMS]]
<li>[[Upgrading to Model 204 version 7.5 on IBM z/VSE]]
</ul>

==Additional information==
Refer to the [http://m204wiki.rocketsoftware.com/images/d/de/M204_V7R4_zOS_Install.pdf Rocket Model 204 Installation Guide for IBM z/OS, version 7.4], for additional installation information.

[[Category:Installation]]

Downloading and uploading Model 204 installation components

2014-12-17T20:08:13Z

Mlarocca: /* FTP JCL example */

===Downloading object files===
From the downloads page, you can download a file directly or have it emailed. Receiving the object deck through e-mail might take a little longer than downloading it directly, but it allows you to schedule a set of objects to be sent to a different person in your organization.

To download a file, click the Download object file link beside the object that you want.

To email a file:
<ol>
<li>Fill in the Target e-mail address field at the top of the downloads list.</li>
<li>Click the Email object file link beside the object that you want.

The object deck will be e-mailed to the specified address as an attachment.</li>
<li>Save the attachment to a local file and then upload it to the mainframe exactly as if you had downloaded it directly.</li>
</ol>

===Uploading object files===
Once the object files are downloaded to the workstation, you must upload them to the z/OS system on the IBM mainframe.
You can use any file transfer mechanism, including FTP and IND$FILE.
Regardless of the transfer mechanism, you must observe the following rules:
<ul>
<li>Transfer the object file in binary format. (No translation from ASCII to EBCDIC must occur as a result of the upload.)</li>
<li>Specify storage size and the RECFM, LRECL, and BLOCKSIZE characteristics of the data set for the object you are transferring:</li>
</ul>
<table>
<tr><th>record format</th> <td>FB (fixed record length with block records)</td></tr>
<tr><th>record size</th> <td>80 for object and macro libraries; 6184 for procedure files</td></tr>
<tr><th>block size</th> <td>6400 for object and macro libraries; 6184 for procedure files</td></tr>
<tr><th>storage size</th><td>primary: 10 CYL; secondary: 5 CYL</td></tr>
</table>

If you are using FTP to upload a file:
<ul>
<li>Use the SITE command 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.)</li>
<li>Use the LOCSITE command if the FTP client is on the mainframe and the server is on the workstation.</li>
</ul>

===FTP JCL example===
The following z/OS JCL to FTP from the FTP server also shows the use of LOCSITE:
//jobcard
//FTP EXEC PGM=FTP,PARM='(EXIT=4,TRAC,TI=20)'
//* (PARM is optional)
//OUTPUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//INPUT DD *
ipaddress (or domain name) of ftp server, n.n.n.n
user login
pswd
binary
LOCSITE CYL
LOCSITE PRIMARY=10
LOCSITE SECONDARY=5
LOCSITE LRECL=80
LOCSITE BLOCKSIZE=6400
LOCSITE RECFM=FB
CD \M204V75
get M204V75.INT 'M204.V75.OBJ.DOWNLOAD' (replace
get M204V75_ZOS.MAC 'M204.V75.MAC.DOWNLOAD' (replace
QUIT
/*

SOUL $functions

2014-08-01T14:14:39Z

Mlarocca: /* Summary of standard functions */

==Overview==

Some operations are inefficient or impossible to code in a high-level programming language like User Language. To overcome this difficulty, User Language provides a variety of functions, which are assembly language subroutines you can call from within a User Language request.

The name of each User Language function begins with a dollar sign ($). For this reason, they are often referred to as $functions (dollar functions).

==Types of functions==

===Functions provided by User Language===

The functions provided by User Language are divided into two sets. One set is supplied as a standard feature and includes functions for data editing, data validation, and other purposes. The other set of functions (mathematical functions) is an optional feature of <var class="product">Model 204</var> and contains mathematical and scientific subroutines. 

In order to save machine resources, your site might have chosen to omit some of the standard functions as well as some or all of the mathematical functions. If a request calls a function that is not yet installed, compile-time errors result. 

===User-written functions===

In addition to the functions provided by User Language, some customer sites write their own functions based on their particular needs.

Before using any user-written functions, make sure that your site's FUNU module has been reassembled with the macro library supplied with the current release. Also, please be sure to carefully test your user-written functions before your system goes into production. 


Note:
It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified.


Customers are individually responsible for any functions they write. Rocket Software takes no responsibility for user-written functions or their documentation.

==Using functions==

You can use functions in several ways, including, as a term in:
<ul>
<li>An expression in a variable assignment statement, for example:</li>
</ul>
%X=$EDIT(2573,'99999')

<ul>
<li>The specifications in a PRINT statement</li>
</ul>

A PRINT statement can include a function call anywhere a field name can be used. For example:
PRINT $EDIT(2573,'99999')

<ul>
<li>An expression in a conditional statement, for example:</li>
</ul>
IF $EDIT(2573,'99999') EQ 02573 THEN...

<ul>
<li>An expression which serves as the argument to another function, for example:</li>
</ul>
%L=$LEN($EDIT(2573,'99999'))


The direct use of function calls in some statements, such as FIND, results in compilation errors. 

====Comparing successful and unsuccessful $function code====

If your request is coded as follows:
BEGIN
$EDIT(2573,'99999')
END


The following error is your result:
*** 1 M204.0229: INVALID STATEMENT $EDIT(2573,'99999')


However, if you code your request as follows, it works properly:
BEGIN
PRINT $EDIT(2573,'99999')
* Or *
* %X=$EDIT(2573,'99999') *
END


===Function return values===

Each function returns a single value to the calling request. For example, this function sets %A equal to the user's login account name:
%a = $account


This function causes the length of the current value of the FULLNAME field to be compared to 10:
IF $LEN(FULLNAME) GT 10 THEN
.
.
.


===Function arguments===

Some functions require one or more arguments which allow you to pass information to the subroutine. Some functions take no arguments. Arguments must be enclosed in parentheses and separated by commas. For example:
IF $READ('CONTINUE?') EQ 'YES' THEN
.
.
.
%X = $mod(COUNT IN CT, %BASE)


====Rules for function arguments====

Function arguments follow the normal rules for arithmetic expressions. Arguments can include other function calls and can perform any type of computation. See the section [[Using variables and values in computation#Expressions|Expressions]] for detailed information on expression syntax.

====Argument evaluation and conversion====

<var class="product">Model 204</var> evaluates each argument to a function as either a string or a number. When this data type conflicts with the data type required by the function, the following rules apply:
<ul>
<li>If an argument is expected to be numeric but is a string, <var class="product">Model 204</var> converts the string to a number according to the conversion rules described in the assignment statement discussion in [[Using variables and values in computation#Relationship between %variable assignment and declaration|Relationship between %variable assignment and declaration]] and [[Using variables and values in computation#Conversion|Conversion]]. </li>
</li>
<li>If an argument is expected to be a string but is numeric, <var class="product">Model 204</var> converts the number to a string. </li>
</li>
<li>If the original number contains decimal places, they are lost during the conversion.</li>
</li>
</ul>

==Sending email messages via User Language==

The User Language <var>$SNDMAIL</var> function simplifies sending an email message to issuing a single function call. You can easily send an email message using User Language without writing a procedure and without having an extensive knowledge of sockets or SMTP protocol.

====Internet Protocol (IP) addressing====

On z/OS systems only, Model 204 supports both IPv6 and IPv4 addressing.

====Limitations of the $SNDMAIL function under z/VM and z/VSE====

<var>$SNDMAIL</var> is supported with the following exceptions:
<ul>
<li>The <var>[[SMTPCADD parameter|SMTPCADD]]</var> and <var>[[SMTPSADD parameter|SMTPSADD]]</var> addresses must be supplied in internet protocol (IP) address protocol, not as domain names. You must supply IPv4 (dotted-decimal) internet addresses for the <var>SMTPCADD</var> and <var>SMTPSADD</var> parameters.</li>

<li>Likewise, if the client and server names are specified using the SMAILD image rather than using the CCAIN parameters <var>SMTPCADD</var> and <var>SMTPSADD</var>, the SERVERDDNAME and CLIENTDDNAME values must be supplied rather than the SERVERNAME and CLIENTNAME values. </li>

<li><var class="product">Model 204</var> does not support IPv6 addressing on z/VM or z/VSE systems.</li>
</ul>

===Enabling $SNDMAIL===

The first requirement for enabling the use of $SNDMAIL is to set the following four required CCAIN parameters:
<table>
<tr class="head">
<th>Parameter</th>
<th>SMTP purpose</th>
</tr>

<tr>
<td>SMTPCADD</td>
<td>SMTP client address. The client is the <var class="product">Model 204</var> address space.

On z/OS systems:

Set this parameter to one of the following: 
<ul>
<li>Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.</li>

<li>Dotted decimal address, such as 182.148.55.206.</li>

<li>IPV6 address, with up to 8 halfwords separated by colons, such as <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>

On z/VM or z/VSE systems:

Set this parameter to the dotted decimal address, such as <code>182.148.55.206</code>.
</td>
</tr>

<tr>
<td>SMTPCPRT</td>
<td>SMTP client port. The default value is 7700.</td>
</tr>

<tr>
<td>SMTPSADD</td>
<td>SMTP server address.

On z/OS systems:

Set this parameter to one of the following: 
<ul>
<li>Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.</li>

<li>Dotted decimal address, such as 182.148.55.206.</li>
<li>IPV6 address, with up to 8 halfwords separated by colons, such as <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>.</li>
</ul>

On z/VM or z/VSE systems:

Set this parameter to the dotted decimal address, such as <code>182.148.55.206</code>.
</td>
</tr>

<tr>
<td>SMTPSPRT</td>
<td>SMTP server port. The default value is 25, which is standard for most SMTP servers.</td>
</tr>
</table>


Your system manager can dynamically reset these parameters while the run is up. If you use the domain name for either <var>SMTPCADD</var> or <var>SMTPSADD</var>, you must have the following DD allocated to the Online:
//SYSTCPD DD DSN=TCPIP.PROFILE(TCPDATA),DISP=SHR


This is the TCP/IP profile data set required to support the resolution of IP domain names. 

On some SMTP servers, a valid email address is required for the <var class="term">%from</var> argument in the <var>$SNDMAIL</var> function. Most SMTP activity requires a valid SMTP server.

====$SNDMAIL and BATCH204====

<var>$SNDMAIL</var> is supported in BATCH204 if you relink BATCH204 with the following objects after V7R4 installation:
<ul>
<li>TC62 (or TC62DOS on z/VSE systems)</li>

<li>TCIU</li>

<li>TCSE</li>

<li>LU62</li>

<li>FUNR (or FUNRDOS on z/VSE systems)</li>
</ul>

After relinking you need to ensure that the following SMTP parameters are set in the ONLINE and BATCH204 CCAIN:
<ul>
<li>SMTPCADD</li>

<li>SMTPSADD</li>

<li>SMTPCPRT</li>

<li>SMTPSPRT</li>
</ul>

===$SNDMAIL===

The <var>$SNDMAIL</var> function sends an email message using the values you enter for the <var>$SNDMAIL</var> arguments. <var>$SNDMAIL</var> lets you send an email message with an optional attachment.

====Syntax====

The syntax for the <var>$SNDMAIL</var> function is:
$SNDMAIL(%SUBJ,%RCPT,%BODY,%FROM,%TO,%CC,%BCC,'EMAILD',%ATTACH,'C')


Where:
<ul>
<li>%SUBJ, which is optional, specifies a %variable or literal that contains the topic line.</li>

<li>%RCPT, which is optional, specifies a %variable or an image that contains the destination addresses, separated by commas.

If %RCPT is omitted, the destination addresses are taken from the %TO, %CC and %BCC arguments. 

If %RCPT is an image, the image name must be enclosed within quotation marks, for example 'DEPT-ADDR'.
</li>

<li>%BODY specifies a %variable or an image that contains the text of the message. If %BODY is an image, the image name must be enclosed in quotation marks, for example 'MSG-TXT'.</li>

<li>%FROM specifies a %variable that contains the FROM header field of up to 255 bytes. Although %FROM is optional, you should supply it, otherwise messages could fail when speaking to another SMTP server. If %FROM is omitted, the logged-on user ID is used. The email server may append the domain name to the given %FROM value.</li>

<li>%TO, %CC, and %BC, which are optional, specify a %variable that contains the TO, CC, and BCC header fields, respectively, of up to 255 bytes each.

Address must be enclosed in carets (<>), for example: M204-help <M204support@rocketsoftware.com>.
</li>

<li>'EMAILD', which is optional, specifies image data. The parameter provides the ability to override the values specified in CCAIN for SMTPSPRT, SMTPCPRT, SMTPSADD, and SMTPCADD. If 'EMAILD' is present, it must be in the following format, with the items in the following order:
* EMAILD - IMAGE WITH SMTP PARAMETERS
IMAGE EMAILD
SERVERPORT IS BINARY LEN 4 ;*SMTPSPRT
CLIENTPORT IS BINARY LEN 4 ;*SMTPCPRT
SERVERNAME IS STRING LEN 255 ;*SMTPSADD
CLIENTNAME IS STRING LEN 255 ;*SMTPCADD
SERVERDD IS STRING LEN 15 ;*Server dotted decimal address IPv4 format (optional)
CLIENTDD IS STRING LEN 15 ;*Client dotted decimal address IPv4 format (optional)
SERVERIPV6 IS STRING LEN 45 ;*Server dotted decimal address IPv6 format (optional)
CLIENTIPV6 IS STRING LEN 45 ;*Client dotted decimal address IPv6 format (optional)
END IMAGE


The SERVERIPV6 and CLIENTIPV6 fields are provided for the IPv6 colon-separated network addresses. These two fields are optional, to provide backward compatibility.
</li>

<li>%ATTACH, which is optional, specifies a %variable or literal with the name of an attachment that will be appended to the message. The attachment is assumed to be in the Universal Buffer at offset 0 (also called position 1). The length of the attachment is defined by the $Buffer_Used value. If the %ATTACH parameter is omitted, there is no attachment.

The function encodes the attachment using Base64 encoding, and may also translate it depending on the 10th argument.</li>

<li>'C', which is optional and is available as of Model 204 version 7.5, specifies that the object in the buffer will be translated to ASCII before being attached to the email. Alternatively, you can set this parameter to a percent variable with the value 'C'. For example, translation to ASCII could be useful if the $SNDMAIL attachment is a CLOB (CHARACTER-LARGE-OBJECT) such as a text document. If this argument is not specified with the value 'C' or 'c', the attachment is sent as binary, that is, without translation.

In this example, the CLOB.TXT attachment will be translated to ASCII before being attached to the email:
%RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,'CLOB.TXT','C')

</li>
</ul>

===Setting CCAIN parameters for $SNDMAIL===

You can set the following CCAIN parameters as default values for $SNDMAIL.
<ul>
<li>SMTPCADD is the default SMTP client address, the TCP/IP domain for the operating system, for the $SNDMAIL function. You can specify SMTPCADD as:
<ul>
<li>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format. </li>

<li>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</li>

<li>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as:
<code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>

You can override SMTPCADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.</li>

<li>SMTPCPRT is the default SMTP client port for the $SNDMAIL function. The value can be any value in the user range — normally above 4095 and up to 32767.

You can override SMTPCPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.
</li>

<li>SMTPSADD is the default SMTP server address for the $SNDMAIL function. You can specify SMTPSADD as:
<ul>
<li>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.</li>

<li>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</li>

<li>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as: <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>

You can override SMTPSADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.
</li>

<li>SMTPSPRT is the default SMTP server port for the $SNDMAIL function. SMTPSPRT is normally set to the standard SMTP value of 25. You can override SMTPSPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function.</li>
</ul>

===Examples of running $SNDMAIL===

====Example 1====
%FROM = 'me@mydomain.com'
%TO = 'My Friend <you@yourdomain.com>'
%BNAME = 'mypicture.jpg'

MODIFY BUFFER CLEAR

IN LOBSVR FOR 1 RECORD WHERE SVRKEY = %SVRKEY
%ISIZE = $LOBLEN(SVRLOB)
PRINT 'SIZE OF ' WITH %SVRKEY WITH ' IS ' WITH %ISIZE
BUFFER, 1, %ISIZE = SVRLOB, 1, %ISIZE
END FOR

PRINT 'BUFFER USED IS ' WITH $buffer_used
%SUBJECT = 'THIS SENDS A JPG FROM LOBSVR - ' WITH %SVRKEY
%BODY = 'THIS BODY CONTAINS ' WITH %SVRKEY
%RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,%BNAME)


In the previous example, a binary object (BLOB) is retrieved from the database and placed at position 1 in the buffer. The $SNDMAIL function sends this as a Base64-encoded attachment.
Note: The second parameter (the RCPTTO addresses) is omitted. The function creates this using the %TO parameter.

====Example 2====
%TO ='JANE <YOU@YOURCORP.COM>'
%BODY='See you at 9:30 AM tomorrow in the conference room'
%RC =$SNDMAIL(,,%BODY,,%TO)


====Example 3====

The EMAILD argument is used to override the default domain names and ports.
IMAGE EMAILD
SERVERPORT IS BINARY LEN 4 ;*SMTPSPRT
CLIENTPORT IS BINARY LEN 4 ;*SMTPCPRT
SERVERNAME IS STRING LEN 255 ;*SMTPSADD
CLIENTNAME IS STRING LEN 255 ;*SMTPCADD
END IMAGE

PREPARE IMAGE EMAILD
%EMAILD:SERVERNAME = 'MAIL.SERVER.COM'
%EMAILD:CLIENTNAME = 'MYMVSSYSTEM'
%EMAILD:SERVERPORT = 25
%EMAILD:CLIENTPORT = 5601
%FROM = 'ME@MYCORP.COM'
%TO = 'JANE <YOU@YOURCORP.COM>'
* RCPTTO is defined as an image here, allowing the string of
* addressees to be more than 255 bytes long.
IMAGE RCPTTO
EMRCPT1 IS STRING LEN 255
END IMAGE

PREPARE IMAGE RCPTTO
%RCPTTO:EMRCPT1 = 'YOU@YOURCORP.COM'
IMAGE BODY
BODY1 IS STRING LEN 240
BODY2 IS STRING LEN 240
END IMAGE

PREPARE IMAGE BODY
%S = 'EXAMPLE 1' /? SUBJECT LINE ?/
%BODY:BODY1 = 'THIS IS BODY1 WHICH IS PART OF AN IMAGE'
%BODY:BODY2 = 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG'
%RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')


====Example 4====

This example illustrates using EMAILD in an IPV6 environment. The lines that differ from Example 3 are shown in bold.
IMAGE EMAILD
SERVERPORT IS BINARY LEN 4 ;*SMTPSPRT
CLIENTPORT IS BINARY LEN 4 ;*SMTPCPRT
SERVERNAME IS STRING LEN 255 ;*SMTPSADD
CLIENTNAME IS STRING LEN 255 ;*SMTPCADD
SERVERDD IS STRING LEN 15 ;*Server dotted decimal address IPv4 format (optional)
CLIENTDD IS STRING LEN 15 ;*Client dotted decimal address IPv4 format (optional)
SERVERIPV6 IS STRING LEN 45 ;*Server dotted decimal address IPv6 format (optional)
CLIENTIPV6 IS STRING LEN 45 ;*Client dotted decimal address IPv6 format (optional)
END IMAGE

PREPARE IMAGE EMAILD
%EMAILD:SERVERPORT = 25
%EMAILD:CLIENTPORT = 5601
%EMAILD:SERVERNAME = 'MAIL.SERVER.COM'
%EMAILD:CLIENTIPV6 = 'C0:12:46:F0::01'

%FROM = 'ME@MYCORP.COM'
%TO = 'JANE <YOU@YOURCORP.COM>'
* RCPTTO is defined as an image here, allowing the string of
* addressees to be more than 255 bytes long.
IMAGE RCPTTO
EMRCPT1 IS STRING LEN 255
END IMAGE

PREPARE IMAGE RCPTTO
%RCPTTO:EMRCPT1 = 'YOU@YOURCORP.COM'
IMAGE BODY
BODY1 IS STRING LEN 240
BODY2 IS STRING LEN 240
END IMAGE

PREPARE IMAGE BODY
%S = 'EXAMPLE 1' /? SUBJECT LINE ?/
%BODY:BODY1 = 'THIS IS BODY1 WHICH IS PART OF AN IMAGE'
%BODY:BODY2 = 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG'
%RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')


===ASCII translation===

All text, except an optional binary attachment, is translated from EBCDIC to ASCII before sending.

===Line ends===

Text that is part of the header and body can include EBCDIC CRLF strings (X'0D25') that are translated to ASCII along with the rest of the text.

===Reserved names===

The $SNDMAIL function uses Interface names CCAEM000 through CCAEM999. The user does not specify these names — the link name is generated by the function.

===Socket limits===

Up to 31 sockets are available on each link. If no more sockets are available on a particular link (CCAEM000, for example), the next link is tried. Thus, a maximum of 31,000 simultaneous email threads is theoretically possible.

===Size of email message===

The FROM, TO, CC, BCC, RCPTTO addresses, and body length, excluding the optional binary attachment, must total less than 27454 bytes.

===Return code===

The $SNDMAIL function returns a fixed full word binary return code. See [[#Handling error condition return codes|Handling error condition return codes]] for possible values.

===RCPTTO parameter===

If the $SNDMAIL EMAILD argument is omitted, the RCPTTO addresses are constructed from the addresses contained in the %TO, %CC, and %BCC arguments.

The sum of the lengths of the RCPTTO address string, (If supplied) and the body text cannot exceed 30,700.

===Using quotation marks===

You must enclose the names of images within quotation marks, for example: 'BODY'. However, do not enclose the percent variable values within quotation marks, for example: %SUBJECT, not '%SUBJECT'.

===Server and client names in the EMAILD parameters===

In the EMAILD image, on a z/OS system, you can specify either or both the server and client names as domain names, for example: <var>SMTPSERVER.YOURDOMAIN.COM</var> or as an Internet Protocol (IP) address. If you specify the domain name, a TCP/IP call looks up the IP address. 
<ul>
<li>If one field is present, all fields must be present, even if the optional fields are left blank. </li>
</li>
<li>If a name or port field is absent, it is taken from the CCAIN parameters SMTPSADD, SMTPCADD, SMTPSPRT, and SMTPCPRT. </li>
</li>
</ul>

The two port parameters have defaults: the SMTPSPRT default is 25; the SMTPCPRT default is 7700.

The two address parameters, SMTPSADD and SMTPCADD, can be specified either as domain names of up to 255 bytes or as IP addresses. If the address begins with an alphabetic character (A to Z), it is automatically evaluated as a domain name. 

The four CCAIN default parameters SMTPSADD, SMTPCADD, SMTPSPRT, and SMTPCPRT can be examined using VIEW and changed using RESET.

===References===

For more information about the standards used in this function, please refer to these Internet Request for Comments documents:
<ul>
<li>RFC822, Standard for the format of ARPA Internet Text Messages</li>
</li>
<li>RFC2821, Simple Mail Transfer Protocol</li>
</li>
<li>RFC3548, The Base16, Base32, and Base64 Data Encoding</li>
</li>
</ul>

===Error codes for $SNDMAIL===

The $SNDMAIL function issues a return code. An error in $SNDMAIL gives a return code of -1, and it is $StatusD that contains the error code. 

The negative error codes starting with -999 are listed in [[#Handling error condition return codes|Handling error condition return codes]]. 

It is also possible that $SNDMAIL will return a positive error code, which comes from TCP/IP and is documented in the IBM TCP/IP documentation, TCP/IP V3.2 for MVS: API Reference, Appendix D. For example, an error code of 60 means that the connection attempt timed out. $SOCKET calls give the same errors.

However, in the case of a non-zero (error) return code, the following message is issued to the user:
M204.2799: $SNDMAIL ERROR errortext


When an attempt is made to set or reset the SMTPCADD or SMTPSADD parameters and the address translation fails, <var class="product">Model 204</var> issues the following messages:
RESET SMTPCADD CCAGGGG

*** M204.2834: ADDRESS LOOKUP FAILED FOR CCAGGGG
*** 1 M204.1123: PARAMETER SMTPCADD NOT RESET


===Handling error condition return codes===

[[#Handling error condition return codes|Handling error condition return codes]] lists the possible $SOCKET return codes.

<table>
<caption>$Socket return codes</caption>
<tr class="head">
<th>SMTP
Error text </th>
<th>Numeric
value </th>
<th>
Meaning</th>
</tr>
<tr>
<td>ERBADARG </td>
<td>-999 </td>
<td>BAD ARGUMENT</td>
</tr>
<tr>
<td>ERNOTOPN </td>
<td>-998 </td>
<td>NOT OPEN</td>
</tr>
<tr>
<td>ERNOSTOR </td>
<td>-997 </td>
<td>NO STORAGE</td>
</tr>
<tr>
<td>ERIMAGER </td>
<td>-996 </td>
<td>IMAGE FAILURE</td>
</tr>
<tr>
<td>ERBADLNK </td>
<td>-995 </td>
<td>BAD LINK</td>
</tr>
<tr>
<td>ERNOTREL </td>
<td>-994 </td>
<td>SOCD NOT RELEASED</td>
</tr>
<tr>
<td>ERPHYERR </td>
<td>-993 </td>
<td>LINK DEAD</td>
</tr>
<tr>
<td>ERNOLINK </td>
<td>-992 </td>
<td>LINK UNKNOWN</td>
</tr>
<tr>
<td>ERTRUNC </td>
<td>-991 </td>
<td>VARIABLE TRUNCATION (READ CALL)</td>
</tr>
<tr>
<td>ERNOSOCK </td>
<td>-990 </td>
<td>SOCKET NOT FOUND</td>
</tr>
<tr>
<td>ERTRUNC2 </td>
<td>-989 </td>
<td>TRUNCATION ERROR ON IMAGE</td>
</tr>
<tr>
<td>EROPSYS </td>
<td>-988 </td>
<td>FUNCTION UNSUPPORTED ON THIS OPSYS</td>
</tr>
<tr>
<td>  </td>
<td>-987 </td>
<td>Not used</td>
</tr>
<tr>
<td>ERNOSRCD </td>
<td>-986 </td>
<td>NO SRCD</td>
</tr>
<tr>
<td>ERFDSLIM </td>
<td>-985 </td>
<td>TOO MANY SOCKETS</td>
</tr>
<tr>
<td>ERBADUBN </td>
<td>-984 </td>
<td>UNIVERSAL BUFFER NOT THERE</td>
</tr>
<tr>
<td>ERBADUBL </td>
<td>-983 </td>
<td>UNIVERSAL BUFFER LENGTH ERROR</td>
</tr>
<tr>
<td>ERBADUBA </td>
<td>-982 </td>
<td>UNIVERSAL BUFFER ALLOCATION ERROR</td>
</tr>
<tr>
<td>EREMREAD </td>
<td>-981 </td>
<td>ERROR WITH EMAIL SERVER READ</td>
</tr>
<tr>
<td>EREMWRIT </td>
<td>-980 </td>
<td>ERROR WITH EMAIL SERVER WRITE</td>
</tr>
<tr>
<td>ERGHBERR </td>
<td>-979 </td>
<td>SKIP=0 ERROR ON GETHOST CALL</td>
</tr>
<tr>
<td>ERGHERR1 </td>
<td>-978 </td>
<td>T1 LT 0 ERROR ON GETHOST CALL</td>
</tr>
<tr>
<td>ERGHERR2 </td>
<td>-977 </td>
<td>NO ADDRESSES RETURNED</td>
</tr>
</table>



When an error message (with code 5xx) is returned from the SMTP server, the following error message is displayed:
M204.2796: 'SMTP %C'



where %C is the error message returned by SMTP.


For the other error codes above, the following error message is returned, in addition to $StatusD being set.
M204.2799: '$SNDMAIL ERROR %C'


where %C is listed in the following table:
<table>
<caption>Error text message possibilities for M204.2799</caption>
<tr class="head">
<th>%C in message 2799 </th>
<th>$StatusD code(s)</th>
</tr>
<tr>
<td>IN PARAMETER </td>
<td>999</td>
</tr>
<tr>
<td>- SOCKET NOT FOUND </td>
<td>990</td>
</tr>
<tr>
<td>- FUNCTION NOT SUPPORTED ON THIS SYSTEM </td>
<td>998</td>
</tr>
<tr>
<td>- NO SRCD </td>
<td>986</td>
</tr>
<tr>
<td>- TOO MANY SOCKETS </td>
<td>985</td>
</tr>
<tr>
<td>WITH UNIVERSAL BUFFER </td>
<td>984, 983, 982</td>
</tr>
<tr>
<td>Reading from SMTP server </td>
<td>981</td>
</tr>
<tr>
<td>Writing to SMTP server </td>
<td>980</td>
</tr>
<tr>
<td>Using GETHOSTBYNAME lookup </td>
<td>979, 978, 977</td>
</tr>
<tr>
<td>GETTING STORAGE </td>
<td>997</td>
</tr>
<tr>
<td>IN IMAGE PROCESSING </td>
<td>996</td>
</tr>
<tr>
<td>WITH TCP LINK </td>
<td>995, 998, 993, 992</td>
</tr>
<tr>
<td>- SOCD NOT RELEASED </td>
<td>994</td>
</tr>
<tr>
<td>READING DATA - TRUNCATION </td>
<td>991</td>
</tr>
</table>

==Summary of standard functions==


The following table lists the standard <var class="product">SOUL</var> functions in alphabetical order. 



See also:
<ul>
<li>[[SOUL $functions#Using_functions|Using functions]] reviews coding in <var class="product">SOUL</var> with $functions.
<li>[[List of $functions]] contains the many additional $functions available as of version 7.5 of <var class="product">Model 204</var>.
</ul>
<table>
<tr class="head">
<th>Function</th>
<th>Returns...</th>
</tr>
<tr>
<td>[[$Account]]</td>
<td>Account under which the user is logged in.</td>
</tr>
<tr>
<td>[[$Acct]]</td>
<td>User ID under which the user is logged in.</td>
</tr>
<tr>
<td>[[$Alpha]]</td>
<td>Whether a string is composed of only the letters A through Z.</td>
</tr>
<tr>
<td>[[$AlphNum]]</td>
<td>Whether a string is composed of only the letters A through Z and digits 0 through 9.</td>
</tr>
<tr>
<td>[[$ArrSize]]</td>
<td>Number of elements in a particular dimension of an array.</td>
</tr>
<tr>
<td>[[$Ascii]]</td>
<td>Input string, converted from EBCDIC to ASCII.</td>
</tr>
<tr>
<td>[[$Binary]]</td>
<td>A number converted into fixed-point binary.</td>
</tr>
<tr>
<td>[[$BldProc]]</td>
<td>Enables a request to build a temporary procedure.</td>
</tr>
<tr>
<td>[[$Buffer_Position]]</td>
<td>Current Universal Buffer position.</td>
</tr>
<tr>
<td>[[$Buffer_Size]]</td>
<td>Size of user's Universal Buffer.</td>
</tr>
<tr>
<td>[[$Buffer_Used]]</td>
<td>Amount of data currently in Universal Buffer</td>
</tr>
<tr>
<td>[[$CenqCt]]</td>
<td>Number of unused entries within the resource enqueuing table.</td>
</tr>
<tr>
<td>[[$ChkMod]]</td>
<td>Whether the terminal operator entered data in any full-screen input field.</td>
</tr>
<tr>
<td>[[$ChkTag]]</td>
<td>Whether any erroneous full-screen input has been entered by the end user.</td>
</tr>
<tr>
<td>[[$ChkPat]]</td>
<td>Syntax of a pattern.</td>
</tr>
<tr>
<td>[[$Code]]</td>
<td>Encoding facility.</td>
</tr>
<tr>
<td>[[$Curfile]]</td>
<td>Name of the file from which the current record has been selected.</td>
</tr>
<tr>
<td>[[$Currec]]</td>
<td>Integer equal to the internal number of the current record.</td>
</tr>
<tr>
<td>[[$C2X]]</td>
<td>A translation of each byte within a character string to its two-byte
hexadecimal representation.</td>
</tr>
<tr>
<td>[[$Date]]</td>
<td>Current date in yy-mm-dd format.</td>
</tr>
<tr>
<td>[[$DateChg]]</td>
<td>Specified number of days, added to or subtracted from a given date.</td>
</tr>
<tr>
<td>[[$DateChk]]</td>
<td>Whether a given date is valid.</td>
</tr>
<tr>
<td>[[$DateCnv]]</td>
<td>Date converted to a format specified by the user.</td>
</tr>
<tr>
<td>[[$DateDif]]</td>
<td>Difference in days between two dates.</td>
</tr>
<tr>
<td>[[$DateP]]</td>
<td>Current date in "dd mon yy" format.</td>
</tr>
<tr>
<td>[[$DayI]]</td>
<td>Number reflecting current day of the week.</td>
</tr>
<tr>
<td>[[$Deblank]]</td>
<td>Substring of a string, with leading and trailing blanks removed.</td>
</tr>
<tr>
<td>[[$Decode]]</td>
<td>Decoding facility.</td>
</tr>
<tr>
<td>[[$Dscr]]</td>
<td>Decoding facility.</td>
</tr>
<tr>
<td>[[$Dsn]]</td>
<td>Data set name when you specify a file's DD name and the ordinal number.</td>
</tr>
<tr>
<td>[[$DsnNum]]</td>
<td>Total number of data sets defined for a file when you specify the file's DD name.</td>
</tr>
<tr>
<td>[[$EcfStat]]</td>
<td>Returns the detailed completion code from the previous EXTERNAL statement.</td>
</tr>
<tr>
<td>[[$Edit]]</td>
<td>Edited numeric and alphanumeric text</td>
</tr>
<tr>
<td>[[$Eformat]]</td>
<td>Exponent notations from converted numeric values</td>
</tr>
<tr>
<td>[[$Encrypt]]</td>
<td>A one-way encryption of a character string.</td>
</tr>
<tr>
<td>[[$Enter]]</td>
<td>Efficient terminal dialogue with users of data entry applications.</td>
</tr>
<tr>
<td>[[$ErrClr]]</td>
<td>Clears the error message text returned by the $Errmsg and $Fsterr functions.</td>
</tr>
<tr>
<tr>
<td>[[$Errmsg]]</td>
<td>Prefix and text of the last counting error or request cancellation message received.</td>
</tr>
<tr>
<td>[[$FDef]]</td>
<td>String that describes the attributes of a field in a <var class="product">Model 204</var> file.</td>
</tr>
<tr>
<td>[[$FieldgroupId]]</td>
<td>The ID of the current field group. (Available as of Model 204 version 7.5.)</td>
</tr>
<tr>
<td>[[$FieldgroupOccurrence]]</td>
<td>The current occurrence number of the field group. (Available as of Model 204 version 7.5.)</td>
</tr>
<tr>
<td>[[$FldLen]]</td>
<td>Length of a field.</td>
</tr>
<tr>
<td>[[$Float]]</td>
<td>Floating-point to a 4-byte string without conversion (4-byte floating point number to a 4-byte string).</td>
</tr>
<tr>
<td>[[$FloatD]]</td>
<td>Floating-point to a 4-byte string without conversion (8-byte floating point number to an 8-byte string). </td>
</tr>
<tr>
<td>[[$FlsAcc]]</td>
<td>User's access rights to a particular field.</td>
</tr>
<tr>
<td>[[$FlsChk]]</td>
<td>Whether a given set of field level security accesses is valid for a field.</td>
</tr>
<tr>
<td>[[$Fsterr]]</td>
<td>Variable-length string containing the prefix and the first counting error message or request cancellation message received by the user since the last time the count was reset to zero.</td>
</tr>
<tr>
<td>[[$Getg]]</td>
<td>Information stored by a $SETG function.</td>
</tr>
<tr>
<td>[[$GetL]]</td>
<td>Line number of the current line on the page on the user's terminal or on the output data set specified by a USE command.</td>
</tr>
<tr>
<td>[[$GetP]]</td>
<td>Page number currently on the user's terminal or on the output data set specified by a USE command.</td>
</tr>
<tr>
<td>[[$GrmLoc]]</td>
<td>Location of a missing member.</td>
</tr>
<tr>
<td>[[$GrmName]]</td>
<td>File name of a missing member.</td>
</tr>
<tr>
<td>[[$GrnLeft]]</td>
<td>Number of optional files that may fail before MAXFAIL is exceeded.</td>
</tr>
<tr>
<td>[[$GrnMiss]]</td>
<td>Number of missing members.</td>
</tr>
<tr>
<td>[[$HPage]]</td>
<td>String of special characters whose length is equal to the value specified as the $HPage argument.</td>
</tr>
<tr>
<td>[[$Hsh]]</td>
<td>A hash value from a converted string value. A hash value is a distinct numeric representation of a given string value.</td>
</tr>
<tr>
<td>[[$Incrg]]</td>
<td>Performs simple arithmetic on global variables.</td>
</tr>
<tr>
<td>[[$Index]]</td>
<td>After comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $SCAN.</td>
</tr>
<tr>
<td>[[$Itsopen]]</td>
<td>Whether or not a file is open.</td>
</tr>
<tr>
<td>[[$Itsremote]]</td>
<td>Whether the current file or group is remote or scattered.</td>
</tr>
<tr>
<td>[[$Jobcode]]</td>
<td>Allows a request that is part of one step of a <var class="product">Model 204</var> batch run to communicate with a subsequent step.</td>
</tr>
<tr>
<td>[[$LangSpc]]</td>
<td>String containing the binary value of a character in a specified language.</td>
</tr>
<tr>
<td>[[$LangSrt]]</td>
<td>A binary string translated to sort according to the NLSORT macro for the specified language.</td>
</tr>
<tr>
<td>[[$LangUst]]</td>
<td>Previously $LangSrt'ed string translated back to its original form.</td>
</tr>
<tr>
<td>[[$Len]]</td>
<td>Length of a value in a field.</td>
</tr>
<tr>
<td>[[$Lowcase]]</td>
<td>A lower case string translated from an uppercase or mixed case string</td>
</tr>
<tr>
<td>[[$LstFld]]</td>
<td>Field names in a file, along with their field descriptions, into an image.</td>
</tr>
<tr>
<td>[[$LstProc]]</td>
<td>Information that is stored for a procedure.</td>
</tr>
<tr>
<td>[[$MisGrup]]</td>
<td>Group name if the error occurred in group context, null if in file context.</td>
</tr>
<tr>
<td>[[$MisName]]</td>
<td>File name of a missing member or file.</td>
</tr>
<tr>
<td>[[$MisNum]]</td>
<td>Number of files that failed in a group.</td>
</tr>
<tr>
<td>[[$MisLoc]]</td>
<td>Location of a missing member or file.</td>
</tr>
<tr>
<td>[[$MisStmt]]</td>
<td>Statement that caused the ON unit to be entered.</td>
</tr>
<tr>
<td>[[$Mod]]</td>
<td>Remainder that results when one argument is divided by the another argument.</td>
</tr>
<tr>
<td>[[$Occurs]]</td>
<td>Whether a field has the OCCURS attribute.</td>
</tr>
<tr>
<td>[[$Oneof]]</td>
<td>Table lookup that can replace a series of IF conditions.</td>
</tr>
<tr>
<td>[[$Pack]]</td>
<td>Packed decimal representation of a string.</td>
</tr>
<tr>
<td>[[$Pad]]</td>
<td>Designated character padded to the left.</td>
</tr>
<tr>
<td>[[$PadR]]</td>
<td>Designated character padded to the right</td>
</tr>
<tr>
<td>[[$RdProc]]</td>
<td>Lines of a User Language procedure, retrieved in sequential order, that is stored in a <var class="product">Model 204</var> file.</td>
</tr>
<tr>
<td>[[$Read]]</td>
<td>An echo of the data a user enters as a request is evaluated</td>
</tr>
<tr>
<td>[[$ReadInv]]</td>
<td>Performs the same function as $READ, except that input from the terminal is not echoed.</td>
</tr>
<tr>
<td>[[$ReadLc]]</td>
<td>An echo of the data a user enters as a request is evaluated, except that case translation is deactivated, regardless of the current *UPPER or *LOWER setting.</td>
</tr>
<tr>
<td>[[$Remote]]</td>
<td>VTAMNAME value of the originating <var class="product">Model 204</var> region when using SNA Communications Server (formerly VTAM) TRANSFER to transfer between <var class="product">Model 204</var> regions.</td>
</tr>
<tr>
<td>[[$Reverse]]</td>
<td>Reversed order of a string.</td>
</tr>
<tr>
<td>[[$RlcFile]]</td>
<td>Name of the file in which the last record locking conflict occurred.</td>
</tr>
<tr>
<td>[[$RlcRec]]</td>
<td>Internal record number for which the last record locking conflict occurred.</td>
</tr>
<tr>
<td>[[$RlcUid]]</td>
<td>ID of the user who caused an ON FIND CONFICT or ON RECORD LOCKING CONFLICT. If the conflicting user is on a remote node, $RLCUID also returns the name of the node.</td>
</tr>
<tr>
<td>[[$RlcUsr]]</td>
<td>User number of the user with which the request conflicted when the last record locking conflict occurred.</td>
</tr>
<tr>
<td>[[$Round]]</td>
<td>Number, rounded to a specified number of decimal places.</td>
</tr>
<tr>
<td>[[$Scan]]</td>
<td>After comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $INDEX.</td>
</tr>
<tr>
<td>[[$Sclass]]</td>
<td>Current user's subsystem user class.</td>
</tr>
<tr>
<td>[[$Setg]]</td>
<td>A created or changed entry in the global variable section of GTBL.</td>
</tr>
<tr>
<td>[[$SetL]]</td>
<td>Sets the current line counter for the output device currently in effect.</td>
</tr>
<tr>
<td>[[$SetP]]</td>
<td>Sets the current page number for the output device currently in effect.</td>
</tr>
<tr>
<td>[[$Slstats]]</td>
<td>Resets the recording of since-last statistics anywhere within a request.</td>
</tr>
<tr>
<td>[[$Sndx]]</td>
<td>SOUNDEX code of an argument.</td>
</tr>
<tr>
<td>[[$Square]]</td>
<td>A number multiplied by itself.</td>
</tr>
<tr>
<td>[[$Stat]]</td>
<td>Current value of any user statistic.</td>
</tr>
<tr>
<td>[[$Status]]</td>
<td>The success or failure of the last executed external I/O or program communication statement.</td>
</tr>
<tr>
<td>[[$StatusD]]</td>
<td>More detailed description of a condition returned by $STATUS.</td>
</tr>
<tr>
<td>[[$Strip]]</td>
<td>A number with suppressed leading zeros.</td>
</tr>
<tr>
<td>[[$Substr]]</td>
<td>Substring of a string.</td>
</tr>
<tr>
<td>[[$Subsys]]</td>
<td>Status of an APSY subsystem.</td>
</tr>
<tr>
<td>[[$Time]]</td>
<td>Current time in hh:mm:ss format.</td>
</tr>
<tr>
<td>[[$Unbin]]</td>
<td>Value converted from binary to string representation.</td>
</tr>
<tr>
<td>[[$Unblank]]</td>
<td>Contents of an argument, removing leading and trailing blanks, and compressing multiple embedded blanks to one blank character.</td>
</tr>
<tr>
<td>[[$Unfloat]]</td>
<td>Character string that represents a numeric counted string of 4 or 8 bytes, which contains a floating point.</td>
</tr>
<tr>
<td>[[$Unpack]]</td>
<td>Unpacked decimal data </td>
</tr>
<tr>
<td>[[$UnqRec]]</td>
<td>

In the case of a uniqueness violation, returns the file-relative record number of the record that already contains the field name = value pair

If no uniqueness violation occurred. returns -1.
</td>
</tr>
<tr>
<td>[[$Upcase]]</td>
<td>An uppercase string converted from a lower or mixed case string.</td>
</tr>
<tr>
<td>[[$Update]]</td>
<td>Name of the group update file or the current file.</td>
</tr>
<tr>
<td>[[$UpdFld]]</td>
<td>Name of the field for which a field level constraint violation has occurred, or a blank if no violation occurred.</td>
</tr>
<tr>
<td>[[$UpdFile]]</td>
<td>Name of the file in which a field level constraint violation has occurred, or a blank if no violation occurred.</td>
</tr>
<tr>
<td>[[$UpdLoc]]</td>
<td>Location name (node name) of the current update unit (Parallel Query Option/204 only).</td>
</tr>
<tr>
<td>[[$UpdOval]]</td>
<td>Value of the original field occurrence causing a constraint violation, when invoked from an ON FCC unit following the detection of an AT-MOST-ONE field-level constraint conflict. </td>
</tr>
<tr>
<td>[[$UpdRec]]</td>
<td>File-relative record number of the record whose update caused a field level constraint violation, or -1 if no violation occurred.</td>
</tr>
<tr>
<td>[[$UpdStat]]</td>
<td>Numeric value denoting the type of field level constraint violation that has occurred, or 0 if no violation occurred.</td>
</tr>
<tr>
<td>[[$UpdStmt]]</td>
<td>Type of User Language updating statement causing a field level constraint violation, or a blank if no violation occurred.</td>
</tr>
<tr>
<td>[[$UpdVal]]</td>
<td>Field value causing a field level constraint violation, or a blank if no violation occurred.</td>
</tr>
<tr>
<td>[[$User]]</td>
<td>User's user number.</td>
</tr>
<tr>
<td>[[$Userid]]</td>
<td>User ID under which the user is logged in.</td>
</tr>
<tr>
<td>[[$UsrPriv]]</td>
<td>Whether a user ID has been granted specific <var class="product">Model 204</var> privileges.</td>
</tr>
<tr>
<td>[[$Verify]]</td>
<td>Whether every character in one string is present in a second string.</td>
</tr>
<tr>
<td>[[$View]]</td>
<td>Value of a parameter.</td>
</tr>
<tr>
<td>[[$Vnum]]</td>
<td>Whether a given argument is in a valid format for a SORT BY VALUE NUMERICAL statement or for any type of mathematical operation.</td>
</tr>
<tr>
<td>[[$Word]]</td>
<td>P word in a specified string, delimited by a blank or optionally specified character.</td>
</tr>
<tr>
<td>[[$Words]]</td>
<td>Number of words in a specified string, delimited by a blank or optionally specified character.</td>
</tr>
<tr>
<td>[[$X2C]]</td>
<td>One-byte EBCDIC characters translated from a string of 2-byte hexadecimal character.</td>
</tr>
</table>

[[Category:SOUL]]

$Fsterr

2014-08-01T14:01:01Z

Mlarocca:

The <var>$FstErr</var> function returns a string containing the prefix and text of the first counting error message or request cancellation message received by the user. 
A null value is returned if no counting error or request cancellation message has been received since:
<ul>
<li>The beginning of the user's <var class="product">Model 204</var> session</li>
</li>
<li>The last call to the <var>[[$ErrClr]]</var> function</li>
</li>
<li>Processing a <var class="product">SOUL</var> <var>Open</var> statement</li>
</li>
</ul>
Refer to the Rocket <var class="product">Model 204</var> Messages Manual for more information on counting messages. This function takes no arguments. 
<var>$FstErr</var> is not available for Host Language Interface applications. 
The <var>$FstErr</var> function requires an additional 88 bytes in the fixed portion of the server.
Example
A sample <var>$FstErr</var> function with an <var>On Error</var> unit follows. To learn about <var>On Error</var> units, see [[Subroutines#ON units|ON units]].
begin
fsterr.proc: on error
print 'The request is ending'
print 'The first error message was:'
print $fstErr
end on

get.recs: find all records for which
agent = blake
end find
for each record in get.recs
.
.
end for
end

The maximum length of the returned string is determined by the setting of the <var>[[ERRMSGL parameter|ERRMSGL]]</var> parameter. That parameter defaults to 80 which means a maximum of 79 characters are returned, but <var>ERRMSGL</var> can be set as high as 256 which means up to 255 characters would be returned.
==See also==
<ul>
<li>the [[IFGERR IFAM function]]
<li><var>[[$Errmsg]]</var>, which returns the most recent counting error message.
<li>The <var>[[ERRMSGL parameter|ERRMSGL]]</var> parameter, which determines the length of errors returned by <var>$Errmsg</var> and <var>$Fsterr</var>.
</ul>
[[Category:SOUL $functions]]

$ErrMsg

2014-08-01T13:59:34Z

Mlarocca:

The <var>$ErrMsg</var> function returns a string containing the prefix and text of the last counting error message or request cancellation message received by the user. 
A null value is returned if no counting error or request cancellation message has been received since:
<ul>
<li>The beginning of the user's <var class="product">Model 204</var> session</li>
</li>
<li>The last call to the <var>[[$ErrClr]]</var> function.</li>
</li>
<li>Processing a <var class="product">SOUL</var> <var>Open</var> statement</li>
</li>
</ul>
Refer to the Rocket <var class="product">Model 204</var> Messages Manual for more information on counting messages. This function takes no arguments. 
Example
A sample <var>$ErrMsg</var> function with an <var>On Error</var> unit follows. To learn about <var>On Error</var> units, see [[Subroutines#ON units|ON units]].
begin
error.proc: on error
print 'The request is ending'
print 'The last error message received was:'
print $errMsg
end on
get.recs: find all records for which
agent = casola
end find
for each record in get.recs
.
.
.
end for
end

The maximum length of the returned string is determined by the setting of the <var>[[ERRMSGL parameter|ERRMSGL]]</var> parameter. That parameter defaults to 80 which means a maximum of 79 characters are returned, but <var>ERRMSGL</var> can be set as high as 256 which means up to 255 characters would be returned.
==See also==
<ul>
<li>the [[IFGERR IFAM function]]
<li><var>[[$Fsterr]]</var>, which returns the first counting error message.
<li>The <var>[[ERRMSGL parameter|ERRMSGL]]</var> parameter, which determines the length of errors returned by <var>$Errmsg</var> and <var>$FstErr</var>.
</ul>
[[Category:SOUL $functions]]

Images

2014-08-01T13:56:23Z

Mlarocca:

<div class="toclimit-3">

==Overview==

This article describes a feature of User Language, called images, that allows:
<ul>
<li>A request to read and process non-<var class="product">Model 204</var> files, that is, sequential and VSAM files, and terminal input, such as a Host Language IFDIAL thread</li>
<li>A request to write to sequential files and terminals </li>
<li>The creation of formatted blocks of storage that can be used to build records or to process data that is not in a format automatically recognized by <var class="product">Model 204</var> </li>
</ul>

===Terminology===

Before reviewing the capabilities and requirements of images, you should be familiar with the following terms that are used throughout this discussion:
<table>
<tr class="head">
<th>Term </th>
<th>Definition</th>
</tr>
<tr>
<td>Array</td>
<td>Ordered arrangement of data elements. Multiple occurrences of an item or a group of items. </td>
</tr>
<tr>
<td>Block </td>
<td>A contiguous storage area into which a record is read or from which a record is written. Also, block can be a contiguous storage area in which data can be manipulated.</td>
</tr>
<tr>
<td>Image</td>
<td>A description of the format of data in a block.</td>
</tr>
<tr>
<td>Item</td>
<td>An individual string or number in an image. </td>
</tr>
</table>

===Global images===

Global images provide a means for passing image data from one request to another, and for efficiently managing more than one image in one request.

Although there are some differences in the way you use the DECLARE IMAGE statement, you generally define and use global images the same as you do non-global images. See [[Global features#Global images and screens|Global images and screens]] where a discussion of global screens, menus, and images begins.

==Using images==

See [[Global features#Global images and screens|Global images and screens]] for a discussion of global images.

===Reading external files or terminal input===

====Input sources====

The image feature lets a request read and process records from the following sources of input: 
<table>
<tr class="head">
<th>Input sources </th>
<th>Description</th>
</tr>
<tr>
<td>Sequential or
VSAM files </td>
<td>

Any number of sequential or VSAM files can be read and processed. If VSAM files are used, the files must be keyed sequential (KSDS). KSDS files can be accessed using an alternate index path. 

For more information on the types of files and keys that can be used,
see the <var>[[DEFINE DATASET command|DEFINE DATASET]]</var> command. 
</td>
</tr>
<tr>
<td>Terminal </td>
<td>

Terminal input can be read and processed. A terminal can consist of the physical device on which the request is run, or a User Language connection that has been made from a Host Language application program by using the IFDIAL function. 

For more information on IFDIAL, refer to the <var class="book">Rocket Model 204 Host Language Interface Reference Manual</var>. 
</td>
</tr>
</table>

====External records====

Records read from sequential or VSAM files and data passed from the terminal are referred to as external records in this discussion to distinguish them from <var class="product">Model 204</var> records. 

The format of the external record is described by a structure called an image. Multiple descriptions of a record are allowed, as discussed later in this article. User Language statements can refer to each item described in the image definition.

====Reading records into an image====

User Language statements, which are documented beginning with [[#Processing images|Processing images]], let the request open the file, read records into the image, and close the file. 

For keyed VSAM files, the request can position the file to read sequentially starting with any record in the file.

===Writing to sequential files or a terminal===

The image feature lets a request write records to any number of sequential files or to a terminal. This capability allows multiple output files and reports to be written by a single pass of the database. 
Note: Only printable characters of a record are displayed on a physical terminal device. Therefore, images used to write to a physical terminal device should be defined with string items only.

===Defining storage blocks===

You can define the data in a block of storage as an image. 

The image definition can consist of item definitions as well as definitions of areas in the block that do not need to be accessed. Items in the image can be filled with constants, %variables, fields from a <var class="product">Model 204</var> record, screen items, items from the current block or another block, and expressions. 

Each item defined in the image can be referred to by User Language statements.

====Possible uses====

In addition to sequential file, VSAM file, or terminal I/O processing, the ability to manipulate a block of storage has several other uses. For example, you can:
<ul>
<li>Construct print lines by filling in items in one or more images at various points in a request. Once the print lines are complete, you can print the lines.</li>

<li>Copy into an image fields in <var class="product">Model 204</var> records that have formats not directly recognized by User Language; the individual parts of the field then can be accessed as image items. For example, if the user wants to use packed decimal data that is stored in a <var class="product">Model 204</var> field, the data can be moved into an image item and used directly. This eliminates the need to use the $PACK function to convert the data prior to its use.</li>

<li>Store blocks of data of up to 255 bytes as a single field, copied to an image, and the parts of the block can be referred to separately. Data that is stored as a single, large field, for example, a line of text, can be moved into an image that defines the data as one or more items. The items then can be referred to separately. </li>

<li>Pass data from one request to another.</li>

<li>You can manipulate more than one image at a time in an application, for example, in an HORIZON application involving simultaneous conversations.</li>

<li>You can use images to structure the local working storage of a request in a more disciplined manner than is possible with %variables.</li>
</ul>

==Defining an image==

===Managing blocks===

You must define the layout of the block before it can be used by the request. 

A block is defined by one or more images that describe the data in the block. 

Images describe blocks of data up to 32,767 bytes in length. 

===Define an image before referring to it===

In a request, an image definition must precede any references to the image. 

===Understanding how data is described by images===

To design applications using images, you can review the following summary of how images are used to describe different views of the data is provided below:
<ul>
<li>Using images, the application can access any piece of data in the block. As many as 255 images can describe the same block.</li>

<li>Although a single request can contain more than one block of images, the total number of images for all blocks within each request cannot exceed 256 images.</li>

<li>You can define multiple images to provide different views of the same data. This is similar to the COBOL capability to REDEFINE a piece of storage. The multiple image capability enables the request to read in a record, determine the format of the data in the record, and access different data items in the record according to format.</li>

<li>You can define the image items as strings or numbers. Numbers can have binary, floating point, packed decimal, zoned decimal, and exponential formats. <var class="product">Model 204</var> automatically handles all data type conversions when referring to image items.</li>

<li>You can define fixed and variable length arrays within an image. Each array element can contain one or more items. Arrays can be nested up to 255 levels deep.</li>

<li>You can define image items precisely or their length can be determined during evaluation. Similarly, the number of array occurrences can be determined during evaluation. This capability allows the request to handle all types of data structures. </li>
</ul>

===Image components===

Each block definition must begin with an IMAGE statement and end with an END IMAGE statement. Between these statements, the following components are used to describe the contents of the block:
<ul>
<li>Image definitions</li>

<li>Item definitions</li>

<li>Array definitions</li>

<li>Reserved area definitions </li>
</ul>

Comments, blank lines, and INCLUDE statements can also be part of a block definition. 

===Concurrent access to multiple records of the same format===

One image definition is required for each record to be accessed concurrently. 

If you need concurrent access to multiple records of the same format, the image definition must be duplicated with a different name. This can be done easily by using an INCLUDE statement inside the image definition.

==Image naming and reference conventions==

===Rules for image names===
<ul>
<li>An image name is a character string that consists of any number of letters, numbers, and some special characters. The name can have no embedded blanks, colons, or <var class="product">Model 204</var> reserved characters. Refer to [[Reserved words and characters]] for a complete list of reserved characters.</li>

<li>An image cannot have the same name as a screen or menu.</li>

<li>If IMAGE, MENU, or SCREEN is an image name, it must be preceded by the keyword IMAGE in READ IMAGE and PREPARE statements. </li>
</ul>

===Rules for item names and array names===
<ul>
<li>Item and array names follow the same naming conventions as image names.</li>

<li>Every image item name and array name must be unique within the block definition. An item name or array name can be reused in different blocks, screens, and menus.</li>

<li>An item (or array) name and its image name cannot have a combined length exceeding 253. </li>
</ul>

===Rule for reserved item names===

The item name READLEN is reserved by <var class="product">Model 204</var> to contain the length of the last record read into the block. This value can be obtained from the variable %imagename:READLEN. 

===Do not duplicate names in the same block===

Do not duplicate item, array, and image names within the same block. 

===References===

To identify the item uniquely, all references outside the image definition must include the image name and item name and must be specified in this format:
%imagename:itemname


For example:
%INVENTORY:PART.NO


identifies the item PART.NO in the image INVENTORY. 

==IMAGE and END IMAGE statements==

The IMAGE statement starts the definition of the image. Each image can contain a description of the complete block or can redefine a portion of another image.

====Syntax====

The format of the IMAGE statement is:
IMAGE imagename [AT {itemname | imagname1
| arrayname}
| GLOBAL [PERMANENT | TEMPORARY]
| [PERMANENT | TEMPORARY] GLOBAL
| COMMON]

Where:
<ul>
<li><var class="term">imagename</var> is the name of the image. Every image name defined in a request must be unique. The image name specified in the IMAGE statement is assigned to the image being defined; other User Language statements in the request can subsequently refer to this name.</li>

<li>The AT clause is optional and specifies the starting location of a redefinition. If the AT clause is omitted, the image definition starts at the beginning of the block. The location can be defined by one of the following options:
<ul>
<li><var class="term">itemname</var> is the name of an item in a previously defined image in this block.</li>

<li><var class="term">imagename1</var> is the name of an image previously defined in this block.</li>

<li><var class="term">arrayname</var> is the name of an array in a previously defined image in this block. </li>
</ul>

<blockquote class="note">Note:
You cannot use the AT clause with a GLOBAL image, since you can only define the first image in a multi-image block as a global image.
<ul>
<li>Specifying COMMON, or specifying neither COMMON nor GLOBAL, results in the image being stored in FSCB. Common elements, as well as DECLARE and COMMON, are discussed in detail in [[Subroutines#Subroutines|Subroutines]]. </li>

<li>GLOBAL specifies to store the image in GTBL. Global images have an implied scope of COMMON (see above).
</li>
</ul>
</blockquote>
</li></ul>

====Restrictions to the GLOBAL option====

You must not specify the GLOBAL attribute for an image that has an image item defined with either of the following attributes:
<ul>
<li>OCCURS UNKNOWN</li>

<li>LEN UNKNOWN</li>
</ul>

For multi-image blocks, you can specify only the first image as GLOBAL; you must not specify subsequent images in a multi-image block as GLOBAL.
<ul>
<li>PERMANENT can be used only with global images. Permanent global images persist across request boundaries; that is, they are maintained in GTBL even after a request has been terminated.</li>

<li>TEMPORARY can be used with only global images. TEMPORARY global images are allocated in GTBL, but are deleted at request termination. For example, use a TEMPORARY global image when you do not need to pass the image to another request; using TEMPORARY global images eliminates the need to explicitly delete globals that do not need to persist.
</li>
</ul>

===END IMAGE statement===

The END IMAGE statement must be the last statement in an image definition. END IMAGE terminates the definition of all images that describe the same block.

The format of this statement is: 
END IMAGE


===Examples of image definitions===

====Single image definition====

An example of the definition of a single image follows:
IMAGE GENERAL.LEDGER.RECORD
GL.RECORD.TYPE IS STRING LEN 1
GL.NUMBER IS STRING LEN 10 DP 3
GL.INV.TYPE IS STRING LEN 2
END IMAGE


====Multiple image definition for the same block====

The following example illustrates two images that define the same block. Each image completely defines the block, with the items named GL.RECORD.TYPE and AR.RECORD.TYPE both located at the first byte in the block.
IMAGE GENERAL.LEDGER.RECORD
GL.RECORD.TYPE IS STRING LEN 1
GL.NUMBER IS STRING LEN 10 DP 3
GL.INV.TYPE IS STRING LEN 2
IMAGE ACCOUNTS.REC.RECORD
AR.RECORD.TYPE IS STRING LEN 1
AR.ACCT.NO IS STRING LEN 6
AR.BALANCE IS PACKED DIGITS 9 DP 2
END IMAGE


====Multiple image definition with shared items====

When an image redefines part of another image, the AT clause names an item or array in an image already defined in the record. Items preceding the named item or array in the block are combined with items defined following the IMAGE statement to create the complete image description.

Therefore, the preceding example also could be defined in the following manner. The example illustrates two images that define the same block but share at least one item in common. In this example, the item RECORD.TYPE is shared by both images, and can be referred to by prefixing the item name by either image name. The items GL.NUMBER and AR.ACCT.NO both begin at position 2 in the block.
IMAGE GENERAL.LEDGER.RECORD
GL.RECORD.TYPE IS STRING LEN 1
GL.NUMBER IS STRING LEN 10 DP 3
GL.INV.TYPE IS STRING LEN 2
IMAGE ACCOUNTS.REC.RECORD AT GL.NUMBER
AR.ACCT.NO IS STRING LEN 6
AR.BALANCE IS PACKED DIGITS 9 DP 2
END IMAGE


===Special considerations for multiple image blocks===

When you define multiple image blocks, take note whether the sum of the individual image items completely defines the block. Is there undefined space between the image items? If there are, you must initialize the space, otherwise you might get unexpected results, as illustrated in the following code.

====Using uninitialized disk space====

In the following multiple image block, PART1, PART2, and PART3 define parts of the block without defining or initializing the space between them. When LINE is defined, which encompasses the entire block, the system assumes that entire block has already been defined, because LINE begins at the same place as PART1. 
R HDRCTL 0
BEGIN

IMAGE A
PART1 IS STRING LEN 10
PART2 IS STRING LEN 5 AT 16
PART3 IS STRING LEN 5 AT 26
LINE IS STRING LEN 30 AT PART1
END IMAGE

PREPARE IMAGE A

%A:PART1 = 'XXXXXXXXXX'
%A:PART2 = 'YYYYY'
%A:PART3 = 'ZZZZZ'

SET HEADER 1 %A:LINE
NP
PRINT '%A:LINE = ' WITH %A:LINE
PRINT '$C2X(%A:LINE) = ' WITH $C2X(%A:LINE)
END


However, when output from the previous procedure is displayed, a stray numeral two appears twice in the header. This system read the string of zeros for the uninitialized space in the header (shown in the line that begins $C2X) and automatically substituted the page number. 
02.142 MAY 22 10.11.11 PAGE 2
XXXXXXXXXX 2YYYYY 2ZZZZZ
%A:LINE = XXXXXXXXXX YYYYY ZZZZZ
$C2X(%A:LINE) = E7E7E7E7E7E7E70000000000E8E8E8E8E80000000000E9E9E9E9E9


====Using initialized disk space====

Refining the previous code, the spaces between PART 1 and PART2 and PART3 are initialized by the intervening SKIP statements.
R HDRCTL 0
BEGIN

IMAGE A
PART1 IS STRING LEN 10
SKIP 5 POSITIONS INITIAL BLANK
PART2 IS STRING LEN 5 AT 16
SKIP 5 POSITIONS INITIAL BLANK
PART3 IS STRING LEN 5 AT 26
LINE IS STRING LEN 30 AT PART1
END IMAGE

PREPARE IMAGE A

%A:PART1 = 'XXXXXXXXXX'
%A:PART2 = 'YYYYY'
%A:PART3 = 'ZZZZZ'

SET HEADER 1 %A:LINE
NP
PRINT '%A:LINE = ' WITH %A:LINE
PRINT '$C2X(%A:LINE) = ' WITH $C2X(%A:LINE)
END


Now the output displays the expected results. The line that begins $C2X has the hexadecimal representation of white space between the defined areas meaning that the space is initialized. The system prints only the white spaces.
02.142 MAY 22 10.12.26 PAGE 2
XXXXXXXXXX YYYYY ZZZZZ
%A:LINE = XXXXXXXXXX YYYYY ZZZZZ
$C2X(%A:LINE) = E7E7E7E7E7E7E74040404040E8E8E8E8E84040404040E9E9E9E9E9


==Defining image items==

You must define each item in an image that is referred to by the request. Use an item definition to describe the following attributes for an item:
<ul>
<li>Data type </li>
<li>Length </li>
<li>Position </li>
<li>Number of occurrences</li>
<li>Editing options</li>
</ul>

====Syntax====

The general format of an item definition is:
itemname [IS [TYPE] type description]

Where:
<ul>
<li><var class="term">itemname</var> is the name by which the item is referred to.</li>

<li>TYPE is an optional keyword.</li>

<li><var class="term">type</var> specifies the data type of the item. Data type options are:
<ul>
<li>String</li>
<li>Binary</li>
<li>Large Object data</li>
<li>Packed decimal</li>
<li>Zoned decimal</li>
<li>Floating point</li>
<li>Exponential notation </li>
</ul></li>

<li><var class="term">description</var> is the length, position, number of occurrences, and editing options specified for the item based on the data type.
</li>
</ul>

The format used when defining an item for each data type is provided in the following table. In addition, an example of an image item definition appears in [[#Item definition examples|Item definition examples]]: 
<table>
<tr class="head">
<th>Term</th>
<th>Description</th>
</tr>

<tr>
<td>Numeric</td>
<td>All types except STRING are considered numeric.</td>
</tr>

<tr>
<td>NULL</td>
<td>Binary zeros.</td>
</tr>

<tr>
<td>Omitted</td>
<td>The option is omitted from the item description and no default is specified.</td>
</tr>

<tr>
<td>String</td>
<td>A string of characters. A string must be enclosed in single quotes if it contains any of the following characters: blank, =, (, ), <, >, or ^.</td>
</tr>

<tr>
<td>ZERO</td>
<td>Numeric zero of the correct format for numeric items. String and EFORMAT items are set to a single character zero. </td>
</tr>
</table>

==Defining a string item==

====Syntax====

Define string items with this syntax: 
STRING {LEN {n | UNKNOWN} [DP {k | *}] | TO position}
[PAD {BLANK | character | NULL}]
[STRIP | NOSTRIP] [JUSTIFY {LEFT | RIGHT}]
[INITIAL {BLANK | string | ZERO | NULL}]
[AFTER {itemname | arrayname}
| AT {position | itemname | imagname1 | arrayname}]
[OCCURS {n [DEPENDING ON {itemname | %variable}]
| UNKNOWN}]

Where:
<ul>
<li>LEN specifies the length either as 1-255 bytes or as UNKNOWN, if the length is determined by the request and the IDENTIFY statement establishes the length. </li>

<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length (LEN) or end (TO) position of the item is required unless the length has been specified in a DEFAULT statement. </li>

<li>DP (optional) specifies either that the item has from 0 to 15 decimal places as specified by k, or that the number of decimal places is variable.
<ul>
<li>DP k represents the number of places retained when a number is stored into an item and the number of places assumed to be present in data read from an external record. </li>

<li>If DP * is specified, all decimal places in the item are retained. If this option is omitted, the default is zero. Do not use DP, if the value to be moved to the item contains a decimal point. </li>
</ul></li>

<li>PAD (optional) defines the fill character. If a value is shorter than an item to which it is being moved, the pad character fills the remainder of the item. If PAD is omitted, a blank is assumed. Padding is done on the right end of left-justified items and on the left end of right-justified items.

The pad character can be a single quoted character, a hexadecimal value expressed as X'hh', or a decimal number. The hexadecimal or decimal value can be from 0 to 255.
</li>

<li>STRIP, the default, specifies to remove the pad characters, if an item value is extracted from an image. NOSTRIP specifies to keep the pad characters. </li>

<li>JUSTIFY (optional) specifies whether a value is to be left- or right-justified when moved into an item by an assignment statement or when stripping on extraction. If JUSTIFY is omitted, the default is left-justified. </li>

<li>INITIAL (optional) defines the value placed in the item by a PREPARE statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If an INITIAL clause is omitted, BLANK is the default initial value.
</li>
</ul>

====AFTER and AT clauses====
<ul>
<li>The AFTER and AT clauses are optional and mutually exclusive. Their function is as follows:

An AFTER clause defines the location of an item as immediately following the end of the specified item or array. This option is particularly useful when an item is redefined and the total length of the items in a redefinition is less than the length of the item. 

An AT clause defines the location of the item in the image as adjacent to an item or array or redefines the space defined by a previously defined item. If the location is not adjacent in a forward direction to the previous item definition, a SKIP is implied (see [[#DEFAULT SKIP statement|DEFAULT SKIP statement]]). If position is used, the location is relative to the beginning of the image. 

The position option can have a value from 1 through 32767. The item or array named in the AT clause cannot have a DEPENDING ON option. 

Consider the following restrictions when using an AFTER or AT clause:
<ul>
<li>Outside of an array definition, the AFTER or AT clause cannot name an item inside the array.</li>

<li>Within an array definition, the AFTER or AT clause cannot name an item outside of the array. </li>

<li>If neither AFTER nor AT are specified, the item abuts the end of the preceding item or the start of the image.</li>
</ul>
</li>
</ul>

====OCCURS clause====
<ul>
<li>The OCCURS clause (optional) specifies that there are multiple occurrences of the item. The OCCURS clause options are as follows:
<ul>
<li><var class="term">n</var> specifies the maximum number of occurrences of the item for a depending array and the exact number of occurrences of the item for a fixed array. The value of <var class="term">n</var> can be from 1 to 32767. Space for the maximum number of occurrences is reserved in a block created by a PREPARE statement or when a block is read from a sequential file, VSAM file, or terminal.</li>

<li>The DEPENDING ON clause identifies the item or %variable that contains the current number of occurrences of this item. An item specified in this clause must be part of this image, cannot have length specified as UNKNOWN, cannot be an array element, and cannot be positioned in the image following an item defined with LEN UNKNOWN or an array defined with OCCURS UNKNOWN. </li>

<li>UNKNOWN specifies that the number of occurrences of the item is determined by the User Language request and that the IDENTIFY statement establishes the number of occurrences. </li>
</ul>
</li></ul>

==Defining a binary item==

====Syntax====

Define binary items with this syntax: 
BINARY {LEN {n | UNKNOWN} | BITS n | TO position}
[BP n]
[SIGNED | UNSIGNED] [ALIGN]
[INITIAL {NULL | number | BLANK | ZERO}]
[AFTER {itemname | arrayname}
| AT {position | itemname | imagname1 | arrayname}]
[OCCURS {n [DEPENDING ON {itemname | %variable}]
| UNKNOWN}]

Where:
<ul>
<li>LEN specifies the length as 1-4 bytes or as UNKNOWN if the length is determined by the request and the IDENTIFY statement establishes the length. </li>

<li>BITS specifies the length as 8, 16, 24, or 32 bits. </li>

<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a DEFAULT statement. </li>

<li>BP (optional) specifies the number of binary places retained when a number is stored in the item and the number of places assumed present in data read from an external record. The number of places can range from zero to the number of bits defined by the length option, the maximum is 31 bits. IF BP is omitted, the default value is zero.</li>

<li>SIGNED, optional and the default, specifies that a negative number can be stored in the item in two's complement form. UNSIGNED, optional, specifies that the item is always positive and that the leftmost bit is part of the number.
Note:
If a negative number is read into an UNSIGNED BINARY item, <var class="product">Model 204</var> uses the absolute value of that number. </li>

<li>ALIGN, optional, specifies that the item is aligned as follows:
<ul>
<li>BINARY LEN 2 on a halfword boundary</li>
<li>BINARY LEN 4 on a fullword boundary </li>
<li>The ALIGN option is ignored for 1- and 3-byte BINARY items.</li>
</ul>

The item is aligned by inserting a SKIP statement preceding the item so that the item's location is on the correct boundary. In arrays, a SKIP is inserted at the end of each occurrence of the array and any parent array to make the length of each occurrence a multiple of the largest aligned item in the array. 

The ALIGN option cannot be specified for an item:
<ul>
<li>When length is defined as UNKNOWN. </li>
<li>When location is unknown during compilation because a previously defined item specified LEN UNKNOWN or OCCURS UNKNOWN. </li>
<li>Containing an AT clause that specifies a location that is not already aligned on the proper storage boundary.</li>
</ul></li>

<li>INITIAL (optional) defines the value placed in the item by a PREPARE statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, NULL is the default initial value. </li>

<li>The AFTER and AT clauses are mutually exclusive and optionally define the location of the item in the image. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li>

<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]].
</li>
</ul>

==Defining a packed decimal item==

====Syntax====

Define packed decimal items with this syntax: 
PACKED {LEN {n | UNKNOWN} | DIGITS n | TO position}
[DP n]
[SIGNED | UNSIGNED]
[INITIAL {ZERO | number | BLANK | NULL}]
[AFTER {itemname | arrayname}
| AT {position | itemname | imagname1 | arrayname}]
[OCCURS {n [DEPENDING ON {itemname | %variable}]
| UNKNOWN}]

Where:
<ul>
<li>LEN specifies the length as 1-8 bytes or as UNKNOWN if the length is determined by the request and the IDENTIFY statement establishes the length. </li>

<li>DIGITS specifies the length as 1-15 decimal digits. </li>

<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a DEFAULT statement. </li>

<li>DP (optional) and specifies the number of decimal places to be retained when a number is stored in this item, that is, the number of places assumed present in data read from an external record. The value of n can range from 0 to 15. If this option is omitted, the default is zero. </li>

<li>SIGNED, optional and the default, specifies that the item can contain a positive or negative number. The sign stored with the number is a hexadecimal C for a positive number and D for a negative number.</li>

<li>UNSIGNED (optional) specifies that the item is always a positive number and that the sign stored with the number is a hexadecimal F. </li>

<li>INITIAL (optional) defines the value placed in the item by a PREPARE statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, the default initial value is a packed zero. </li>

<li>The mutually exclusive and optional AFTER and AT clauses define the location of the item in the image. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li>

<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]].
</li>
</ul>

==Defining a zoned decimal item==

====Syntax====

Define zoned decimal items with this syntax: 
ZONED {LEN {n | UNKNOWN} | DIGITS n | TO position}
[DP n]
[SIGNED | UNSIGNED]
[INITIAL {ZERO | number | BLANK | NULL}]
[AFTER {itemname | arrayname}
| AT {position | itemname | imagname1 | arrayname}]
[OCCURS {n [DEPENDING ON {itemname | %variable}] | UNKNOWN}]

Where:
<ul>
<li>LEN specifies the length as 1-15 bytes or as UNKNOWN if the length is determined by the request and the IDENTIFY statement establishes the length. </li>

<li>DIGITS specifies the length as 1-15 decimal digits. </li>

<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a DEFAULT statement. </li>

<li>DP, optional, specifies the number of decimal places to be retained when a number is stored in this item, that is, the number of places assumed present in data read from an external record. The value of n can range from 0 to 15. If this option is omitted, the default is zero. </li>

<li>SIGNED, optional and the default, specifies that the item can contain a positive or negative number. The sign stored with the number is a hexadecimal C for a positive number and D for a negative number. </li>

<li>UNSIGNED, optional, specifies that the item is always a positive number and that the sign stored with the number is a hexadecimal F. </li>

<li>INITIAL is optional and defines the value placed in the item by a PREPARE statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, the default initial value is zoned decimal zeros. </li>

<li>The mutually exclusive and optional AFTER and AT clauses define the location of the item in the image. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li>

<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]].
</li>
</ul>

==Defining a floating point item==

====Syntax====
FLOAT {LEN {n | UNKNOWN} TO position
[INITIAL {ZERO | number | BLANK | NULL}] [ALIGN]
[AFTER {itemname | arrayname}
| AT {position | itemname | imagname1 | arrayname}]
[OCCURS {n [DEPENDING ON {itemname | %variable}] | UNKNOWN}]

Where:
<ul>
<li>LEN specifies the length as either 4, 8, or 16 bytes or as UNKNOWN if the length is determined by the request and the IDENTIFY statement establishes the length.

Although you can move 16-byte floating-point values between data sets and files, intermediate results and %variables inside User Language are 8 bytes long. 

Arithmetic manipulations and data conversions retain only 15 significant decimal digits in 8 bytes.
</li>

<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a DEFAULT statement. </li>

<li>INITIAL, optional, defines the value placed in the item by a PREPARE statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. If this option is omitted, the default initial value is a floating point zero. </li>

<li>ALIGN, optional, specifies that the item is aligned as follows:
<ul>
<li>FLOAT LEN 4 on a fullword boundary</li>
<li>FLOAT LEN 8 on a doubleword boundary</li>
<li>FLOAT LEN 16 on a doubleword boundary </li>
<li>The item is aligned by inserting a SKIP statement preceding the item so that the item's location is on the correct boundary. In arrays, a SKIP statement is inserted at the end of each occurrence of the array and any parent array to make the length of each occurrence a multiple of the largest aligned item in the array. </li>
</ul>

The ALIGN option cannot be specified for an item: 
<ul>
<li>When length is defined a UNKNOWN.</li>
<li>When location is unknown during compilation because a previously defined item specified LEN UNKNOWN or OCCURS UNKNOWN. </li>
<li>Containing an AT clause that specifies a location that is not already aligned on the proper storage boundary. </li>
</ul></li>

<li>The AFTER and AT clauses are mutually exclusive and optionally define the location of the item in the image. For a complete discussion, see [[#Defining a string item|Defining a string item]]. </li>

<li>The OCCURS clause is optional and specifies that there are multiple occurrences of the item. For a complete discussion, see [[#Defining a string item|Defining a string item]].
</li>
</ul>

==Defining an exponential notation item==

====Syntax====

Define exponential notation items with this syntax: 
EFORMAT {LEN {n | UNKNOWN} | TO position}
[PAD {BLANK | character | NULL}]
[STRIP | NOSTRIP] [JUSTIFY {LEFT | RIGHT}]
[INITIAL {BLANK | string | ZERO | NULL}] [DIGITS n]
[DP n] [AFTER {itemname | arrayname}
| AT {position | itemname | imagname1 | arrayname}]
[OCCURS {n [DEPENDING ON {itemname | %variable}] | UNKNOWN}]

Where:
<ul>
<li>LEN specifies the length either as 1-255 bytes or as UNKNOWN if the length is determined by the request and the IDENTIFY statement establishes the length. </li>

<li>TO specifies the last byte position of the item in the image as a number from 1 to 32767. The length or end (TO) position of the item is required unless provided in a DEFAULT statement. </li>

<li>PAD, optional, defines the fill character. If a value is shorter than an item to which it is being moved, the pad character fills the remainder of the item. Padding is done on the right end of items that are left-justified and on the left end for items that are right-justified. The pad character can be a single quoted character, a hexadecimal value expressed as X'hh', or a decimal number from 1 to 255. </li>

<li>STRIP, the default, specifies that the pad character is removed if an item value is extracted from an image. NOSTRIP specifies to keep the pad characters. </li>

<li>JUSTIFY, optional, specifies whether a value is to be left- or right-justified when moved into an item by an assignment statement. The default behavior is left-justified. </li>

<li>INITIAL is optional and defines the value placed in the item by a PREPARE statement and in unused occurrences when a record is read from a sequential file, VSAM file, or terminal into an image. A single character zero is the default value. </li>

<li>DIGITS specifies the maximum number of significant digits — the total number of digits to the left and right of the decimal point. The value of n can be a number from 1 to 15. </li>

<li>DP specifies the number of digits to be placed to the right of the decimal point when a value is moved into the item. </li>

<li>The mutually exclusive and optional AFTER and AT clauses define the location of the item in the image. See [[#Defining a string item|Defining a string item]], for a complete discussion. </li>

<li>The optional OCCURS clause specifies that there are multiple occurrences of the item. See [[#Defining a string item|Defining a string item]] for a complete discussion.
</li>
</ul>

==Item definition examples==

===An image containing various item types===
IMAGE GENERAL.LEDGER.RECORD
GL.RECORD.TYPE IS STRING LEN 1
GL.NUMBER IS ZONED LEN 10 DP 0
GL.INV.TYPE IS STRING LEN 2
GL.DEPRECIATION.CODE IS STRING LEN 2
GL.BOOK.VALUE IS PACKED DIGITS 9 DP 2
GL.YEARS.REMAINING IS BINARY LEN 4
GL.QUANTITY.ON.HAND IS BINARY LEN 4
GL.ITEM.SIZE IS FLOAT LEN 4
END IMAGE


===Using the AT and AFTER clauses===
IMAGE PRINT.DATA
PRINT.LINE1 IS STRING LEN 133 DP *
PRINT.CC IS STRING LEN 1 AT PRINT.LINE1
PRINT.ITEM1 IS STRING LEN 8
SKIP 2 POSITIONS
PRINT.ITEM2 IS STRING LEN 7
SKIP 2 POSITIONS
PRINT.ITEM3 IS STRING LEN 8
SKIP 2 POSITIONS
PRINT.ITEM4 IS STRING LEN 6
PRINT.LINE2 IS STRING LEN 133 DP * AFTER PRINT.LINE1
END IMAGE


In the preceding example, PRINT.LINE2 is placed adjacent to the end of PRINT.LINE1. Without the AFTER clause, an AT clause would be required to specify the numeric position of PRINT.LINE2 in the image. 

==Defining arrays==

An <var class="term">array</var> contains multiple occurrences of a single item or a group of items. 

===Array definition statements===

When an array is composed of a single item, the array can be defined by using the OCCURS clause on the item definition or an ARRAY statement. 

When an array is composed of more than one item, the array is defined by using an ARRAY statement and is followed by definitions of the items that compose each element of the array. 

None of the items in an array or subordinate array can specify LEN UNKNOWN or OCCURS UNKNOWN.

===Types of arrays===

The format of the ARRAY statement depends on which of the following types of arrays is being defined:
<table>
<tr class="head">
<th>For type of array... </th>
<th>The number of occurrences in the array is...</th>
</tr>
<tr>
<td>Fixed occurrence </td>
<td>Constant.</td>
</tr>
<tr>
<td>Depending </td>
<td>Constant as defined in the image, but a record that is read from a sequential file, VSAM file, or terminal or is written to a sequential file or terminal can contain a smaller number of occurrences.</td>
</tr>
<tr>
<td>Unknown </td>
<td>Not known. The maximum number of occurrences must be specified during evaluation by using the [[#IDENTIFY statement|IDENTIFY statement]]. </td>
</tr>
</table>

===ARRAY and END ARRAY statements===

You define an array with an ARRAY statement. The definitions of items and subordinate arrays follow the ARRAY statement. 

You specify the end of the array with an END ARRAY statement. END ARRAY ends the definition of the array defined by the preceding ARRAY statement. In addition, an IMAGE or END IMAGE statement ends all preceding ARRAY definitions. 

==Defining a fixed occurrence array==

A <var class="term">fixed occurrence array</var> has a specified number of occurrences. Each external record read from a sequential file, VSAM file, or terminal or written to a sequential file or terminal is assumed to contain that number of occurrences. 

====Syntax====

The format of the ARRAY statement used to define a fixed occurrence array is:
ARRAY [arrayname] OCCURS n
[AFTER {itemname | arrayname}
| AT {position | itemname | imagname1 | arrayname}

Where:
<ul>
<li><var class="term">arrayname</var> (optional) names the array. An array must be named if it is specified in the AT clause of an image definition or in the AFTER or AT clauses in an item definition. </li>

<li><var class="term">n</var> is the number of occurrences of the items in the array, which can range from 1 to 32767.</li>

<li>AFTER and AT clauses are mutually exclusive and optionally specify the location of the array in the image. See [[#Defining a string item|Defining a string item]] for detailed information.
</li>
</ul>

====Example====

The following example of an image contains a fixed occurrence array. In this example, each element of the SALES.MONTHLY array contains the item SALES.TOTAL and five occurrences of the item SALES.BY.MODEL.
IMAGE SALES
ARRAY SALES.MONTHLY OCCURS 12
SALES.TOTAL IS PACKED DIGITS 9 DP 2
SALES.BY.MODEL IS PACKED DIGITS 9 DP 2 -
OCCURS 5
END ARRAY
END IMAGE


The same image could be written as:
IMAGE SALES
ARRAY SALES.MONTHLY OCCURS 12
SALES.TOTAL IS PACKED DIGITS 9 DP 2
ARRAY OCCURS 5
SALES.BY.MODEL IS PACKED DIGITS 9 DP 2
END ARRAY
END ARRAY
END IMAGE


==Defining a depending array==

A <var class="term">depending array</var> has a fixed number of occurrences in the image, but a smaller number of occurrences can be found in records read from a sequential file, VSAM file, or terminal or records written to a sequential file or terminal. 

===Depending variable===

A depending variable is used to specify the actual number of occurrences that exist in the record. 

The depending variable is used in this manner:
<ul>
<li>When a record is read from a sequential file, VSAM file, or terminal into an image, the record is assumed to contain only the number of occurrences specified by the value in the depending variable. The depending variable must have a value from zero to the maximum number of occurrences in the array. The occurrences specified in the variable are moved to the image and any remaining occurrences are initialized. When an image is created by a PREPARE IMAGE statement, space in the image is allocated for the maximum number of occurrences. </li>

<li>When a record is written from an image to a sequential file or terminal, the record is assumed to contain only the number of occurrences specified by the value in the depending variable. Therefore, the record is written with all unfilled occurrences removed.
</li>
</ul>

If a subordinate array has a depending variable, the value of that variable applies to all occurrences of the outer array. 

====Restrictions====

A depending array cannot be redefined in the current image or in any other image in the block. In addition, a depending array and the AFTER or AT clause are mutually exclusive.

====Syntax====

The form of the ARRAY statement used for defining a depending array is:
ARRAY [arrayname] OCCURS n DEPENDING ON {itemname | %variable}

Where:
<ul>
<li><var class="term">arrayname</var>, optional, names the array. An array must be named if it is specified in the AT clause of an image definition or in the AFTER or AT clauses of an item definition. </li>

<li><var class="term">n</var> is the number of occurrences of the items in the array, which can range from 1 to 32767.</li>

<li>The DEPENDING ON clause names a previously defined %variable or item within the image that contains the actual number of occurrences in an input record. An item used as the depending variable cannot:
<ul>
<li>Be an array element</li>
<li>Vary in length, that is, be defined with LEN UNKNOWN</li>
<li>Follow any varying length item or array in the image. </li>
</ul></li>
</ul>

====Example====

The following example of an image contains an array with a depending variable is shown below. In this example, SALES.MODELS contains 15 occurrences of the item SALES.MODEL.NO. Therefore, the external record can contain from 0 to 15 occurrences.
IMAGE SALES
SALES.MODELS IS BINARY LEN 2
ARRAY OCCURS 15 DEPENDING ON SALES.MODELS
SALES.MODEL.NO IS PACKED DIGITS 9 INITIAL 0
END ARRAY
END IMAGE


If a record is read into the previous image, the number of items defined by the value of the item SALES.MODELS are moved from the record into the array. Any occurrences of SALES.MODEL.NO not filled in the array from the record are initialized to zero. Before a record is written from the SALES image to a sequential file or terminal, the number of items defined by the value of the item SALES.MODELS are moved from the array into the record. Any unused occurrences are not present in the record written to the sequential file or terminal. 

==Defining an unknown array==

An array must be defined as <var class="term">unknown</var> when you cannot determine the maximum number of occurrences until after the data moves into the image. The number of occurrences in the array is specified as UNKNOWN. During evaluation, the IDENTIFY statement is used to specify the number of occurrences in the array before any item in the array is referred to. 

====Syntax====

The format of the ARRAY statement used for defining an unknown array is:
ARRAY [arrayname] OCCURS UNKNOWN
[AFTER {itemname | arrayname}
| AT {position | itemname | imaginename1
| arrayname}]

Where:
<ul>
<li><var class="term">arrayname</var> is required and names the array. This name is used to identify the array in IDENTIFY statements that specify the number of occurrences during evaluation.</li>

<li>The AFTER and AT clauses are mutually exclusive and optionally specify the location of the array in the image. See [[#Defining a string item|Defining a string item]] for detailed information.
</li>
</ul>

====Example====

This example illustrates the use of unknown arrays. In this example, the number of occurrences of the array TRANSACTION is contained in the item TRANS.COUNT. Before the items TRANS.NO, TRANS.AMT, or TRANS.CUST can be referred to, the IDENTIFY statement is executed to set the number of occurrences.
TRANS.COUNT IS BINARY LEN 4
ARRAY TRANSACTION OCCURS UNKNOWN
TRANS.NO IS PACKED LEN 5
TRANS.AMT IS PACKED LEN 7 DP 2
TRANS.CUST IS STRING LEN 10
END ARRAY


==Referring to array elements==

Individual items within an array are identified by subscripts. The <var class="term">subscript</var> is enclosed in parentheses and can be any expression that evaluates to a number from 1 to the maximum size of the array. 

===Nested arrays===

If arrays are nested, subscripts are required for each nesting level and are separated by commas. The outermost array is the first subscript.

====Example====

In this example, the fifth student in the second course would be referred to as COURSE.STUDENT(2,5).
IMAGE COURSE.DATA
ARRAY OCCURS 20
COURSE.NUMBER IS BINARY LEN 4
COURSE.NAME IS STRING LEN 25
COURSE.INSTRUCTOR IS STRING LEN 20
COURSE.STUDENT IS STRING LEN 20 OCCURS 30
END ARRAY
END IMAGE


==Initialization of array values==

<var class="product">Model 204</var> lets you specify multiple value assignments into array dimensions within a single User Language assignment statement by adding an asterisk (*) as the subscript value. Using the asterisk is valid for percent variable arrays and image arrays.

====Example 1====

The following statement sets all elements in all dimensions to 0:
%ARRAY.ITEM (*,*,*) = 0


====Example 2====

If an array is defined as occurs 3, occurs 4, occurs 2, <code>%ARRAY.ITEM(*,2,*) = 9</code> is equivalent to the following:
%ARRAY.ITEM(1,2,1) = 9
%ARRAY.ITEM(1,2,2) = 9
%ARRAY.ITEM(2,2,1) = 9
%ARRAY.ITEM(2,2,2) = 9
%ARRAY.ITEM(3,2,1) = 9
%ARRAY.ITEM(3,2,2) = 9


====Example 3====

The following example prints AAA and 100:
BEGIN
IMAGE TEST
ARRAY OCCURS 5
PART1 IS BINARY LEN 2
PART2 IS FLOAT LEN 8
PART3 IS STRING LEN 3 OCCURS 4
PART4 IS FLOAT LEN 8 OCCURS 2
END ARRAY
END IMAGE
PREPARE IMAGE TEST
%TEST:PART3(3,*) = 'AAA'
%TEST:PART4(*,2) = 100
PRINT %TEST:PART3(3,4)
PRINT %TEST:PART4(2,2)
END


====Example 4====

The asterisk is not valid on the right side of a User Language assignment statement. The following statement is invalid and causes a compilation error:
%X = %ARRAY.ITEM(*,*,*)


==Using Large Object fields with a very large array==

If you have a very large array that is densely populated and not a preallocated field, you may improve performance by storing this array of data in a Large Object field.

When an array of data is used as a field that is not preallocated, then each field reference includes the overhead of walking through the record to find that fieldname(fieldoccurrence) value.

With a Large Object field, you can directly address each item using the <offset>,<length> syntax available for Large Object fields.

There is one Table B access to retrieve the Large Object descriptor, and one Table E access to read the page that your data resides on, no matter how far into the object the data resides.

There may be a substantial CPU reduction for applications that reference large arrays as Large Object data instead of holding each array entry in a field occurrence.

Cautionary usage note: Disk space utilization: Each Large Object field requires the total Large Object length rounded up to the next 6184 bytes of space.This is because Large Object data is a collection of Table E pages; you cannot allocate just part of a page.

==Defining reserved space==

The format of the entire block does not have to be specified in an image definition. When items are not contiguous, space must be reserved to correctly position the items. 

Space is reserved automatically by an AT clause that places an item beyond the end of the last defined item. 

===SKIP statement===

Space is reserved explicitly by using the SKIP statement. The space reserved by a SKIP statement can be initialized by a PREPARE statement but cannot be accessed. 

====Syntax====

The format of the SKIP statement for reserving space is:
[itemname IS] SKIP n POSITION[S]
[INITIAL {NULL | character | BLANK}]

Where:
<ul>
<li>The <var class="term">itemname</var> <var>IS</var> clause (optional) names a reserved area that can be referred to by an AFTER or AT clause.</li>

<li><var class="term">n</var> is the number of bytes to be reserved. A maximum of 32767 bytes can be reserved.</li>

<li>The INITIAL clause indicates the character with which the area is filled by PREPARE and IDENTIFY statements. Options are as follows:
<ul>
<li>character — a single quoted character, a decimal number from 1 to 255, or a hexadecimal value expressed as X'hh'</li>
<li>BLANK — white spaces</li>
<li>NULL — binary zeros </li>
</ul>

If the INITIAL clause is omitted, NULL is the default. 
</li>
</ul>

====Example====

This sample SKIP statement reserves two bytes before the next image item: 
SKIP 2 POSITIONS


==DEFAULT TYPE and DEFAULT SKIP statements==

You can provide default values for image item options to eliminate repetition of these options on each item definition, using: 
<ul>
<li>DEFAULT TYPE</li>
<li>DEFAULT SKIP </li>
</ul>

===DEFAULT TYPE statement===

The DEFAULT TYPE statement lets you set default option values for each item type. The options specified on a DEFAULT TYPE statement for an item type are applied to each item of that type defined between the default statement and the next default statement of the same item type. 

====Syntax====

The format of the DEFAULT TYPE statement is:
DEFAULT [TYPE] type options

Where:
<ul>
<li>The optional TYPE keyword specifies a default data type for any item definition that does not explicitly define the data type. Without the TYPE keyword, the statement defines the default option values for an item type without defining the default item type.</li>

<li><var class="term">type</var> specifies the data type of the item. Valid values are STRING, BINARY, FLOAT, PACKED, ZONED, or EFORMAT.</li>

<li><var class="term">options</var> specifies any of the options that are valid for the item type except for the TO, AFTER, AT, and OCCURS clauses.
</li>
</ul>

===DEFAULT SKIP statement===

The DEFAULT SKIP statement specifies the default length or initial value for a SKIP statement or an implied skip. It can appear anywhere in an image definition and remains in effect until the next DEFAULT SKIP statement.

====Syntax====

The format of the DEFAULT SKIP statement is:
DEFAULT SKIP n POSITION[S]
[INITIAL {NULL | 'character' | BLANK}]

Where:
<ul>
<li><var class="term">n</var> is a positive integer that specifies the number of bytes to be reserved. A maximum of 32767 bytes can be reserved.</li>

<li>The INITIAL clause indicates the fill character for PREPARE and IDENTIFY statements. Options are as follows:
<ul>
<li><var class="term">character</var> — a single quoted character, a decimal number from 1 to 255, or a hexadecimal value expressed as X'hh'</li>
<li>BLANK — white space</li>
<li>NULL — binary zeros </li>
</ul>

If the INITIAL clause is omitted, NULL is the default. 
</li>
</ul>

===Example of DEFAULT statements===

The following examples show how an image can be described without and then with DEFAULT statements.

====Without DEFAULT statements====
IMAGE SALES
SALES.YEAR.TOTAL IS PACKED DIGITS 7 DP 2
SALES.MONTH.TOTAL IS PACKED DIGITS 7 DP 2
SALES.REP.NO IS PACKED DIGITS 5
SALES.REP.NAME IS STRING LEN 20
SALES.REP.ADDRESS.1 IS STRING LEN 20
SALES.REP.ADDRESS.2 IS STRING LEN 20
END IMAGE


====With DEFAULT statements====
IMAGE SALES
DEFAULT TYPE STRING LEN 20
DEFAULT PACKED DIGITS 7 DP 2

* THE FOLLOWING TWO ITEMS DEFAULT TO DIGITS 7 DP 2

SALES.YEAR.TOTAL IS PACKED
SALES.MONTH.TOTAL IS PACKED

* DP 0 IS NECESSARY ON THE NEXT LINE IN ORDER TO AVOID
* THE DEFAULT OF 2

SALES.REP.NO IS PACKED DIGITS 5 DP 0

* THE FOLLOWING 3 ITEMS DEFAULT TO STRING LEN 20

SALES.REP.NAME
SALES.REP.ADDRESS.1
SALES.REP.ADDRESS.2
END IMAGE


==Processing images==

Once a block is defined, you can use the following statements to process external records and to manipulate a block of storage. 
<table>
<tr class="head">
<th>Statement</th>
<th>Action undertaken</th>
</tr>

<tr>
<td>CLOSE</td>
<td>Closes a sequential file, VSAM file, or terminal opened by the request.</td>
</tr>

<tr>
<td>IDENTIFY</td>
<td>Defines an active image and establishes the length for items or array occurrences defined as UNKNOWN.</td>
</tr>

<tr>
<td>OPEN</td>
<td>Opens a sequential file, VSAM file, or terminal for processing.</td>
</tr>

<tr>
<td>POSITION</td>
<td>Specifies the next record to be read sequentially in a VSAM KSDS file.</td>
</tr>

<tr>
<td>PREPARE</td>
<td>Initializes an image.</td>
</tr>

<tr>
<td>READ IMAGE</td>
<td>Reads a record from a sequential file, VSAM file, or terminal.</td>
</tr>

<tr>
<td>RELEASE POSITION</td>
<td>Terminates the browse operation established by a POSITION statement.</td>
</tr>

<tr>
<td>WRITE IMAGE</td>
<td>Writes a record to a sequential file or to a terminal.</td>
</tr>
</table>

===Key field for VSAM files===

When the VSAM key is not in character format, special handling is required to supply the key in the format required by VSAM. If the key is supplied as a %variable or image item that has a numeric type, the READ IMAGE and POSITION statements attempt to convert the numeric value to string.

The suggested technique to resolve this problem is to define the image of the record with the key field defined in the format expected by VSAM and redefined as a string of the same length. The key value is moved to the key item and the string item name is provided in the READ or POSITION statement. 

An example of this technique for a VSAM file that has a 4-byte binary key is illustrated below:
IMAGE VSAM.REC
KEY IS BINARY LEN 4
KEY.STR IS STRING LEN 4 AT KEY
.
(additional items)
.
END IMAGE
OPEN DATASET VSAMFILE
IF $Status NE 0 THEN
PRINT $Errmsg
STOP
END IF
%KEYVAL = $READ('KEY VALUE = ')
PREPARE VSAM.REC
%VSAM.REC:KEY = %KEYVAL
READ IMAGE VSAM.REC FROM VSAMFILE KEY EQ %VSAM.REC:KEY.STR
.
.
.


==Close statement==

The <var>Close</var> statement lets the request close a sequential file, VSAM file, or a terminal opened by the request. 

====Syntax====

The format of the <var>Close</var> statement is:
Close {Dataset {ext-filename | %variable}
| External {ext-filename | %variable}
| [External] Terminal}

Where:
<ul>
<li>You must specify either the <var>Dataset</var>, <var>External</var>, or <var>Terminal</var> keyword.</li>

<li>The <var>Dataset</var> keyword specifies that the entity to be closed is a non-<var class="product">Model 204</var> file, that is, a sequential or VSAM file. </li>

<li>The <var>External</var> keyword specifies that the entity to be closed is a non-<var class="product">Model 204</var> file, that is, a sequential or VSAM file, or a terminal. </li>

<li><var class="term">ext-filename</var> specifies the name of the sequential or VSAM file to close, that is, the name used in the <var>Open</var> statement. Also, a %variable can provide the file name.</li>

<li><var>Terminal</var> specifies that the terminal currently opened by the <var>Open</var> statement should be closed. Also, a %variable can supply the word <var>Terminal</var>.
</li>
</ul>

===Closing a Model 204 file===

The <var>Close</var> statement can be used only for closing external files or terminals. To close a <var class="product">Model 204</var> file, you may use the <var>[[$Close]]</var> function within a <var class="product">User Language</var> request, or the <var>[[CLOSE command|CLOSE]]</var> command outside a request.

==IDENTIFY statement==

The IDENTIFY statement establishes: 
<ul>
<li>Active image, if multiple images define the same block.</li>
<li>Length of items that were defined as UNKNOWN.</li>
<li>Number of occurrences for arrays that were defined as UNKNOWN. </li>
</ul>

====Syntax====

The complete syntax for the IDENTIFY statement follows. The form of the IDENTIFY statement used to perform each of these activities is then discussed in detail.
IDENTIFY {[IMAGE] imagename
| %imagename:itemname LEN {n | %variable}
| {%imagename:arrayname | %imagename:itemname}
OCCURS {n | %variable}}

Where:
<ul>
<li><var class="term">imagename</var> refers to an image that was previously described in an image definition.</li>

<li><var class="term">%imagename</var>:<var class="term">itemname</var> is an item that was defined with LEN UNKNOWN or OCCURS UNKNOWN.</li>

<li>The LEN clause specifies the length in bytes of the item or a %variable that contains the length. The length cannot exceed 255 bytes. </li>

<li><var class="term">%imagename</var>:<var class="term">arrayname</var> is an array that was defined with OCCURS UNKNOWN.</li>

<li>The OCCURS clause specifies the number of occurrences of the item or a %variable that contains the number. The number of occurrences cannot exceed 32767.
</li>
</ul>

===Establishing an active image===

Use the following form of the IDENTIFY statement to switch the active image to the named imaged, when multiple images define the same block:
IDENTIFY [IMAGE] imagename


The IDENTIFY statement also initializes the items, if any, that were not initialized by a previous READ IMAGE or PREPARE statement. 
Note: Use the IDENTIFY statement instead of a PREPARE statement for requests in which you want to maintain data passed in an image.

====Use with global images====

When used with global images, the IDENTIFY IMAGE statement, can cause request termination due to either: 
<ul>
<li>Definition mismatches. See [[Global features#Consistency checks performed|Consistency checks performed]] for a description.</li>

<li>Insufficient space in GTBL. See the
<var class="book">[http://www.rocketsoftware.com/m204/products/model204/documentation/v7r4/M204-System-Mgr/view Rocket Model 204 System Manager's Guide]</var>.
</li>
</ul>

The IDENTIFY IMAGE statement does not refresh a global image, if a copy of that image is already in GTBL. The IDENTIFY IMAGE statement simply makes the specified image active. See [[Global features#Images and screen processing|Images and screen processing]] for a diagram showing the structure of GTBL followed by a discussion of performance considerations with respect to the definition of global objects.

===Establishing lengths for UNKNOWN items===

Use the following form of the IDENTIFY statement to set the length for items defined with LEN UNKNOWN:
IDENTIFY %imaginename:itemname LEN {n | %variable}


The location of an item is established when the length of every preceding variable length item and array is established. The length cannot be changed after it is defined by an IDENTIFY statement. If you must enlarge an array after the length is established, copy the image to another image where the array is larger using assignment statements.

===Establishing occurrences for UNKNOWN arrays===

Use the following form of the IDENTIFY statement to set the number of occurrences for arrays or items defined with OCCURS UNKNOWN:
IDENTIFY {%imagename:arrayname
| %imagename:itemname} OCCURS {n | %variable}


You cannot change the number of occurrences after they are defined by an IDENTIFY statement. If you issue an IDENTIFY statement for an item whose length was previously set by an IDENTIFY statement, the request is cancelled. 

You must issue a PREPARE statement before another IDENTIFY statement can be issued on the same item. If you need to enlarge an array after the number of occurrences is established, you must copy the image to another image where the array is larger using assignment.

==MODIFY BUFFER statement==

====Function====

Manages the Universal Buffer size and can also keep messages or overwrite them with a fill character.

====Syntax====
MODIFY BUFFER [SIZE=n | %variable [PRESERVE | NOPRESERVE]]
[FILL [X'nn' | C'x'] | CLEAR]

Where:
<ul>
<li>BUFFER (formerly and still accepted as MQ_BUFFER) specifies the Universal Buffer area. </li>

<li>SIZE specifies the number of bytes allocated for the BUFFER area. If the value of the SIZE option enlarges or shrinks the current buffer, the buffer contents are overwritten.</li>

<li>PRESERVE specifies to retain the buffer contents. If a storage allocation error occurs, the value of 8 is set in the $STATUS return code (which is the standard WebSphere MQ value for this error).

If the data was truncated when the buffer was shrunk, then the value of 14 for data truncation is set in $STATUS, although the operation succeeds.
</li>

<li>CLEAR option, the default, specifies to overwrite the buffer with X'00'.</li>

<li>FILL option specifies a fill-character to use; for example, X'40' fills with blanks. The FILL option can also be a decimal number and/or the equals sign (=), or it can be an alpha character (C) and/or the equals sign. If a value is not specified after the keyword FILL, the default value is the CLEAR option.

If the FILL or CLEAR option is specified, the behavior of MODIFY BUFFER statement depends on what other options are used:
<table>
<tr class="head">
<th>If... </th>
<th>Then...</th>
</tr>

<tr>
<td>FILL/CLEAR, SIZE, and NOPRESERVE are specified, or FILL is specified without SIZE </td>
<td>Entire buffer is filled with the fill character.</td>
</tr>

<tr>
<td>FILL/CLEAR, SIZE, and PRESERVE are specified </td>
<td>Fill character is used to fill the new portion of the buffer after the preserved data only if the buffer size is increased. </td>
</tr>
</table>
</li>
</ul>

====Usage====

The MODIFY BUFFER statement requires that you specify at least one option. 

When you overwrite the contents of BUFFER area, the value of $Buffer_Used is set to zero and the value of $Buffer_Position is set to one. See [[$Buffer_Size#$Buffer_Size|$Buffer_Size]] and [[$Buffer_Used#$Buffer_Used|$Buffer_Used]].

If you exceed the 2-gigabyte limit on the size of BUFFER, $STATUS returns a value of 34. A negative number or a number less than UBUFSZ is changed to UBUFSZ.

==OPEN statement==

The OPEN statement opens a sequential file, VSAM file, or terminal for processing. 

====DEFINE DATASET required====

Before a VSAM file or a DOS sequential file can be opened, it must previously have been
defined using the <var>[[DEFINE DATASET command|DEFINE DATASET]]</var> command. 

====Syntax====

The format of the OPEN statement is:
OPEN {[DATASET | EXTERNAL]
{ext-filename | %variable}
| [EXTERNAL] {TERMINAL | %variable}}
FOR {INPUT [OUTPUT] | OUTPUT [INPUT] | INOUT}
[PASSWORD {value | %variable}]

Where:
<ul>
<li>Either the DATASET or EXTERNAL keyword must be specified to open a sequential (non-<var class="product">Model 204</var>) file. DATASET and EXTERNAL should not be specified for opening <var class="product">Model 204</var> files. </li>

<li><var class="term">ext-filename</var> specifies the name of external file (that is, the sequential or VSAM file) to be opened. The external file name is the name specified in the DEFINE DATASET command or, for sequential files, the OS DDNAME or CMS FILEDEF. You can provide the external file name can be provided in a %variable.</li>

<li>TERMINAL specifies that the entity to be opened is a terminal. The word TERMINAL can be provided in a %variable. </li>

<li>The required FOR clause specifies the type of I/O processing that is performed on the opened external file or terminal. An external file or terminal must be at least opened for INPUT to be read into an image and opened for OUTPUT to write data from an image.

The INPUT OUTPUT, OUTPUT INPUT, and INOUT combination options are valid only for the TERMINAL keyword. 
</li>

<li>The PASSWORD clause is required for only password protected VSAM data sets. The clause generates an error when used with an OPEN TERMINAL statement, but is ignored in all other cases.

With the PASSWORD clause, the password can be specified directly or can be provided as the value of a %variable. Password validation is performed during evaluation and is not checked during compilation. 
</li>
</ul>

====Usage notes====

====OPEN statement in remote context====

This form of the OPEN statement is not supported in remote context. Using the AT keyword with any of the keywords DATASET, EXTERNAL, or TERMINAL generates the following error message, which is not displayed on the terminal, but can be retrieved with the $Errmsg function:
M204.1497: REMOTE SPECIFICATION CONFLICTS WITH OPEN TYPE


If the DATASET or EXTERNAL keyword is not specified and an entity is opened other than a terminal, <var class="product">Model 204</var> searches for the name of the file in the following order: 
<ol>
<li><var class="product">Model 204</var> temporary groups</li>
<li><var class="product">Model 204</var> permanent groups</li>
<li><var class="product">Model 204</var> files </li>
</ol>

This search order is consistent with the search order that <var class="product">Model 204</var> uses at command level for the OPEN command. 

====Opening non-Model 204 data sets from within procedures====

If a User Language procedure attempts to open an already open non-<var class="product">Model 204</var> data set at evaluation time, <var class="product">Model 204</var> softly restarts the user with the following counting error message:
M204.2153 DATASET name IS ALREADY OPEN


====Clearing messages====

An OPEN statement automatically clears $Fsterr and $Errmsg. You can also clear the messages accessed by $Fsterr and $Errmsg, using the $ErrClr function; for more details, see [[$ErrClr#$ErrClr|$ErrClr]].

==POSITION statement==

The POSITION statement specifies the next record to be read sequentially in a VSAM KSDS file. An established position is used by the READ NEXT statement to locate the next record to be returned. A new position can be established at any time by executing another POSITION statement. 

This POSITION statement is not to be confused with the POSITION statement used to recall a position in a found set or list which has been saved using the REMEMBER option during FOR loop processing. See [[Global features#POSITION statement|POSITION statement]].

====Syntax====

The format of the POSITION statement is:
POSITION {ext-filename | %variable}
AT KEY operator {value | %variable}

Where:
<ul>
<li><var class="term">ext-filename</var> is the name of the VSAM file specified in the OPEN statement. The name can be provided as the value of a %variable.

If <var class="term">ext-filename</var> is provided as a literal, it cannot be the name of a found set or list.
</li>

<li><var class="term">operator</var> specifies that the key of the record to be retrieved must be equal to or greater than or equal to the specified value. Valid operators are: =, >=, EQ, or GE.</li>

<li><var class="term">value</var> specifies the key at or beyond which the file is positioned for subsequent reads. The key can be provided as the value of a %variable.

If <var class="term">value</var> is a null string, a key of binary zeros is substituted. The first record in the file is returned if the operator is >= or GE. If the operator is = or EQ, a record is found only if it has a key of all binary zeros. 

If the length of <var class="term">value</var> is less than the length of the VSAM key, the key is treated as generic. A generic key search is satisfied when the value matches the same number of characters at the beginning of the VSAM key. The portion of the VSAM key that is longer than the value is ignored in the comparison.

If the VSAM key is not a character string, special handling is required. For information on how to specify the key when the key is not a string, refer to [[#Key field for VSAM files|Key field for VSAM files]]. 
</li>
</ul>

==PREPARE statement==

The PREPARE statement initializes an image and makes it the active image. This is required when image items are accessed prior to reading an external record into the image. PREPARE initializes the block associated with the image with the values specified in the INITIAL clauses of the item definitions or DEFAULT statements. 

Previous identifications of lengths of items defined as length UNKNOWN or number of occurrences of arrays defined with OCCURS UNKNOWN are lost. The IDENTIFY statement must be executed again to establish length or number of occurrences. 

====Syntax====

The format of the PREPARE statement is:
PREPARE [IMAGE] imagename


where <var class="term">imagename</var> refers to an image that was previously described in an image definition. The keyword IMAGE is required if imagename is IMAGE, MENU, or SCREEN.

===Use with global images===

The PREPARE IMAGE statement, when used with global images, can cause request termination due to either: 
<ul>
<li>Definition mismatches (see [[Global features#Consistency checks performed|Consistency checks performed]] for a description for global images)</li>

<li>Insufficient space in GTBL (see the
<var class="book">[http://www.rocketsoftware.com/m204/products/model204/documentation/v7r4/M204-System-Mgr/view Rocket Model 204 System Manager's Guide]</var>.
</li>
</ul>

==READ IMAGE statement==

====Purpose====

The READ IMAGE statement reads a record from a sequential or VSAM file or terminal into the image and sets the image as the active image. Or, the READ IMAGE statement reads the contents of the Universal Buffer. 

====Syntax====
READ [IMAGE] imagename FROM
[BUFFER [POSITION={%pvariable | n}]
{MAXLEN={%lvariable | n}]] |
[{ext-filename | TERMINAL | %variable}
[PROMPT {'text' | %variable}]
[NEXT | KEY operator {value | %variable}]]

Where:
<ul>
<li><var class="term">imagename</var> is an image that was previously described in an image definition. The keyword IMAGE is required if imagename is IMAGE, MENU, or SCREEN. <var class="term">imagename</var> also specifies a message to read in the Universal Buffer area.</li>

<li>The FROM clause determines which use of the READ IMAGE statement to employ:
<ul>
<li>Reading Large Object data from the Universal Buffer</li>
<li>Reading from a sequential file or the terminal</li>
</ul></li>

<li>BUFFER (formerly, and still accepted as MQ_BUFFER) specifies the Universal Buffer area.</li>

<li>POSITION must be in the range 1-16,777,216. If not, the operation returns $STATUS=10 and $STATUSD=20 return codes. <var class="term">%pvariable</var> or <var class="term">n</var> specifies where in the buffer to begin reading.

If POSITION=<var class="term">%pvariable</var> is specified and <var class="term">%pvariable</var> is greater than $Buffer_Used, the operation returns $STATUS=10 and $STATUSD=20.

The starting position in the buffer is determined by POSITION=<var class="term">%pvar</var>, if that was specified; $Buffer_Position, otherwise.

The ending position in the buffer is determined by the lowest of starting position, plus <var class="term">%lvariable</var>, if MAXLEN=<var class="term">%lvariable</var> was specified as the value of $Buffer_Used.
</li>

<li>MAXLEN=%lvariable specifies the maximum number of bytes to copy into the image. The actual number copied might be less than that, either because the number of bytes available in the BUFFER area (from the starting position) is less, or because the size of the image is less.

MAXLEN must be in the range 1-32,767. If not, the operation returns $STATUS=10 and $STATUSD=19.
</li>

<li><var class="term">ext-filename</var> specifies that records are read from a previously opened sequential or VSAM file. The name of the file can be provided as the value of a %variable.</li>

<li>TERMINAL specifies that records are read from the terminal. The word TERMINAL can be provided as the value of a %variable. </li>

<li>The optional PROMPT clause is used with only the TERMINAL option. It specifies to display a prompt sign before the READ is performed. Prompting is especially useful for synchronizing communication between the User Language request and Host Language program.

The PROMPT string can be as many as 255 characters. The string can be provided as a string type %variable.
</li>

<li>The NEXT option reads the next record in the file. NEXT is the default, if the KEY clause is omitted. A READ IMAGE statement with the NEXT option can be executed only following an OPEN, POSITION, or READ NEXT statement. </li>

<li>The KEY clause identifies the record to read. The KEY clause is valid only for VSAM files and the value is converted to a string. A READ IMAGE statement with the KEY clause automatically performs a RELEASE POSITION.

Key clause options are <var class="term">operator</var> and <var class="term">value</var>:
<ul>
<li><var class="term">operator</var> specifies that the key of the record to be retrieved must be equal to or greater than or equal to the specified value. Valid operators are: =, >=, EQ, or GE.</li>

<li><var class="term">value</var> is the key that locates the record. It can be supplied in a %variable.

If the value is a null string, a key of binary zeros is substituted. The first record in the file is returned, if the operator is >= or GE. If the operator is = or EQ, a record is found only if it has a key of all binary zeros. If the length of the value is less than the length of the VSAM key, the key is treated as generic. A generic key search is satisfied when the value matches the same number of characters at the beginning of the VSAM key. The portion of the VSAM key that is longer than the value is ignored in the comparison.
</li>
</ul>

If the VSAM key is not a character string, special handling is required. For information on how to specify the key when the key is not a string, refer to [[#Key field for VSAM files|Key field for VSAM files]]. 
</li>
</ul>

====Usage====

This statement is valid only if the file or terminal from which the record is read is currently open for INPUT, INPUT OUTPUT, or INOUT. READ IMAGE processing reads data until the Universal Buffer is exhausted, or the image is filled. 

The part of the message selected is copied from BUFFER area to the image:
<ul>
<li>Contents of the BUFFER area are unchanged.</li>

<li>$Buffer_Used is unchanged.</li>

<li>$Buffer_Position is set to the byte after the last byte copied.</li>

<li>No error indication is given, if the image is not big enough to hold the data.
</li>
</ul>

===BUFFER area positioning===

If POSITION is specified:
<ul>
<li>Numeric value, expressed as either a constant or variable, indicates where in the buffer to begin reading; the count starts from 1. </li>

<li>Beyond the end of the data, then the image is unchanged; READLEN is set to 0. </li>

<li>If the value is nonnumeric, less than one, or beyond the end of the data, then the statement fails with a nonzero $STATUS value.
</li>
</ul>

If the POSITION option is not specified:
<ul>
<li>Data is extracted from the buffer at the point where the last READ left off, or from the beginning of the buffer if this is the first READ after any other statement (including WebSphere MQ statements). </li>

<li>Once the buffer has been emptied, subsequent READ statements that do not specify POSITION set READLEN to 0, and leave the target image unchanged.
</li>
</ul>

After a READ IMAGE statement is issued, use the value of READLEN to determine how many bytes were actually copied. If no bytes were copied, READLEN=0.

The bytes in the image at offsets higher than the READLEN value are unchanged.

To determine the number of bytes remaining, use the following formula: 
bytes remaining = ($buffer_used - $buffer_position + 1)


===Record positioning===

If no position has been set prior to a READ NEXT, the position is assumed to be at the beginning of the file.

The record is positioned in the image according to the following rules:
<ul>
<li>If the record is longer than the image, the record is truncated.</li>

<li>If the record is smaller than the image, items beyond the end of the data are filled with the INITIAL value. An item that is partially filled by the input data is filled with the pad character for STRING and EFORMAT items and with binary zeros for BINARY, PACKED, ZONED, and FLOAT items.</li>

<li>When there are arrays with depending variables, each such array is filled with the number of elements specified in the depending variable. The remainder of the array is initialized according to the INITIAL clauses. The remaining data is move to the image following the array.</li>

<li>If the length of the image is unknown because items or arrays have length or number of occurrences specified as UNKNOWN, the block is filled with as much of the external record as fits in the remaining physical buffer space.
</li>
</ul>

===Length of the external record===

The length of the external record is stored in the variable <var class="term">%imagename</var>:READLEN. 

Previous identifications of lengths of items defined as length UNKNOWN or number of occurrences of arrays defined with OCCURS UNKNOWN are lost. The IDENTIFY statement must be executed again to establish length or number of occurrences. 

==RELEASE POSITION statement==

The RELEASE POSITION statement terminates a browse operation established by a POSITION statement. 

Execution of a RELEASE POSITION statement releases the VSAM string that maintains the current position in the file. The number of these strings is limited, and freeing the string as soon as the browse is finished allows other users to access the file.
Note: A POSITION statement automatically is released by another POSITION statement, a READ IMAGE statement with a KEY clause, a CLOSE statement, or the end of the request. 

====Syntax====

The format of the RELEASE POSITION statement is:
RELEASE POSITION {ext-filename | %variable}

Where:

<var class="term">ext-filename</var> is the name of the external file used in the POSITION statement. A %variable also can be used to supply the external file name. 

==WRITE IMAGE statement==

====Purpose====

The WRITE IMAGE statement loads data into the Universal Buffer or writes an active image to a sequential file or to the terminal.

====Syntax====

The format of the WRITE IMAGE statement is:
WRITE [IMAGE] imagename ON
[BUFFER [POSITION=%pvariable | n]
[MAXLEN={%lvariable | n}]]
| {seq-filename | TERMINAL | %variable}

Where:
<ul>
<li><var class="term">imagename</var> specifies a message to place in the message buffer.</li>

<li>The ON clause determines which use of the WRITE IMAGE statement to employ: writing to a sequential file or the terminal or writing Large Object data to the Universal Buffer.</li>

<li>BUFFER (formerly, and still accepted as MQ_BUFFER) specifies the Universal Buffer area.</li>

<li><var class="term">%pvariable</var> or <var class="term">n</var> specifies where in the buffer to start the placement.</li>

<li>POSITION must be in the range 1-16,777,216. If not, the operation returns $STATUS=10 and $STATUSD=20.

The starting position in the buffer is determined by:
<ul>
<li>POSITION=<var class="term">%pvariable</var>, if that was specified.</li>
<li>$Buffer_Position, otherwise.</li>
</ul></li>

<li>MAXLEN=<var class="term">%lvariable</var> specifies the maximum number of bytes to copy from the image. The actual number copied is less than <var class="term">%lvariable</var>, if the size of the image is less.

MAXLEN must be in the range 1-32,767. If not, the operation returns $STATUS=10 and $STATUSD=19. The amount of data to copy is determined by:
<table>
<tr class="head">
<th>If MAXLEN=%lvar is </th>
<th>Then copy...</th>
</tr>

<tr>
<td>Not specified </td>
<td>Current length of the image.</td>
</tr>

<tr>
<td>Specified </td>
<td>Lesser of %lvariable and the current length of the image.</td>
</tr>
</table>
</li>

<li><var class="term">seq-filename</var> specifies the name of the sequential file to which the image should be written. A %variable also can be used to supply the name of the sequential file.</li>

<li>TERMINAL specifies that the image should be written to the terminal. A %variable also can be used to supply the word TERMINAL.

If you specify the TERMINAL option on the WRITE IMAGE statement, data type translation is not performed for the terminal output. 
</li>
</ul>

====Usage====

The WRITE IMAGE statement is valid only if the file or terminal from which the record is read currently is open for OUTPUT, OUTPUT INPUT, or INOUT values. 
Note: When the WRITE IMAGE statement is used for a depending array, unused occurrences of the array are eliminated from the output.

If an MQPUT or MQPUT1 statement is issued with the BUFFER option, the buffer must contain a message, otherwise the operation fails with a nonzero $STATUS value.

If the last WebSphere MQ operation was a successful put or get, then an MQPUT or MQPUT1 statement with the BUFFER options puts the message most recently processed. In all other cases, at least one WRITE IMAGE imagename ON BUFFER statement must have been issued.
Note: Issue an MQPUT statement with the BUFFER option after a WRITE IMAGE imagename ON BUFFER statement, otherwise $STATUS indicates there is no data in the buffer.

====Image positioning====

The data in the image is loaded into the buffer. Where the data is placed in the buffer depends on whether the POSITION option was specified. 

If POSITION was not specified:
<ul>
<li>On the first such WRITE IMAGE after any other User Language statement or WebSphere MQ statement, the data is loaded starting in the first-byte position in the buffer.</li>

<li>On subsequent WRITE IMAGE statements, data is loaded immediately following the data from the most recent WRITE.
</li>
</ul>

If POSITION is specified as:
<ul>
<li>Numeric value, expressed as either a constant or variable that indicates where in the buffer to begin to place the data, then the count starts from 1. </li>

<li>Nonnumeric, less than one, or larger than the current size of the buffer, then the statement fails with a nonzero $STATUS value.
</li>
</ul>

The ending position in the buffer is determined by the starting position, plus the amount of data to copy.

If the size of the user's BUFFER area is less than the ending position, the existing BUFFER area is expanded to a size equal to the ending position (data within the BUFFER area is preserved).

The data is copied from the image to the BUFFER area:
<ul>
<li>$Buffer_Position is set to the byte after the last byte copied.</li>

<li>$Buffer_Used is set according to the following rule: if data was written past the previous $Buffer_Used point, then $Buffer_Used is the point written to by the WRITE IMAGE; otherwise, it is unchanged.
</li>
</ul>

==Error handling==

Error conditions encountered during the processing of image I/O statements — CLOSE, OPEN, POSITION, READ IMAGE, RELEASE POSITION, and WRITE IMAGE — generate <var class="product">Model 204</var> error messages that are not displayed on the terminal. 

The request should check for errors after the execution of each I/O statement by using the $Status function. The text of the most recently issued error message then can be retrieved by using the $Errmsg function. Refer to [[$ErrClr#$ErrClr|$ErrClr]] and [[$Status#$Status|$Status]] for more information. 

===$Status return codes===

The values that can be returned by $Status are listed below:
<table>
<tr class="head">
<th>Code </th>
<th>Description</th>
</tr>

<tr>
<td align="right">0</td>
<td>The operation was successful. A return code of 0 also clears the message buffer. Therefore, the $Errmsg function, if called, returns a null string.</td>
</tr>

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

Either an end of file was detected by a READ NEXT statement or a matching key was not found for the criteria specified in a READ KEY or POSITION statement. 

This code is only a warning; the request continues but cannot refer to the image before the next READ KEY or POSITION statement.
</td>
</tr>

<tr>
<td align="right">2</td>
<td>

A serious error has occurred such as an OPEN statement failure or an attempt to access an unopened file. The request continues, but the statement that generated the status code has not completed successfully. 

The failed statement cannot set an image active, resulting in the cancellation of the request if the image is referred to before being set active. 

The error that occurred can be retrieved by using the $Errmsg function to obtain the last counting or cancellation error message produced by <var class="product">Model 204</var>. 
</td>
</tr>
</table>

===Detecting ABEND codes in User Language===

When <var class="product">Model 204</var> intercepts an ABEND, the ABEND code and reason code are saved in the user's KOMM and can be accessed by the <var>[[$Status]]</var> and <var>[[$StatusD]]</var> $functions. The values of $Status and $StatusD are set as follows:
<table>
<tr class="head">
<th>$function</th>
<th>Value</th>
<th>Where</th>
</tr>

<tr>
<td>$Status</td>
<td>System ABEND code</td>
<td>System code is not zero</td>
</tr>

<tr>
<td>$Status</td>
<td>User ABEND code</td>
<td>User code is not zero</td>
</tr>

<tr>
<td>$Status</td>
<td>255 (X'FF')</td>
<td>ABEND code => X'F00'</td>
</tr>

<tr>
<td>$StatusD</td>
<td>Concatenated values of the $Status values:</td>
<td>

<var class="term">sss</var> is the system ABEND code

<var class="term">uuu</var> is the user ABEND code

<var class="term">rr</var> is the ABEND reason code
</td>
</tr>
</table>

If the ABEND is related to a communications I/O error, the SNA Communications Server (formerly VTAM), LU 6.2, or TCP/IP error routines set $Status and $StatusD with the result of the Terminal I/O and so override the ABEND code information.
Note: It is possible to get an ABEND code of all zeros. Some IBM system routines terminate with an ABEND U000 when they are invoked without APF authorization.

The ABEND code is not available in the z/VSE environment.

==Sample requests==

This section presents three examples illustrating the use of images in a request.

===Using the READ KEY facility===

The following request illustrates the use of the READ KEY facility. The printed record is the one with a VSAM key equal to a user-specified value.
BEGIN
IMAGE EMP.REC
CODE IS STRING LEN 8
JOB.DESC IS STRING LEN 50
NUM IS STRING LEN 7 DP *
END IMAGE
OPEN DATASET VSAMDS1 FOR INPUT
IF $STATUS NE 0 THEN
PRINT $Errmsg
STOP
END IF
PROMPT: %KEY = $READ('ENTER KEY')
IF %KEY = 'END' THEN
JUMP TO EXIT
END IF
READ IMAGE EMP.REC FROM VSAMDS1 KEY EQ %KEY
IF $STATUS EQ 1 THEN
PRINT 'RECORD NOT FOUND'
ELSEIF $STATUS EQ 2 THEN
PRINT $Errmsg
JUMP TO EXIT
ELSE
PRINT 'CODE = ' WITH %EMP.REC:CODE
PRINT 'JOB DESCRIPTION = ' WITH -
%EMP.REC:JOB.DESC
PRINT 'NUMBER = ' WITH %EMP.REC:NUM
END IF
JUMP TO PROMPT
EXIT: CLOSE DATASET VSAMDS1
END


The preceding request could be rewritten in the manner shown in Example 2 to print information from ten successive records of the VSAM file. 

===Using a POSITION statement===

The starting position in this example is established in the file through the use of the POSITION statement and a user-specified key.
BEGIN
IMAGE EMP.REC
CODE IS STRING LEN 8
JOB.DESC IS STRING LEN 50
NUM IS STRING LEN 7 DP *
END IMAGE
OPEN DATASET VSAMDS1 FOR INPUT IF $STATUS NE 0 THEN
PRINT $Errmsg
STOP
END IF
PROMPT: %KEY = $READ('ENTER KEY')
IF %KEY = 'END' THEN
JUMP TO EXIT
END IF
POSITION VSAMDS1 AT KEY GE %KEY
FOR %CT FROM 1 TO 10
READ IMAGE EMP.REC FROM VSAMDS1
IF $STATUS EQ 1 THEN
PRINT 'END OF FILE'
JUMP TO PROMPT
ELSEIF $STATUS EQ 2 THEN
PRINT $Errmsg
JUMP TO EXIT
ELSE
PRINT 'CODE = ' WITH %EMP.REC:CODE
PRINT 'JOB DESCRIPTION = ' WITH -
%EMP.REC:JOB.DESC
PRINT 'NUMBER = ' WITH %EMP.REC:NUM
END IF
END FOR
JUMP TO PROMPT
EXIT: CLOSE DATASET VSAMDS1
END


===Example===

The following request reads a sequential file that contains output from a previously issued PRINT ALL INFORMATION (PAI) statement. The foundset data is now in a data set. The request also handles non-PAI lines that might be found in the sequential file as separators; see the sample output that follows. The file being processed in this request contains PAI data for a CENSUS file.
BEGIN
IMAGE PAI
LINE IS STRING LEN 255
FIELDNAME IS STRING AT LINE LEN UNKNOWN
SKIP 3 POSITIONS
VALUE IS STRING LEN UNKNOWN
END IMAGE

OPEN DATASET OUTTAPE2 FOR INPUT
IF $STATUS EQ 1 THEN
JUMP TO DONE
ELSEIF $STATUS EQ 2 THEN
PRINT 'OPEN ERROR: ' WITH $Errmsg
STOP
END IF
READ: READ PAI FROM OUTTAPE2
IF $STATUS EQ 1 THEN
JUMP TO DONE
ELSEIF $STATUS EQ 2 THEN
PRINT 'READ ERROR: ' WITH $Errmsg
STOP
END IF
%A = $INDEX(%PAI:LINE,' = ')-1
IF %A GE 0 THEN
%B = %PAI:READLEN-%A-3
IDENTIFY %PAI:FIELDNAME LEN %A
IDENTIFY %PAI:VALUE LEN %B
PRINT 'FIELD=''' WITH %PAI:FIELDNAME WITH '''' -
WITH 'VALUE=''' AT 35 WITH %PAI:VALUE WITH ''''
ELSE
PRINT %PAI:LINE
END IF
JUMP TO READ
DONE: PRINT 'END OF INPUT FILE'
END


The preceding request generates output in the format illustrated below. (This is the recommended format for file reorganization, as discussed in [[File reorganization and table compaction]].)
*
FIELD='HOUSEHOLD ID' VALUE='53690'
FIELD='AGE' VALUE='21'
FIELD='OCCUPATION' VALUE='CLERK'
FIELD='SEX' VALUE='FEMALE'
FIELD='PLACE SIZE' VALUE='50000'
FIELD='RELATION' VALUE='UNRELATED'
FIELD='FATHERS BIRTHPLACE' VALUE='UNITED STATES'
FIELD='MOTHERS BIRTHPLACE' VALUE='UNITED STATES'
FIELD='BIRTHPLACE' VALUE='NORTH CENTRAL REGION'
FIELD='MOTHER TONGUE' VALUE='ENGLISH'
FIELD='SCHOOL' VALUE='4 YEARS HIGH SCHOOL'
FIELD='ROOMS' VALUE='GROUP QUARTERS'
FIELD='FAMILY SIZE' VALUE='NOT IN A FAMILY'
*
FIELD='HOUSEHOLD ID' VALUE='42860'
FIELD='AGE' VALUE='36'
FIELD='OCCUPATION' VALUE='SALESMAN'
FIELD='SEX' VALUE='MALE'
FIELD='PLACE SIZE' VALUE='50000'
FIELD='RELATION' VALUE='HEAD'
FIELD='FATHERS BIRTHPLACE' VALUE='UNITED STATES'
FIELD='MOTHERS BIRTHPLACE' VALUE='UNITED STATES'
FIELD='BIRTHPLACE' VALUE='SOUTHERN REGION'
FIELD='MOTHER TONGUE' VALUE='ENGLISH'
FIELD='SCHOOL' VALUE='1-3 YEARS COLLEGE'
FIELD='ROOMS' VALUE='4'
FIELD='FAMILY SIZE' VALUE='4'
END OF INPUT FILE


</div> 

[[Category:SOUL]]

$ERRCLR

2014-08-01T13:52:24Z

Mlarocca: Mlarocca moved page $ERRCLR to $ErrClr: Lower case change

#REDIRECT [[$ErrClr]]

$ErrClr

2014-08-01T13:52:24Z

Mlarocca: Mlarocca moved page $ERRCLR to $ErrClr: Lower case change

The $ERRCLR function clears the error message text returned by the $ERRMSG and $FSTERR functions. The $ERRCLR function takes no argument.
Example
%DUMMY=$ERRCLR

[[Category:SOUL $functions]]

ERRLEN parameter

2014-08-01T13:50:19Z

Mlarocca:

{{Template:ERRLEN parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>80
<dt>Parameter type
<dd>System
<dt>Where set
<dd>On User 0's parameter line and viewable only during system initialization
<dt>Related products
<dd>All
<dt>Introduced
<dd><var class="product">Model 204 V6.1</var> or earlier
</dl>
==Description==
The length of serious error messages saved for the VIEW ERRORS command
ERRLEN specifies the number of characters saved from the original messages. Each message is saved with an 18-character prefix, which is not included in ERRLEN.
==See also==
<ul>
<li>The [[ERRMSGL parameter]], which determines the length of errors returned by <var>[[$Errmsg]]</var> and <var>[[$Fsterr]]</var>.
</ul>
[[Category:System parameters]]
[[Category:Parameters]]

Data maintenance

2014-08-01T13:47:46Z

Mlarocca:

<div class="toclimit-3">

==Overview==

<var class="product">Model 204</var> data are maintained and updated with a variety of [[SOUL]] statements. This topic describes data maintenance statements and special conditions regarding their usage. 

===Data maintenance statements===

Use the following statements to perform basic data maintenance (record and field additions and updates):
<table>
<tr class="head">
<th>Statement </th>
<th> Action</th>
</tr>

<tr>
<td><var>ADD</var> </td>
<td>Place a new field-value pair on a record.</td>
</tr>

<tr>
<td><var>CHANGE</var> </td>
<td>Alter the value of fields in a record.</td>
</tr>

<tr>
<td><var>DELETE</var> </td>
<td>Remove fields from a record.</td>
</tr>

<tr>
<td><var>DELETE RECORD</var> </td>
<td>Remove a record from a <var class="product">Model 204</var> file; this statement reclaims space occupied by the deleted record.</td>
</tr>

<tr>
<td><var>DELETE RECORDS</var> </td>
<td>Remove sets of records from a <var class="product">Model 204</var> file; this statement executes faster than the DELETE RECORD statement but does not reclaim the space occupied by the deleted records.</td>
</tr>

<tr>
<td nowrap><var>FILE RECORDS UNDER</var> </td>
<td>Save retrieved or collected sets of record numbers for reference in later requests. </td>
</tr>

<tr>
<td><var>STORE RECORD</var> </td>
<td>Put a new record into a <var class="product">Model 204</var> file.</td>
</tr>

<tr>
<td><var>UPDATE RECORD </var></td>
<td>Perform a series of field-level updates in a single call. This statement is intended for use with <var class="product">Parallel Query Option/204.</var></td>
</tr>
</table>

====Example data====

Each statement is discussed separately in the sections that follow. To illustrate their usage, assume that the following two records have been stored:
VIN = A99999998E VIN = X99999999Z
MAKE = FORD MAKE = FORD
COLOR = GREEN COLOR = RED
YEAR = 88 YEAR = 04
MODEL = FOCUS MODEL = MUSTANG


===Using For Each Record loops===

The SOUL data maintenance statements handle one record at a time, therefore the data maintenance statements are always part of a <var>For Each Record</var> loop. The data maintenance may involve a field-value pair for the field.

==ADD statement==

The <var>ADD</var> statement adds a new occurrence of a field and/or value to a record.

====Syntax====

The basic format of the ADD statement is:
ADD fieldname = {value | (expression)}


Where:
<ul>
<li>fieldname identifies the field in a record.</li>

<li>value specifies the value you want to store.</li>

<li>(expression) can be used in place of value to specify the resolved value at the time of evaluation. (expression) can be a function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string.</li>
</ul>

Note: For Large Object data in <var class="product">Model 204</var> V7.5 and later, a file must be defined with the <var>[[FILEORG parameter|FILEORG]]</var> X'100' bit in order to use the above syntax. With LOB fields, the assigned value is typically held in a <var>[[Longstrings|Longstring]]</var> variable. [[Large Object field processing for non-FILEORG X'100' files|In non-FILEORG X'100' files, a special syntax must be used to ADD a LOB field.]]

====Example====

Referring to the two sample stored records (see [[#Data used in examples in this topic|Data used in examples in this topic]]), this request:
BEGIN
FIND.RECS: FIND ALL RECORDS FOR WHICH
MAKE = FORD
BODY IS NOT PRESENT
END FIND
FOR EACH RECORD IN FIND.RECS
ADD BODY = 2DR
END FOR
END


would change the records to:
VIN = A99999998E VIN = X99999999Z
MAKE = FORD MAKE = FORD
COLOR = GREEN COLOR = RED
BODY = 2DR BODY = 2DR
YEAR = 98 YEAR = 04
MODEL = FOCUS MODEL = MUSTANG


====Usage====
<ul>
<li>The <var>ADD</var> statement places an additional occurrence of a field-value pair on the record.</li>

<li>You can use the <var>ADD</var> statement to add any field to a record except for a sort or hash key field. You can use this statement only within a <var>FOR EACH RECORD</var> loop.</li>

<li>The <var>ADD</var> statement is supported in remote file and scattered group contexts.</li>

<li>To use the <var>ADD</var> statement with multiply occurring fields, see the [[Operations on multiply occurring fields#ADD statement|ADD statement for multiply occurring fields]]. </li>

<li>To add a field whose value you do not explicitly specify, see [[#Using VALUE IN to reference a NOTE value|Using VALUE IN to reference a NOTE value]], below. </li>

<li>For Large Object data in non-[[FILEORG parameter|FILEORG X'100']] files, a compiler error is issued for <var>ADD</var> (and <var>STORE</var>) statements if the context to the right of the equal sign (<tt>=</tt>) is not a <var>BUFFER</var> reference:
M204.0037: INVALID SYNTAX
</li>
</ul>

==CHANGE statement==

The <var>CHANGE</var> statement alters a record by adding a field and value pair, or altering the value of an existing field within a record. 

====Syntax====

The basic format of the <var>CHANGE</var> statement is: 
CHANGE fieldname [= value |(expression)] TO (newvalue |(expression))


Where:
<ul>
<li><var class="term">fieldname</var> specifies the name of the field to add to the record, or identify the field where the value is changed.</li>

<li><var class="term">value</var> is required only if the field has the INVISIBLE attribute. See the discussion on the [[Field attributes#INVISIBLE attribute|INVISIBLE attribute]]. </li>

<li><var class="term">newvalue</var> specifies the value that overwrites the existing value for the field.</li>

<li>(<var class="term">expression</var>) is resolved by the expression compiler and overwrites the existing value for the field. (<var class="term">expression</var>) can be a function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string. </li>
</ul>

Note: For Large Object data in <var class="product">Model 204</var> V7.5 and later, a file must be defined with the <var>[[FILEORG parameter|FILEORG]]</var> X'100' bit in order to use the above syntax. With LOB fields, the assigned value is typically held in a <var>[[Longstrings|Longstring]]</var> variable. In non-FILEORG X'100' files, [[Large Object field processing for non-FILEORG X'100' files|a special syntax must be used to CHANGE a LOB field.]]

====Usage====
<ul>
<li>You can use the <var>CHANGE</var> statement to change any field in a record except for a sort or hash key field. </li>

<li>You can use this statement only within a <var>FOR EACH RECORD</var> loop. </li>

<li>The <var>CHANGE</var> statement is supported in remote file and scattered group contexts.</li>

<li>If a <var>CHANGE</var> statement is applied to a record that does not contain the field to be changed, the specified field name and value are added to the record. </li>

<li>To use the <var>CHANGE</var> statement with multiply occurring fields, see the [[Operations on multiply occurring fields#CHANGE statement|CHANGE statement for multiply occurring fields]]. </li>

<li>To change a field whose value you do not explicitly specify, see [[#Using VALUE IN to reference a NOTE value|Using VALUE IN to reference a NOTE value]], below. </li>
</ul>

==DELETE statement==

The <var>DELETE</var> statement removes fields from a record. 

====Syntax====

The format of the <var>DELETE</var> statement is:
DELETE fieldname [= value | (expression)]


Where:
<ul>
<li><var class="term">fieldname</var> specifies the name of the field to remove from the record.</li>

<li><var class="term">value</var> is required only if the field has the <var>INVISIBLE</var> attribute. (See the discussion in [[Field attributes]].) </li>

<li>(<var class="term">expression</var>) can be used in place of value to specify the resolved value at the time of evaluation. (<var class="term">expression</var>) can be a function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string.</li>
</ul>

====Example====

This request directs <var class="product">Model 204</var> to remove the field <code>BODY</code> from the records retrieved by the <code>FIND.RECS</code> statement:
BEGIN
FIND.RECS: FIND ALL RECORDS FOR WHICH
VIN = A99999998E OR X99999999Z
END FIND
FOR EACH RECORD IN FIND.RECS
DELETE BODY
END FOR
END


The records then appear as:
VIN = A99999998E VIN = X99999999Z
MAKE = FORD MAKE = FORD
COLOR = BLUE COLOR = BLUE
YEAR = 98 YEAR = 04
MODEL = FOCUS MODEL = MUSTANG


====Usage====
<ul>
<li>You can use the <var>DELETE fieldname</var> statement on any field in a record except for a sort or hash key field. This statement can be used only within a <var>FOR EACH RECORD</var> loop. </li>

<li>If the <var>DELETE fieldname</var> statement is applied to a record that does not contain the field to be deleted, no action is taken on that record. </li>

<li>The <var>DELETE fieldname</var> statement is supported in remote file and scattered group contexts.</li>

<li>The <var>DELETE fieldname</var> statement supports Large Object data. Processing this statement frees the Table B and Table E data.</li>

<li>To use with multiply occurring fields, see [[Operations on multiply occurring fields#DELETE statement|Deleting multiply occurring fields]]. </li>

<li>To use with field groups, see [[Operations on multiply occurring fields#Deleting a field group|Deleting a field group]]. </li>

<li>For information about space recovered from deletions and about attempting to delete missing records, see [[#Deleting fields and records|Deleting fields and records]], below.</li>
</ul>

==DELETE RECORD statement==

The <var>DELETE RECORD</var> statement removes a record or sets of records from a <var class="product">Model 204</var> file. 

===Syntax===

The format of the <var>DELETE RECORD</var> statement is:
DELETE RECORD


===Example===

This request deletes all records found by the <var>FIND</var> statement: 
BEGIN
FIND.RECS: FIND ALL RECORDS FOR WHICH
MAKE = FORD
YEAR = 96
END FIND
FOR EACH RECORD IN FIND.RECS
DELETE RECORD
END FOR
END


===Usage===
<ul>
<li>When you delete records with the <var>DELETE RECORD</var> statement, the space those records occupy may be reclaimed depending on the file order. For more information on reclaiming space, refer to [[#Reused space|Reused space]]. </li>

<li>You can use this statement only inside a <var>FOR EACH RECORD</var> loop.</li>

<li>The <var>DELETE RECORD</var> statement is supported in remote file and scattered group contexts. </li>

<li>For information about space recovered from deletions and about attempting to delete missing records, see [[#Deleting fields and records|Deleting fields and records]], below.</li>
</ul>

====Limitation of the date-time stamp feature deleting records====

The [[Adding a date-time stamp field#Overview of the date-time stamp feature|date-time stamp feature]] does not include support for <var>DELETE RECORD</var> or <var>DELETE RECORDS</var> processing. <var>DELETE RECORD</var> or <var>DELETE RECORDS</var> processing must be handled by your application software.

As well, you can use logical delete techniques. However, in all forms of deleting records, it is your responsibility to maintain a log of record deletions, if you want one.

==DELETE ALL RECORDS statement==

The <var>DELETE ALL RECORDS</var> statement deletes sets of records from a <var class="product">Model 204</var> file. 

===Syntax===

The forms of this statement are:
DELETE [ALL] RECORDS IN label

DELETE [ALL] RECORDS ON [LIST] listname

<ul>
<li><var>DELETE ALL RECORDS IN</var> deletes a set of records located by a <var>FIND</var> statement. </li>

<li><var>DELETE ALL RECORDS ON LIST</var> deletes the set of records on the named list from the file.
</li>
</ul>

===Example===

This request deletes the set of records located by the <var>FIND</var> statement:
BEGIN
FIND.RECS: FIND ALL RECORDS FOR WHICH
MAKE = FORD
YEAR = 00
END FIND
DELETE ALL RECORDS IN FIND.RECS
END


===Usage===
<ul>
<li>The <var>DELETE ALL RECORDS</var> statement initiates fewer internal operations and therefore executes faster than the <var>DELETE RECORD</var> statement. However, use the <var>DELETE RECORD</var> statement rather than <var>DELETE ALL RECORDS</var> for records with <var>ORDERED</var> or <var>UNIQUE</var> fields, to ensure that values in the Ordered Index accurately reflect the contents of the data stored in Table B.

In addition, when records are deleted with <var>DELETE ALL RECORDS IN</var>, the space they occupy is not reclaimed. When it is desirable to reclaim space to expand existing records or to insert new records, use the <var>DELETE RECORD</var> statement. </li>

<li>The <var>DELETE ALL RECORDS</var> statement is supported in remote file and scattered group contexts.</li>

<li>For information about space recovered from deletions and about attempting to delete missing records, see [[#Deleting fields and records|Deleting fields and records]], below.</li>
</ul>

==Deleting fields and records==

This section expands on the detail of use for the <var>DELETE</var> statements. Some general issues related to deleting fields and records are presented.

===Reused space===

Space recovered from both record and field deletions is always used to expand existing records that are near the deletions, regardless of which file option is selected.
<var class="product">Model 204</var> inserts new records in space recovered from deleted records only on unordered or hash files, or on sort files for which the <var>Reuse Record Number</var> option of the <var>[[FILEORG parameter|FILEORG]]</var> parameter is set active. 

If the <var>Reuse Record Number</var> option is active for an unordered, hash, or sort file, you must explicitly delete any <var>INVISIBLE</var> fields associated with a record in the file when deleting the record itself. If an <var>INVISIBLE</var> field is not deleted, it becomes part of any new record that is put into the old record's space. 

===Deleting from a record list===

Error messages might be generated when a <var>FOR EACH RECORD</var> loop is performed on a list of records from which some of the records have been deleted from the file. For example:
BEGIN
*
* FIND ALL STATE CONTROL RECORDS
*
STATES: FIND ALL RECORDS FOR WHICH
REC = STATE
END FIND
PLACE RECORDS IN STATES ON LIST FOUND
*
* EXCLUDE MASS. AND N.H. BECAUSE
* THEIR SURCHARGE RATE HAS NOT CHANGED
*
REMOVE: FIND ALL RECORDS ON LIST FOUND FOR WHICH
STATE CODE = MA OR NH
END FIND

FOR EACH RECORD IN REMOVE
DELETE RECORD
END FOR
*
* CHANGE SURCHARGE RATE FOR ALL OTHER STATES
*
SURCHARGE: FOR EACH RECORD ON LIST FOUND
CHANGE SURCHARGE RATE TO .50
END FOR
END


This request would produce these messages:
*** M204.1266: NONEXISTENT RECORD REFERENCED - 23 IN FILE INSURE
*** M204.1266: NONEXISTENT RECORD REFERENCED - 24 IN FILE INSURE


Depending upon the intent of the request, these messages may or may not indicate an error. 

==FILE RECORDS statement==

The <var>FILE RECORDS</var> statement files a set of records that were retrieved by a <var>FIND</var> statement or that were collected on a list. You can reference the set of records in later requests. 

===Syntax===

The forms of this statement are:
FILE RECORDS IN label UNDER fieldname = value

FILE RECORDS IN label UNDER fieldname = (expression)

FILE RECORDS ON [LIST] listname UNDER fieldname = value


===Usage===
<ul>
<li>The <var>FILE RECORDS</var> statement adds one of these pairs to the specified records:
fieldname = value

fieldname = (expression)
</li>

<li>The <var>FILE RECORDS</var> statement is supported in remote file and scattered group contexts.</li>

<li>The field used in a <var>FILE RECORDS</var> statement must have the <var>INVISIBLE KEY</var> or <var>INVISIBLE ORDERED</var> field attributes. Refer to [[Field attributes]] for more information.

In addition, the <var class="term">fieldname</var> = <var class="term">value</var> pair should be unique in the file. If the pair has appeared previously in other records, either by explicit field creation or by a previous <var>FILE RECORDS</var> statement, inconsistencies in the file can occur. The <var>FILE RECORDS</var> statement creates new index entries for the
<var class="term">fieldname</var> = <var class="term">value</var> pair, eliminating existing references.
Note: The index update generated by a <var>FILE RECORDS UNDER</var> statement is never deferred.</li>

<li>The <var class="term">expression</var> in the syntax above is enclosed in parentheses and is one of following expression types: function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression.</li>
</ul>

====Example of using an expression====
B
%REC IS STRING LEN 3
%CT IS FLOAT
%VAL1 IS FLOAT
%VAL2 IS FLOAT
%REC = 'REC'
FOR %CT FROM 1 TO 10
IN EXPRESS STORE RECORD
ORD1 = (%REC WITH %CT)
ORD2 = (%CT * 2)
ORD4 = (%CT * 4)
END STORE
COMMIT
FD1:
IN EXPRESS FD ORD1 EQ VALUE(%REC WITH %CT)
END FIND
FR FD1
CHANGE ORD2 TO (%CT * 2.1)
ADD ORD3 = (%CT * 3)
CHANGE ORD4 = (%CT * 4 ) TO (%CT * 4.1)
DELETE ORD3 = (%CT * 3)
INSERT ORD4 = (%CT * 5)
END FOR
FILE RECORDS IN FD1 UNDER INVORD5 = (%REC WITH %CT)
END FOR
PRINT 'FRV1'
FRV1:
IN EXPRESS FRV INVORD5
FD2:
IN EXPRESS FD INVORD5 = VALUE IN FRV1
END FIND
CT2:
CT FD2
PRINT VALUE IN FRV1 AND COUNT IN CT2
END FOR
END


====Locating filed record sets====

<var>FIND</var> statements in later requests can locate the filed set of records by using the <var class="term">fieldname</var> = <var class="term">value</var> pair as the retrieval condition. For example, if a set of records were filed with the statement:
SAVE.RECS: FILE RECORDS IN FIND.RECS UNDER SAVE = 1


Then to locate the records again, you use the following statement in the same request or in a later one:
GET.RECS: FIND ALL RECORDS FOR WHICH SAVE = 1


====Using lists for filed record sets====

Two sets of records retrieved by different <var>FIND</var> statements can be filed together under the same <var class="term">fieldname</var> = <var class="term">value</var> pair only if both sets are first placed on a list, and then the list is filed by one statement, as in the following: 
BEGIN
FIND.RECS: FIND ALL RECORDS FOR WHICH
STATE = VIRGINIA
AGENT = DOYLE
END FIND
SAVE.DOYLE: PLACE RECORDS IN FIND.RECS ON LIST COMPLIST
FIND.T3S: FIND ALL RECORDS FOR WHICH
STATE = VIRGINIA
INCIDENT = T3
END FIND
PLACE RECORDS IN FIND.T3S ON LIST COMPLIST
SAVE.LIST: FILE RECORDS ON LIST COMPLIST UNDER SAVE = T3S
END


If the <code>SAVE.DOYLE</code> statement were replaced with:
SAVE.DOYLE: FILE RECORDS IN FIND.RECS UNDER SAVE = T3S


the original references to <code>SAVE = T3S</code> would be lost as soon as the <code>SAVE.LIST</code> was executed. Thus, a second use of the same <var class="term">fieldname</var> = <var class="term">value</var> pair replaces the previous one.

====Simulating the FILE RECORDS UNDER statement====

You can simulate the <var>FILE RECORDS</var> statement by explicitly adding a <var class="term">fieldname</var> = <var class="term">value</var> pair to a set of records. For example, if the <code>SAVE.LIST</code> statement in the previous example is replaced by:
SAVE.LIST: FOR EACH RECORD ON LIST COMPLIST
ADD SAVE = T3S
END FOR


Then the index references to existing records that contain that <var class="term">fieldname</var> = <var class="term">value</var> pair are not invalidated. You are responsible for deleting such references, if deletion is desired. 

==STORE RECORD statement==

The <var>STORE RECORD</var> statement is used to add new records to a <var class="product">Model 204</var> file. The <var class="term">fieldname</var>=<var class="term">value</var> pairs that constitute the new record must follow the <var>STORE RECORD</var> statement, one to a line, and must not be labeled. 

===Syntax===

The format of the <var>STORE RECORD</var> statement is: 
STORE RECORD
fieldname =[value1 | (expression1)]
[fieldname2=[value2 | (expression2)]]
...
[THEN CONTINUE
statement
statement
...]
END STORE [label]


Where:
<ul>
<li>(<var class="term">expression</var>) can be a function call, string concatenation, arithmetic operation, SOUL construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string.</li>

<li><var>THEN CONTINUE</var> maintains the record context of the <var>STORE RECORD</var> statement, while allowing additional work to happen on the record. <var>THEN CONTINUE</var> is useful for adding variable numbers of multiply occurring fields, and it is required syntax for adding fieldgroups inside a <var>STORE</var> statement.</li>
</ul>

===Examples===
BEGIN
STORE RECORD
NAME = JEAN ANDERSON
SALARY = 30000
POSITION = CHEMIST
END STORE
END


Using the THEN CONTINUE statement
%COLOR = 'BLUE'
STORE RECORD
MODEL = %MODEL
THEN CONTINUE
FR WHERE RECTYPE = 'TABLE' AND COLOR = %COLOR
%CODE = COLOR_CODE
END FOR
ADD COLOR_CODE=%CODE
PAI
END STORE


===Usage===
<ul>
<li>Use an <var>END STORE</var> statement or another label to end the <var>STORE RECORD</var> statement. Do not end a <var>STORE RECORD</var> statement with an <var>END BLOCK</var> statement. </li>

<li>This form of the <var>STORE RECORD</var> statement is used to add new records to any file that does not have the sorted or hashed option.</li>

<li>The <var>STORE RECORD</var> statement is supported in remote file and scattered group contexts.</li>

<li>To store a field whose value you do not explicitly specify, see [[#Using VALUE IN to reference a NOTE value|Using VALUE IN to reference a NOTE value]], below. </li>

<li>The <var>THEN CONTINUE</var> statement allows for the conditional building of a <var class="product">Model 204</var> record. You can use any intervening statements after <var>THEN CONTINUE</var> and before <var>END STORE</var>.

The statements following the <var>THEN CONTINUE</var> statement of the <var>STORE RECORD</var> block operate as if they were coded within a <var>FRN $Currec</var> block, which immediately follows the <var>END STORE</var> statement. This is easier for coding because you do not need to repeat the file specification of the <var>STORE RECORD</var> statement. It is also more efficient because an actual <var>FRN</var> statement is not necessary.</li>
</ul>

====Large Object storage====

[[Field design#BLOB, CLOB, and MINLOBE attributes|Binary Large Objects]] — fields defined with a <var>BLOB</var> or <var>CLOB</var> attribute (often referred to collectively as LOBs) — are stored in Table E, and they can hold content longer than the 255 limit of regular <var class="product">Model 204</var> fields. They are useful for holding blocks of text, images, documents, etc. 

Note: Prior to the <var class="product">Model 204</var> version 7.5 introduction of the [[FILEORG parameter|FILEORG X'100']] bit, LOB fields required a special <var>STORE</var> syntax referencing the "universal buffer." This pre-V7.5 syntax is documented in [[Large Object field processing for non-FILEORG X'100' files]].

As of <var class="product">Model 204</var> V7.5, LOB fields can be stored using normal <var>STORE</var> syntax, typically with a [[Longstrings|Longstring]] variable holding the content:

B
%REC IS STRING LEN 3
%CT IS FLOAT
%VAL1 IS FLOAT
%VAL2 IS FLOAT
%REC = 'REC'
FOR %CT FROM 1 TO 10
IN EXPRESS STORE RECORD
ORD1 = (%REC WITH %CT)
ORD2 = (%CT * 2)
ORD4 = (%CT * 4)
END STORE
COMMIT
FD1:
IN EXPRESS FD ORD1 EQ VALUE(%REC WITH %CT)
END FIND
FR FD1
CHANGE ORD2 TO (%CT * 2.1)
ADD ORD3 = (%CT * 3)
CHANGE ORD4 = (%CT * 4 ) TO (%CT * 4.1)
DELETE ORD3 = (%CT * 3)
INSERT ORD4 = (%CT * 5)
END FOR
END FOR
END


When you store an instance of a Large Object field, the value of the data is stored in the file's Table E. Additionally, a LOB descriptor containing a pointer to the value in Table E, as well as other items, are stored in the record data in a Table B entry. The LOB descriptor is 27 bytes in length, plus the 1-byte length and 2-byte field code that apply to all fields — unless the field is preallocated.
See [[File Load utility#Building a Large Object descriptor|Building a Large Object descriptor]]
for a description of how to build a Large Object data descriptor.

The following compiler error is issued when the right side of the equal sign is expected to contain a <var>BUFFER</var> expression and it does not.
M204.0037: INVALID SYNTAX


====Sort or hash key files====

If you are adding a record to a file that has the sort or hash option, the sort or hash key value follows the <var>STORE RECORD</var> on the same line, as shown below: 
STORE RECORD [sort-or-hash-key-value]


The sort or hash key must be provided if the <var>FILEORG</var> parameter was set to indicate that the sort or hash key is required in every record. 

For example, the request to store a record in a file that requires the vehicle identification number as the sort key can be written:
BEGIN
STORE RECORD A99999998E
MAKE = FORD
COLOR = GREEN
YEAR = 98
MODEL = FOCUS
END STORE
END


When this record is stored, the field <code>VIN = A99999998E</code> is added to it. 

You can also specify the sort or hash key as an expression:

IN TEST1 STORE RECORD (expression)
...
END STORE


Where: 

(<var class="term">expression</var>) is the sort or hash key. (<var class="term">expression</var>) can be a function call, string concatenation, arithmetic operation, User Language construct, or Boolean expression. The expression must be enclosed in parentheses to invoke the expression compiler; otherwise the value will be treated as a literal string.

====Files with a UNIQUE field====

If a record is added to the file that has a <var>UNIQUE</var> field, and a uniqueness conflict is detected during the <var>STORE RECORD</var> processing, the partially stored record is backed out. For files without the <var>Reuse Record Number</var> (<var>RRN</var>) option, this results in the use of a record number which cannot be reclaimed. 

====IN GROUP MEMBER clause====

You can use the <var>IN GROUP MEMBER</var> clause to restrict the <var>STORE RECORD</var> statement to one member file in a group context. See [[Files, groups, and reference context#IN GROUP MEMBER clause|IN GROUP MEMBER clause]] for more information.

====FIND ALL VALUES options====

Like other <var>FIND</var> statements, you can specify a range of values for the <var>FIND ALL VALUES</var> statement by using the <var>FROM</var> and <var>TO</var> clauses. 

In addition, you can select values based upon a pattern by using the <var>LIKE</var> clause. 

====Storing field groups (FIELDGROUP)====

Introduced with <var class="product">Model 204</var> version 7.5, field groups add a formalized internal structure for sets of repeating fields — for instance, a set of children and their birthdays would automatically associate the second birthday with the second child. With regular repeating fields, the programmer must be very careful: If, for instance, an occurrence of a birthday field is deleted, the correct occurrence of the associated child must also be deleted, or else the repeating values become out-of-sync. Field groups take care of this housekeeping by associating a set of fields with an internal field group ID.

Field groups can be added, changed, and deleted on a record after the record is created, but storing them on the initial <var>STORE RECORD</var> statement requires the use of <var>THEN CONTINUE</var>. The following example demonstrates this, both for fieldgroups and for nested fieldgroups (a fieldgroup contained inside another fieldgroup). Take this set of field definitions:

IN FILE LIBRARY DEFINE FIELDGROUP BOOK
IN FILE LIBRARY DEFINE FIELDGROUP CHAPTER WITH FG BOOK
IN FILE LIBRARY DEFINE FIELD RECTYPE WITH ORD CHAR
IN FILE LIBRARY DEFINE FIELD AUTHOR_FIRSTNAME WITH ORD CHAR
IN FILE LIBRARY DEFINE FIELD AUTHOR_LASTNAME WITH ORD CHAR
IN FILE LIBRARY DEFINE FIELD BOOK_TITLE WITH ORD CHAR EXACTLY-ONE FG BOOK
IN FILE LIBRARY DEFINE FIELD BOOK_SUBTITLE WITH ORD CHAR EXACTLY-ONE FG BOOK
IN FILE LIBRARY DEFINE FIELD BOOK_ISBN WITH ORD CHAR EXACTLY-ONE FG BOOK
IN FILE LIBRARY DEFINE FIELD BOOK_PRICE WITH AT-MOST-ONE FG BOOK
IN FILE LIBRARY DEFINE FIELD BOOK_READERCOMMENT WITH REPEATABLE FG BOOK
IN FILE LIBRARY DEFINE FIELD CHAPTER_NO WITH REPEATABLE FG CHAPTER
IN FILE LIBRARY DEFINE FIELD CHAPTER_TITLE WITH REPEATABLE FG CHAPTER


Note that the fieldgroup <code>CHAPTER</code> is defined with an attribute of fieldgroup <code>BOOK</code>, which causes <code>CHAPTER</code> to be nested inside <code>BOOK</code>. To add records to this file, a <var>STORE RECORD</var> statement stores a base record, and then fieldgroups are added inside a <var>THEN CONTINUE</var> clause:

in file library store record
rectype = 'AUTHOR'
author_firstname = 'Jane'
author_lastname = 'Austen'
then continue
add fieldgroup book
book_title = 'Sense and Sensibility'
book_subtitle =
book_isbn = %isbn(%x)
book_price = %price(%x)
book_readercomment = 'Loved it. Better than "Cats". Mom'
book_readercomment = 'An inspired, blistering novel. The New York Times'
book_readercomment = 'Excellent! GB Shaw'
then continue
add fieldgroup chapter
chapter_no = 1
chapter_title = 'The Dashwoods of Sussex'
end add
add fieldgroup chapter
chapter_no = 2
chapter_title = 'Mrs. John Dashwood'
end add
add fieldgroup chapter
chapter_no = 3
chapter_title = 'Freddy and Elinor'
end add
end add
add fieldgroup book
book_title = 'Pride and Prejudice'
book_subtitle =
book_isbn = %isbn(%y)
book_price = %price(%y)
book_readercomment = 'Brief. Encountery. Mom'
book_readercomment = 'Would love to snap up the movie rights. H. Smidkin'
then continue
add fieldgroup chapter
chapter_no = 1
chapter_title = 'A Truth Universally Acknowledged'
end add
add fieldgroup chapter
chapter_no = 2
chapter_title = 'Waiting on Mr. Bingley'
end add
end add
end store

Note:
In the above example there is no specific "end" statement for the <var>THEN CONTINUE</var> statements. Rather, the context for the continue ends when the containing context ends. In the case above, the context of the outermost <var>THEN CONTINUE</var> is the <var>STORE RECORD</var> statement, which is being continued in order to provide <var>ADD FIELDGROUP</var> statements for field group <code>BOOK</code>. The context for the inner <var>THEN CONTINUE</var> statements — used to add <code>CHAPTER</code> field groups — is the <var>ADD FIELDGROUP</var> statement above it. After adding <code>CHAPTER</code> information for a <code>BOOK</code>, that block is ended with <var>END ADD</var>, and <var>STORE RECORD</var> context returns, where if needed, another <code>BOOK</code> field group can be added.

====Nested STORE RECORD statements====

The <var>THEN CONTINUE</var> block allows for the coding of a nested <var>STORE..END STORE</var> block within the body of the outer <var>STORE</var>, so that related records may be built together. A nested <var>STORE</var> can refer to a different file context, without compromising the file context of the outer <var>STORE</var>. 

The following example stores an order header record along with an order line record:
IN ORDHDR STORE RECORD
ORDER_NUMBER = 1000568
CUSTOMER_NUMBER = 111456
THEN CONTINUE
IN ORDLINE STORE RECORD
ORDER_NUMBER = 1000568
ITEM_ID = F004
ITEM_QTY = 3
END STORE
ADD ORDER_STATUS = A
END STORE
...


The results of this would be the following record stored in the <code>ORDHDR</code> file:
ORDER_NUMBER = 1000568
CUSTOMER_NUMBER = 111456
ORDER_STATUS = A


and the following record stored in the <code>ORDLINE</code> file:
ORDER_NUMBER = 1000568
ITEM_ID = F004
ITEM_QTY = 3


====Multiply occurring fields====

In the following example, a <var>For Each Occurrence</var> loop is driven, based on occurrences of the field <code>SALES_MM</code> previously stored, to store occurrences of <code>MONTHLY_TOTAL</code>:
B
%MONTHLY_SALES IS FLOAT ARRAY (3)
%MONTHLY_SALES(1) = 10
%MONTHLY_SALES(2) = 15
%MONTHLY_SALES(3) = 35
IN SALES STORE RECORD
RECTYPE = TOT_SALES
SALES_MM = '01'
SALES_MM = '02'
SALES_MM = '03'
THEN CONTINUE
FEO_SALES:
FEO SALES_MM
ADD MONTHLY_TOTAL = %MONTHLY_SALES(OCCURRENCE IN FEO_SALES)
END FOR
END STORE
END


The resultant record in the <code>SALES</code> file is:
RECTYPE = TOT_SALES
SALES_MM = 01
SALES_MM = 02
SALES_MM = 03
MONTHLY_TOTAL = 10
MONTHLY_TOTAL = 15
MONTHLY_TOTAL = 35


====COMMIT and BACKOUT====

The <var>COMMIT</var> and <var>BACKOUT</var> statements can be used following a <var>THEN CONTINUE</var> statement to save parts of a record as it is built, and to back out all of parts of a record conditionally. Consider the following example:
%CUSTNO = '100639'
IN ORDERS STORE RECORD
RECTYPE = ORDER
ORDER_NUMBER = 1000234
CUSTOMER_NUMBER = %CUSTNO
THEN CONTINUE
COMMIT /? save the order header ?/
FIND_CUST:
IN CLIENTS FD RECTYPE = POLICYHOLDER
POLICY NO = %CUSTNO
END FIND
FOR 1 RECORD IN FIND_CUST
%ADDRESS = ADDRESS
%CITY = CITY
END FOR
ADD ADDRESS = %ADDRESS
ADD CITY = %CITY

COMMIT /? Save the customer address ?/
ADD DELIV_DATE = ($datechg('YYYYMMDD',$DATE(1,''),10))
IF %ORDER_DELAYED = 'Y' THEN
BACKOUT /? Back out deliv date if delay detected ?/
END IF
END STORE


If <code>%ORDER_DELAYED</code> is not <code>Y</code>, the record is stored as follows:
RECTYPE = ORDER
ORDER_NUMBER = 1000234
CUSTOMER_NUMBER = 100639
ADDRESS = 0880 HANCOCK STREET
CITY = LANCASTER
DELIV_DATE = 20111228


Otherwise, the <code>DELIV_DATE</code> <var class="term">fieldname</var>=<var class="term">value</var> pair is backed out.

====Known restrictions or limitations====
<ul>
<li>Be cautious of using the <var>JUMP TO</var> statement following <var>THEN CONTINUE</var> to jump to a label outside the <var>STORE..END STORE</var> block, as this may lead to the storing of a partial record.</li>

<li>It is possible to call a subroutine after the <var>THEN CONTINUE</var> statement, as you might in a <var>FOR RECORD NUMBER</var> loop. Additional update statements to the current record are allowed in the subroutine but only in a <var>FRN $Currec</var> loop. Otherwise, record context is not established and any additional updating statements within the subroutine would be rejected with the following compilation error:
M204.0229: INVALID STATEMENT
</li>

<li>A <var>DELETE RECORD</var> statement following <var>THEN CONTINUE</var>, but before <var>END STORE</var>, causes the current record context to be lost. Any further update statements cause the request to be cancelled with one of the following messages:
M204.1233: DFAV, BAD RECORD NUMBER n FOR FILE filename
M204.1266: NONEXISTENT RECORD REFERENCED - n IN FILE DSNLIST
</li>
</ul>
Note: When using <var>THEN CONTINUE</var>, keep in mind standard considerations for coding any update unit. Be aware that creating longer update units has implications for resource sharing, checkpoints, and recovery requirements.

==UPDATE RECORD statement==

The <var>UPDATE RECORD</var> statement improve performances in remote context by using only one network call to perform all of a group of field-level updates (<var>ADD</var>, <var>CHANGE</var>, <var>DELETE</var>) against the current record in a record loop.

===Syntax===

The syntax of the <var>UPDATE RECORD</var> statement is as follows:
UPDATE RECORD
update-statement-1
update-statement-2
.
.
.
update-statement-N
END UPDATE

Where:

An <var class="term">update-statement</var> is one of the following:
<ul>
<li><var>ADD</var></li>

<li><var>DELETE</var></li>

<li><var>CHANGE</var></li>

<li><var>INSERT</var></li>
</ul>

===Usage===
<ul>
<li>The <var>UPDATE RECORD</var> statement, while supported in all reference contexts, is intended for use with <var class="product">Parallel Query Option/204</var>.</li>

<li>If a series of update statements is executed individually, each one requires a separate network call.</li>

<li>All forms of the update statements are supported. Except, a <var>DELETE EACH</var> statement is not allowed within an <var>UPDATE RECORD</var> statement.</li>

<li>If a field constraint violation occurs, the entire <var>UPDATE</var> statement is backed out.</li>

<li>If an <var>ON</var> unit invoked during the processing of an <var>UPDATE RECORD</var> statement is run with a <var>BYPASS</var> statement, the processing of the request continues with the statement that follows the <var>END UPDATE</var> statement.</li>

<li>If no updates are found between <var>UPDATE RECORD</var> and <var>END UPDATE</var>, the statement is ignored.</li>
</ul>

==Using VALUE IN to reference a NOTE value==

===VALUE IN label clause===

The clause <var>VALUE IN label</var> can replace an explicit field value in the <var>ADD</var>, <var>CHANGE</var>, and <var>STORE RECORD</var> statements. This also applies to the special forms of these statements that are discussed in [[Operations on multiply occurring fields]].

The forms of the <var>VALUE IN</var> statement are:
ADD fieldname = VALUE IN label

CHANGE fieldname TO VALUE IN label

STORE RECORD fieldname = VALUE IN label


===Example===

The following request finds all records in the <code>CLIENTS</code> file that are registered in Alexandria and insured by agent Casola. The policy number for each record found is noted and a corresponding policy number is located on the <code>VEHICLES</code> file. The vehicle premium for the policy on the <code>VEHICLES</code> file is then changed to the total premium amount noted for the policy on the <code>CLIENTS</code> file. 
BEGIN
FIND.RECS: IN CLIENTS FIND ALL RECORDS FOR WHICH
AGENT = CASOLA
CITY = ALEXANDRIA
END FIND
FOR EACH RECORD IN FIND.RECS
KEEP.POL: NOTE POLICY NO
KEEP.PREM: NOTE TOTAL PREMIUM
FIND.MATCH: IN VEHICLES FIND ALL RECORDS FOR WHICH
OWNER POLICY = VALUE IN KEEP.POL
END FIND
FOR EACH RECORD IN FIND.MATCH
CHANGE VEHICLE PREMIUM TO VALUE -
IN KEEP.PREM
END FOR
END FOR
END


==Storing data in fields==

===Storing null values===

If the new value in an <var>ADD</var>, <var>CHANGE</var>, or <var>STORE</var> statement is left blank, no field is added to or stored with the record. If a field containing a null value must be added, you specify the value as an explicit null string (two single quotes with no space between them). For example: 
ADD VEHICLE PREMIUM = ''
CHANGE AGENT TO ''


Note that this statement:
CHANGE FULLNAME TO


is equivalent to:
DELETE FULLNAME


because the old value of <code>FULLNAME</code> is deleted, but no new value is added.

===Using the FIND statement to select fields with null values===

You can use the <var>FIND</var> statement to select records that have a field whose value is the null string, as illustrated below:
FIND.RECS: IN CLIENTS FIND ALL RECORDS FOR WHICH
FULLNAME = ''
END FIND


However, the <var>FIND</var> statement does not select records for a particular field that is missing altogether from the record. See [[Record retrievals#IS PRESENT condition|IS PRESENT condition]] and [[Value loops#Locating records missing a particular field|Locating records missing a particular field]] for examples of finding records without a particular field. 

===Storing values in preallocated fields===

The file manager can indicate in a field definition the length of the field (<var>LENGTH</var> attribute) and/or the number of times that field can occur in a record (<var>OCCURS</var> attribute). Space for fields with the <var>LENGTH</var> and <var>OCCURS</var> attributes is preallocated in each record in a file, and this space cannot be expanded. 

If you attempt to store more values (an <var>OCCURS</var> violation) or longer values (a <var>LENGTH</var> violation) than a field's definition permits, an error message is displayed or the request is cancelled. 

====LENGTH violations====

If a field is defined as having a particular length (<var>LENGTH</var> m), that field can store only values that are between one and <var class="term">m</var> bytes long. Other values are rejected. If you explicitly specify a field name and value in a SOUL statement, as in this request: 
ADD YEAR = 90


<var class="product">Model 204</var> checks the length of the value during the compilation phase. A length violation detected in an update statement (<var>ADD</var>, <var>CHANGE</var>, <var>FILE</var>, or <var>STORE</var>) results in a compilation error. A length violation also can be detected for a <var>STORE</var> statement for a sort or hash key defined with <var>LENGTH</var> m. 

If field name variables or %variables are used in an update statement, length validity checks are deferred until the request is evaluated. If an error is detected at this point, the request is cancelled. Request cancellation can be avoided by using <var>[[$FldLen#$FldLen|$FldLen]]</var>. Specifying a field value that is too long for a <var>LENGTH</var> field in a retrieval context always causes the retrieval to fail, because the value could not have been stored. 

Attempts to locate invalid values are treated as references to a nonexistent value. For example, a selection criterion in a <code>FIND fieldname = value</code> fails to locate any records. 

====OCCURS violations====

If a field is defined as occurring a particular number of times (<var>OCCURS</var> n), it can be stored up to n times in any record. An attempt to add (using <var>ADD</var> or <var>STORE RECORD</var> statement) an additional occurrence to a record containing the maximum number causes the request to be cancelled. To protect SOUL requests from cancellations due to occurrence violations refer to:
<ul>
<li>[[Operations on multiply occurring fields#COUNT OCCURRENCES OF statement|COUNT OCCURRENCES OF statement]] </li>

<li><var>[[$Occurs|$Occurs]]</var>
</li>
</ul>

===Storing values in FLOAT fields===

====Exponent notation====

If a new value is to be stored in a field defined with the FLOAT attribute, the value can be defined in exponent notation. See [[Record retrievals#Exponent notation|Exponent notation]] for information. 

An invalid value is stored as an unconverted string.

====String values====

When you supply a string as the value to be stored, <var class="product">Model 204</var> attempts to convert the string to floating point representation according to the floating point conversion rules (see [[Record retrievals#Equality retrievals|Equality retrievals]]). If the value to be stored cannot be converted, one of two things happens:
<ul>
<li>If the field is preallocated, the request is cancelled.</li>

<li>If the field is not preallocated, the unconverted value is stored.
</li>
</ul>

====Floating point values====

When you supply a floating point value as the value to be stored, the value is not altered if its length is the same as the floating point field's defined length. Values of different lengths are truncated or rounded according to the rules described in. 

===Storing values in BINARY fields===

====Compressed values====

Fields defined as having the <var>BINARY</var>, <var>OCCURS</var>, and <var>NON-CODED</var> attributes can store only compressible values because only a small amount of space is preallocated for such a field. A compressible value is a decimal integer of up to nine digits with no plus sign, leading zeros, embedded blanks (following a minus sign), or decimal point.
Refer to [[Field design#Data_typing|Data typing]] for additional information on such values. 

====Value checking====

Values to be stored in <var>BINARY</var> fields are not checked until the request is evaluated. If you attempt to store an incompressible value in a <var>BINARY</var>, <var>OCCURS</var>, and <var>NON-CODED</var> field, the request is cancelled. 

==Updating field groups==
Note: Field groups are supported as of Model 204 version 7.5.

When a field group is added, a field group ID is assigned to the field group. This field group ID is unique among all field groups in the record, whether or not they have the same field group name. The ID is a number between 1 (zero is not used as an ID) and 2**32-1. The field group ID is an unsigned 32-bit integer, though only a length byte and trailing non-zero bytes are stored.

Field group IDs from 1-255 require two bytes for the field group ID in Table B, IDs 256-65535 require three bytes, and so on. Once assigned, a field group ID is not reused regardless of whether the field group associated with the ID is deleted. That is, if you add a field group and it is assigned ID 6, and then you delete the field group, ID 6 will not be reused.

The one exception when field group ID reuse is allowed is on transaction back out. If field group ID 6 is assigned to an added field group, but then the addition is backed out, field group ID 6 can be assigned to a subsequent <var>ADD</var> or <var>INSERT FIELDGROUP</var>.

===Adding a field group===
To add a field group, issue an ADD FIELDGROUP statement in a record context:
FR IN LABELX
ADD FIELDGROUP fieldgroupname
field1 = (value1 | expression)
[field2 = (value2 | expression)
...]
END ADD
END FOR

The syntax of the <var class="term">fieldname=value</var> pairs inside an <var>ADD FIELDGROUP</var> statement is identical to that of a <var>STORE RECORD</var> statement. See also [[#Inserting a field group|Inserting a field group]].

In place of a value in the <var class="term">fieldname=value</var> pair, you can enter an expression. See [[#Expressions as field name values|Expressions as field name values]] for details.

===Inserting a field group===
In addition to the ADD FIELDGROUP statement, you can also issue an <var>INSERT FIELDGROUP</var> statement:
FR WHERE ...
INSERT FIELDGROUP <var class="term">name</var>(<var class="term">subscript</var>)
FIELDA = ’ABC’
FIELDB = ’DEF’
...
END INSERT
END FOR


The <var>INSERT FIELDGROUP</var> statement has the same semantics as an <var>INSERT FIELD</var> statement. If the indicated occurrence of the field group is found, the new occurrence is inserted immediately before that occurrence. If it is not found, the new occurrence is added at the end of the record.

The inside of the <var>INSERT</var> block has the identical format to the <var>STORE RECORD</var> and <var>ADD FIELDGROUP</var> statements.

===Deleting a field group===
You can delete a field group several ways.

====Delete first field group occurrence in each record====
BEGIN
A: IN TEST1 FD
END FIND
B: FR A
DELETE FIELDGROUP BIRDS
END FOR


====Delete all field group occurrences, if present, in one record====
BEGIN
A: IN TEST1 FD
END FIND
B: FR A
DELETE EACH FIELDGROUP PESTS
END FOR


====Delete a field group without the name or ID reference====
BEGIN
A: IN TEST1 FD
END FIND
B: FR A
FOR EACH OCCURRENCE OF FIELDGROUP TRANSLATIONS
IF LANGUAGE = ’INDIAN’ THEN
%X = $FIELDGROUPID
DELETE FIELDGROUP
PRINT ’DELETING ID: ’ WITH %X
END IF
END FOR
END FOR


====Delete a field group with a subscript====

To delete the third occurrence of field group <code>PITCHERS</code>, you would issue the following statement:
FR IN LABELX
DELETE FIELDGROUP PITCHERS(3)
END FOR

When you delete a field group occurrence, all fields within the field group occurrence are deleted, as well as the indices for those fields. Or, you can delete a field group with a simple <var>DELETE</var> statement while in a field group context:
FR IN LABELX
FAO FIELDGROUP PITCHERS
DELETE FIELDGROUP
END FOR
END FOR


===Displaying field groups and their fields===
After you add a field group to a record, you can display the field groups and their fields by issuing a <var>PAI</var> statement, output as follows:
BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100095
PAI
END

POLICY_NUMBER = 100095
POLICY_RESTRICTIONS = POLICY IS INVALID IF ...
... OTHER POLICY FIELDS
\DRIVER = 1
DRIVER_NAME = ALTON, BARBARA W
...OTHER DRIVER FIELDS
/DRIVER = 1
\DRIVER = 2
DRIVER_NAME = ALTON, CARRIE Y
...OTHER DRIVER FIELDS
/DRIVER = 2
\VEHICLE = 6
MAKE = VOLKSWAGEN
MODEL = NEW BEETLE
...OTHER VEHICLE FIELDS
/VEHICLE = 6
\VEHICLE = 7
MAKE = MITSUBISHI
MODEL = ECLIPSE
...OTHER VEHICLE FIELDS
\CLAIM = 9
CLAIM_NUMBER = 100059
WEATHER = RAIN
...OTHER CLAIM FIELDS
/CLAIM = 9
\CLAIM = 10
CLAIM_NUMBER = 100064
WEATHER = FOG
...OTHER CLAIM FIELDS
/CLAIM = 10
/VEHICLE = 7
\VEHICLE = 8
MAKE = CHEVROLET
MODEL = SUBURBAN
...OTHER VEHICLE FIELDS
/VEHICLE = 8

The lines that begin with a backslash (<tt>\</tt>) identify the start of a field group and the lines that begin with a forward slash (<tt>/</tt>) identify the end of the field group. The field group ID of the field group occurrence is indicated after the field group name on both the field group beginning and ending lines.

The field group IDs are not necessarily in ascending order in a record. The previous example was created by issuing <var>INSERT</var> statements, so the IDs are out of order.

The function <var>[[$FieldgroupId]]</var> can be used to show the field group ID.

===Support for field group name variables===

Field group name variables are supported; for example:
<nowiki>IN POLICIES FRN %RECNO
%FIELD = ’SURCHARGE%’
ADD FIELDGROUP VEHICLE
MAKE = ’FORD’
MODEL = ’MUSTANG’
%%FIELD = 15
* and so on
END ADD FIELDGROUP VEHICLE
END FOR</nowiki>

Field name variables that evaluate to something in an invalid field group context result in request cancellation. For example, if <code>BARD</code> is a field in field group <code>PITCHERS</code> and you issue the following statement:
IN FILE REDSOCKS FRN %RECNO
%FIELD = ’BARD’
ADD %%FIELD = ’Knuckle ball’

A request cancellation is generated, because you tried to add an occurrence of field <code>BARD</code> outside its appropriate field group context.
</div> 

[[Category:SOUL]]

Release notes for Model 204 version 7.5

2014-08-01T13:45:23Z

Mlarocca:

These release notes list the enhancements and other changes contained in Model 204 version 7.5.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.5.0 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
This section summarizes the new features and enhancements for Model 204 version 7.5.0.

===SOUL (User Language)===
The significantly enhanced, object-oriented, version of User Language is now called [[#SOUL (User Language) enhancements|SOUL]]. All existing User Language programs will continue to work under SOUL, so User Language can be considered to be a subset of SOUL, though the name "User Language" is now deprecated.
<ul>
<li>integration of object-oriented language extensions from the Janus SOAP User Language Interface</li>
<li>[[Release notes for Model 204 version 7.5 (DRAFT)#External Call Facility .28ECF.29|ECF]] CALL statements can pass up to 60 parameters</li>
</ul>

===System Management===
<ul>
<li>Writing records to the SMF data set without an SVC installed</li>
</ul>

===Performance===
<ul>
<li>GTBL can be stored above the bar</li>
<li>[[Release notes for Model 204 version 7.5 (DRAFT)#Support for physical field groups|Support for physical field groups]]</li>
</ul>

==Operating system requirements==
Requirements for Model 204 version 7.5 are still being determined.

Model 204 version 7.5 requires the following operating system support:
<ul>
<li>For IBM z/OS: Version 1 Release 7. V1R7 is sufficient for all new functionality except for the following
features:
<ul>
<li>Large (1 MB) page support requires Version 1 Release 9.
<li>Extended address volumes (EAV) requires Version 1 Release 12.
</ul>
<li>For IBM z/VM: Version 5 Release 4.0 or later
<li>For IBM z/VSE:
<ul>
<li>Version 5 Release 1 or
<li>Version 4 Release 3 or
<li>Version 4 Release 2.1 or
<li>Version 4 Release 2.0, with these program temporary fixes (PTFs) installed:
<ul>
<li>UD53436
<li>UD53437
<li>UD53438
<li>UD53439
</ul>
</ul>
Note: z/VSE V5.1 is required to take advantage of any 64-bit capabilities under VSE.

</ul>

=== Hardware requirements ===
Requirements for Model 204 version 7.5 are still being determined.

Model 204 version 7.5 requires the IBM z/890 or above processor, except for the following feature:

The large (1 MB) page support feature requires the IBM z10 or above processor. 

===Model 204 compatibility with operating systems===
Content for version 7.5 is still being determined.
For information on Model 204 certification with IBM operating systems, see:
http://www.rocketsoftware.com/products/rocket-model-204/technical-information

<div id="Connect* compatibility with Model 204"></div>
===Connect* compatibility with Model 204===
Connect★ version 7.5.0 is compatible with all versions of Model 204.

==SOUL (User Language) enhancements==
Much of the substantial new and enhanced functionality described in the following subsections is available as a result of the acquisition of Sirius Software. The functionality that is the subject of the initial subsection, "Object oriented programming," motivates the new name for User Language, '''SOUL''' (Simple Objective User Language).

===Object oriented programming===
As of version 7.5 of Model 204 (and backward compatible with existing User Language applications), the SOUL language is equipped with [http://en.wikipedia.org/wiki/Object-oriented Object-Oriented Programming](sometimes abbreviated OO) capabilities comparable or superior to other contemporary object oriented languages. The OO features were formerly contained in the [[Janus SOAP User Language Interface]], and you can use [[Object oriented programming in SOUL]] as an entry point to the extensive SOUL OO documentation. In particular, you might want to begin with the [[Getting started with OOP for User Language programmers|OO tutorial]].

===Record capacity increase===
In this version of Model 204, the record limit is increased from sixteen million records to forty-eight million records per file.

===New SOUL statements===
{{Template:User Language statements}}

===Non-OO enhancements in SOUL===
{{Template:User Language syntax enhancements}}

===SOUL support for field groups===

====ADD (or INSERT or DELETE) FIELDGROUP statements====
The <var>ADD FIELDGROUP</var> statement and the <var>INSERT FIELDGROUP</var> statement behavior parallels the behavior of the <var>ADD</var> and <var>INSERT</var> statements for simple fields. The <var>DELETE FIELDGROUP</var> statement handles more situations and is therefore more complex.
See [[Data maintenance#Updating field groups|Updating field groups]] for details.

====Statements for handling field groups====
SOUL now provides several statements for handling field groups:
<ul>
<li><var>FOR FIELDGROUP</var></li>
<li><var>FOR ALL OCCURRENCES OF FIELDGROUP (FAO FIELDGROUP)</var></li>
<li><var>FOR EACH OCCURRENCE OF FIELDGROUP (FEO FIELDGROUP)</var></li>
</ul>

See [[Operations on multiply occurring fields#Special statements for multiply occurring fields and field groups|Special statements for multiply occurring fields and field groups]] for details.

====Output statements for field groups====

The following SOUL statements provide display output for Model 204 field groups:
AUDIT ALL FIELDGROUP INFORMATION (AAFGI)
PRINT ALL FIELDGROUP INFORMATION (PAFGI)


See [[Basic SOUL statements and commands#Output statements for fields and field groups|Output statements for fields and field groups]] for details.

====Field group SORT support====
You can use field groups in [[Sorting#Field group SORT support|sorted sets]]. <var>SORT</var> statement support for field groups lets you sort records with field groups as well as reference field groups in the sorted sets. For example, you can issue a <code>FAO FIELDGROUP</code> statement or <code>FEO FIELDGROUP</code> statement against the sorted set.

===EQ VALUE retrieval condition===

SOUL now provides the <var>EQ VALUE</var> clause to support expressions in <var>FIND</var> statements.

See [[Record retrievals#Using expressions in FIND statements|Using expressions in FIND statements]] for details.

===EQ WITH retrieval condition for concatenated fields===
SOUL now provides the <var>EQ WITH</var> clause for retrieving <var>CONCATENATION-OF</var> fields. Model 204 automatically builds the concatenated value.

See [[Record retrievals#Using expressions in FIND statements|Using expressions in FIND statements]] and [[Record retrievals#EQ WITH retrieval condition for concatenated fields|EQ with retrieval condition for concatenated fields]] for details.

===External Call Facility (ECF)===
<var>EXTERNAL CALL</var> statements can now pass more parameters.
The maximum number of parameters that can be passed in an <var>EXTERNAL CALL</var> statement has been increased from 40 to 60.
The maximum value setting for <var>[[ECPSIZE parameter|ECPSIZE]]</var> is increased from 1310680 to 1966020 to accommodate the extra parameters.

ECF is available only on z/OS systems. For more information about the External Call Facility and the <var>EXTERNAL CALL</var> statement, see the <var class="book">Rocket Model 204 System Manager's Guide</var>.

===REPEAT statement UNTIL option===
The <var>REPEAT</var> statement now supports the <var>UNTIL</var> option. In previous releases, only <var>REPEAT WHILE</var> was supported.

A <var>[[Flow of control in User Language#REPEAT UNTIL statement|REPEAT UNTIL]]</var> statement enters the loop body prior to checking the condition.

===New and changed classes and methods===

====New InvalidBitNumber class====
Objects of the [[InvalidBitNumber class|InvalidBitNumber exception class]] are thrown when an invalid bit number is requested by a bit manipulation function. It is currently thrown only by the <var>[[BitClearString (String function)|BitClearString]]</var>, <var>[[BitFlipString (String function)|BitFlipString]]</var>, <var>[[BitSetString (String function)|BitSetString]]</var>, and <var>[[BitValueString (String function)|BitValueString]]</var> functions.

====New InvalidTranslateTable class====
Objects of the [[InvalidTranslateTable class|InvalidTranslateTable exception class]] are thrown when a requested system translate table cannot be found. It is currently thrown only by the <var>[[TranslateTable (HttpRequest property)|TranslateTable]]</var> <var>HttpRequest</var> property.

====New bit manipulation String functions====
New bit manipulation functions <var>[[BitClearString (String function)|BitClearString]]</var>, <var>[[BitCountString (String function)|BitCountString]]</var>, <var>[[BitFlipString (String function)|BitFlipString]]</var>, <var>[[BitSetString (String function)|BitSetString]]</var>, and <var>[[BitValueString (String function)|BitValueString]]</var> make it easier to manipulate the bits in a string.

====New String processing functions====
New <var>String</var> functions <var>[[Before (String function)|Before]]</var> and <var>[[After (String function)|After]]</var> return the parts of a string before or after a user-specified delimiter string.

====New Stringlist subroutine====
New <var>Stringlist</var> subroutine <var>[[AppendPemData (Stringlist subroutine)|AppendPemData]]</var>
appends a PEM encode string to a <var>Stringlist</var>.

====New System methods TODClock and UUIDTime====
New System class methods [[TODClock (System function)|TODCLOCK]] and [[UUIDTime (System function)|UUIDTime]] have been created to facilitate generation of version 1 universal unique identifiers and to provide high precision time stamps for SOUL applications. These methods were actually added as a ZAP update to Model 204 7.5 (75Z109).

====New HttpRequest TranslateTable property====
The <var>[[TranslateTable (HttpRequest property)|TranslateTable]]</var> <var>HttpRequest</var> property makes it possible to set the translate table to be used for EBCDIC to ASCII translation of data in an <var>HttpRequest</var> object.

====Disable base64 encoding in LoadFromRecord and related methods====
The <var>Base64Encode</var>=<var>False</var> argument can be used with the <var>[[LoadFromRecord (XmlDoc/XmlNode subroutine)|LoadFromRecord]]</var> method to disable any base64 encoding of field values.

Alternatively, the <var>CharacterMap</var> argument (with a non-null value) can be used to disable any base64 encoding of field values, and to specify translations, which can avoid request translation due to X'00' and/or untranslatable characters in field values.

These arguments are also added to the <var>[[NewFromRecord (XmlDoc function)|NewFromRecord]]</var> and <var>[[ToXmlDoc (Record function)|ToXmlDoc]]</var> methods.

====New parameter for AppendJournalData====
The <var>QT</var> option is added to the <var>[[AppendJournalData (Stringlist function)#Options parameter|AppendJournalData]]</var> method, to include QT type audit entries.

====New parameter for AddField====
The <var>Strip</var> option is added to the <var>Screen</var> class method <var>[[AddField (Screen function)|AddField]]</var> to allow suppression of leading and trailing blank removal from input fields.

===New and changed $functions===

====Former Sirius $functions====
The $functions referred to by the link below are added to SOUL as a result of the acquisition of Sirius Software:
:[[List of $functions|Sirius $functions]]
Among these $functions are integrated [[List_of_mathematical_$functions|math $functions]]: high-performance, high-precision versions of the IBM mathematical functions. These functions eliminate the need to use external math libraries.

====$SNDMAIL attachment ASCII translation====
The <var>[[SOUL_$functions#Sending_email_messages_via_User_Language|$SNDMAIL]]</var> function can now translate an attachment to ASCII before sending it.
This translation is useful if the <var>$SNDMAIL</var> attachment is a <var>CLOB</var> (<var>CHARACTER-LARGE-OBJECT</var>) such as a text document.

The <var>$SNDMAIL</var> function now accepts an optional parameter after the name of the attached object. If this parameter is set to 'C' (or to a percent variable with the value 'C'), the object in the buffer is translated to ASCII before being attached to the email.

If this parameter is not specified, the object in the buffer is sent as a binary object.

In this example:
%RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,'CLOB.TXT','C')

the <code>CLOB.TXT</code> attachment will be translated to ASCII before being attached to the email.

====New function calls for field groups====
When a field group is added, a [[Data maintenance#Updating field groups|field group ID]] is assigned to the field group.
<ul>
<li><var>[[$FieldgroupId]]</var> returns the ID of the current field group.</li>
<li><var>[[$FieldgroupOccurrence]]</var> returns the current occurrence number of the field group.</li>
</ul>

==Sirius products and product enhancements==
[[Sirius Software product list|The former-Sirius products]] are now available to Model 204 customers as separately purchased items as a result of the acquisition of Sirius Software.

===Changes to Janus SSL support===
Under Model 204 version 7.5, Janus products:

<ul>
<li>Drop support for version 2 of the Secure Sockets Layer encryption protocol (SSL V2)

You can use the <var>[[SSLPROT (JANUS DEFINE parameter)|SSLPROT]]</var> parameter on the <var>JANUS DEFINE</var> command for a port to explicitly specify, or limit, the SSL protocols available for a connection. The <var>SSLPROT</var> documentation describes the SSL protocols that Janus supports. 

Janus support for SSL V2 also included an option to specify a larger than "legal" input buffer for connections not strictly conforming to the V2 standard. You specify that buffer size with the <var>JANUS DEFINE</var> <var>[[SSLIBSIZE (JANUS DEFINE parameter)|SSLIBSIZE]]</var> parameter, and the <var>SSLIBSIZE</var> maximum value as of Model 204 V7.5 is reduced (from 32767 bytes) to the SSL maximum allowed size of 16384. </li>

<li>Add support for new ciphers and TLS levels

You can use the <var>[[SSLCIPH (JANUS DEFINE parameter)|SSLCIPH]]</var> <var>JANUS DEFINE</var> parameter to specify the SSL ciphers available for a connection. The <var>SSLCIPH</var> documentation describes the SSL ciphers that Janus supports. </li>
</ul>

===WEBOPT parameter change===
The <var>[[WEBOPT parameter|WEBOPT]]</var> parameter default value is changed to X'03' from 0. <var>WEBOPT</var> affects the interaction of Model 204 and RACF security.

==File-related enhancements==

===Support for physical field groups===
Model 204 supports non-relational, de-normalized data structures. Many Model 204 sites have enjoyed significant cost and performance benefits from efficiently processing multiply occurring fields. This concept has been enhanced to introduce physical field groups that let you view and process groups of fields as a logical entity.

You can define a physical field group only for files with the [[#FILEORG (new settings)|FILEORG X'100' setting]]. To take advantage of field groups in files defined before Model 204 version 7.5, you must reorganize the files with a <var>FILEORG</var> setting that includes the X'100' bit.

Files with <var>FILEORG</var> X'100' can have up to 32,000 fields.

For more information, see [[Field group design]].

===Increased Table B record number capacity===
[[Table B (File architecture)|Table B]] can now contain up to 48M possible record numbers. (The previous limit was 16M.)

Set the [[#FILEORG (new settings)|FILEORG X'200' bit]] at file creation time to allow for the increased record numbers.
<blockquote class="note">
Notes: 
<ul>
<li>The limit for <var>BSIZE</var> remains at 16M.

<code>BSIZE * BRECPPG</code> must be less than or equal to 48M (actually decimal 50,331,648 to be exact). 

For example, if <var>BSIZE</var> is 16M, <var>BRECPPG</var> cannot be more than 3. </li>

<li>The <var>FILEORG</var> X'200' bit cannot be set for files with hash key or sorted file organization.</li>
</ul>
</blockquote>

===Automatic fields===
Model 204 now lets you define a field whose value is [[Field design#Automatic fields|automatically maintained]]. A field can count occurrences of another field so that every store or delete of the field occurrence changes the count in the automatic field. The following automatically maintained field attributes are available for files defined with the FILEORG x'100' setting:
<ul>
<li><var>COUNT-OCCURRENCES-OF</var></li>
<li><var>CREATE-TIME</var></li>
<li><var>CREATE-TIMEUTC</var></li>
<li><var>CREATE-USER</var></li>
<li><var>UPDATE-TIME</var></li>
<li><var>UPDATE-TIMEUTC</var></li>
<li><var>UPDATE-USER</var></li>
</ul>

The value of an automatic field is updated at the start of a transaction by Model 204 and you cannot set it explicitly by a program. Any valid update statement causes the appropriate time and user stamps to be updated. For example, the time and user stamps will be updated when <code>DELETE FOO(8)</code> is processed, even if there are no occurrences of FOO in the record and an actual update does not take place.

Once you define an automatic value for a field, you cannot redefine the automatic value.

===Concatenated fields===
Model 204 now lets you define [[Field design#Concatenated fields|concatenated fields]].

Fields that make up concatenated field values must be <var>AT-MOST-ONE</var>, <var>EXACTLY-ONE</var>, or <var>OCCURS</var> 1 and must all be in the same field group context (or not in a field group). Fields that occur in all field groups (<var>FIELDGROUP *</var>) cannot be used in a concatenation.

If a concatenated field becomes longer than 255 bytes after adding separator and escape characters, the update request is cancelled.

===New field attributes===
Model 204 version 7.5 introduces the new <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> attributes described in this section. These attributes apply to all fields in Model 204. 

Note: These attributes all require that the <var>[[FILEORG parameter|FILEORG]]</var> parameter X'100' bit be set on the file containing the fields.

Changes in the new field attributes are detected during the redefinition of an existing field. When such a change is detected, the following messages might be issued:
M204.1260: [FIELD | FIELDGROUP] WAS PREVIOUSLY DEFINED WITH DIFFERENT ATTRIBUTES,
NEW [FIELD | FIELDGROUP] OPTIONS IGNORED

or
M204.2884: [FIELD WAS PREVIOUSLY DEFINED AS A FIELDGROUP | FIELDGROUP WAS PREVIOUSLY
DEFINED AS A FIELD], NEW DEFINITION IGNORED


The table below lists the new field attributes. For details on each attribute, click its name. For more information on how related attributes work together, see the [[Field design]] topic.
<table>
<tr class="head">
<th>Attribute</th><th>Abbreviation</th><th>Description</th>
</tr>

<tr>
<td>[[DEFINE_FIELD_command#Ordered_index_CHUNK_attribute|CHUNK]]</td>
<td>CNK</td>
<td>Defines "OI chunks" of data in ORDERED NUMERIC fields to enable more efficient range searching.</td>
</tr>

<tr>
<td>[[Field design#CONCATENATION-OF .28CAT.29 attribute|CONCATENATION-OF]]</td>
<td>(CAT)</td>
<td>Lists the fields that make up a concatenated field, and provides a concatenated value based upon the values of the constituent fields.</td>
</tr>

<tr>
<td nowrap>[[Field design#Counting occurrences of a field|COUNT-OCCURRENCES-OF]]</td>
<td>(CTO)</td>
<td>Automatically maintains a count of the number of occurrences of the specified field.</td>
</tr>

<tr>
<td>[[Field design#Automatic Fields|CREATE-TIME]]</td>
<td>(CRTM)</td>
<td>Captures the time when the record was created, as of the start of the transaction.</td>
</tr>

<tr>
<td>[[Field design#Automatic Fields|CREATE-TIMEUTC]]</td>
<td>(CRTMU)</td>
<td>Captures the Coordinated Universal Time when the record was created, as of the start of the transaction.</td>
</tr>

<tr>
<td>[[Field design)#Automatic Fields|CREATE-USER]]</td>
<td>(CRUS)</td>
<td>Captures the user ID of the user who created the record.</td>
</tr>

<tr>
<td>[[Field design#DATETIME-GE .28DTGE.29.2C DATETIME-GT .28DTGT.29.2C DATETIME-LE .28DTLE.29.2C and DATETIME-LT .28DTLT.29 attributes|DATETIME]]</td>
<td>(DT)</td>
<td>Specifies the format of the date and time data stored in Table B. The default is YYYYMMDDHHMMSSXXXXXX, i.e. to the nearest millionth of a second.</td>
</tr>

<tr><td>[[Field design#DATETIME-GE .28DTGE.29.2C DATETIME-GT .28DTGT.29.2C DATETIME-LE .28DTLE.29.2C and DATETIME-LT .28DTLT.29 attributes|DATETIME-GE]]</td>
<td>(DTGE)</td>
<td>With DATETIME-GT, DATETIME-LE, and DATETIME-LT, used to establish a range for date/time values. Specifies that the date/time value must be later than or the same as the date/time value that follows. </td>
</tr>

<tr>
<td>[[Field design#DATETIME-GE .28DTGE.29.2C DATETIME-GT .28DTGT.29.2C DATETIME-LE .28DTLE.29.2C and DATETIME-LT .28DTLT.29 attributes|DATETIME-GT]]</td>
<td>(DTGT)</td>
<td>Specifies that the date/time value must be later than the date/time value that follows.</td>
</tr>

<tr>
<td>[[Field design#DATETIME-GE .28DTGE.29.2C DATETIME-GT .28DTGT.29.2C DATETIME-LE .28DTLE.29.2C and DATETIME-LT .28DTLT.29 attributes|DATETIME-LE]]</td>
<td>(DTLE)</td>
<td>Specifies that the date/time value must be earlier than or the same as the date/time value that follows.</td>
</tr>

<tr>
<td>[[Field design#DATETIME-GE .28DTGE.29.2C DATETIME-GT .28DTGT.29.2C DATETIME-LE .28DTLE.29.2C and DATETIME-LT .28DTLT.29 attributes|DATETIME-LT]]</td>
<td>(DELT)</td>
<td>Specifies that the date/time value must be earlier than the date/time value that follows.</td>
</tr>

<tr>
<td>[[Field design#DEFAULT-VALUE .28DV.29 attribute|DEFAULT-VALUE]]</td>
<td>(DV)</td>
<td>Specifies the value to use for the field when the record is created and no value has been assigned to the field.

(The value of the STORE-DEFAULT setting determines whether the DEFAULT-VALUE is physically stored on the record or if it is just used as the default value when the field is missing.)</td>
</tr>

<tr>
<td>[[Field design#ESCAPE .28ESC.29 attribute|ESCAPE]]</td>
<td>(ESC)</td>
<td>Specifies an escape character to insert before separator and escape characters in a concatenated field, differentiating those characters from real data. The default value is X'01'.</td>
</tr>

<tr>
<td>[[Field design#AT-MOST-ONE.2C REPEATABLE and EXACTLY-ONE attributes|EXACTLY-ONE]]</td>
<td>(EXONE)</td>
<td>Specifies that a field always has exactly one occurrence in its record or field group context.
EXACTLY-ONE fields always appear first when output by a Print All Information (PAI) statement.</td>
</tr>

<tr><td>[[Field design#FIELDGROUP attribute|FIELDGROUP]]</td>
<td>(FG)</td>
<td>Specifies the name of the field group that the defined field is associated with (contained within).</td>
</tr>

<tr>
<td>[[Field design#FLOAT-GE .28FLTGE.29.2C FLOAT-GT .28FLTGT.29.2C FLOAT-LE .28FLTLE.29 and FLOAT-LT .28FLTLT.29 attributes|FLOAT-GE]]</td>
<td>(FLTGE)</td>
<td>With FLOAT-GT, FLOAT-LE, and FLOAT-LT, used to establish a range for float values when defining a field. Specifies that the float value must be greater than or equal to the value that follows.</td>
</tr>

<tr>
<td>[[Field design#FLOAT-GE .28FLTGE.29.2C FLOAT-GT .28FLTGT.29.2C FLOAT-LE .28FLTLE.29 and FLOAT-LT .28FLTLT.29 attributes|FLOAT-GT]]</td>
<td>(FLTGT)</td>
<td>Specifies that the float value must be greater than the value that follows.</td>
</tr>

<tr>
<td>[[Field design#FLOAT-GE .28FLTGE.29.2C FLOAT-GT .28FLTGT.29.2C FLOAT-LE .28FLTLE.29 and FLOAT-LT .28FLTLT.29 attributes|FLOAT-LE]]</td>
<td>(FLTLE)</td>
<td>Specifies that the float value must be less than or equal to the value that follows.</td>
</tr>

<tr>
<td>[[Field design#FLOAT-GE .28FLTGE.29.2C FLOAT-GT .28FLTGT.29.2C FLOAT-LE .28FLTLE.29 and FLOAT-LT .28FLTLT.29 attributes|FLOAT-LT]]</td>
<td>(FLTLT)</td>
<td>Specifies that the float value must be less than the value that follows.</td>
</tr>

<tr>
<td>[[Field design#INTEGER-GE .28INTGE.29.2C INTEGER-GT .28INTGT.29.2C INTEGER-LE .28INTLE.29 and INTEGER-LT .28INTLT.29 attributes|INTEGER-GE]]</td>
<td>(INTGE)</td>
<td>With INTEGER-GT, INTEGER-LE, and INTEGER-LT, used to establish a range for integer values when defining a field. Specifies that the integer value must be greater than or equal to the value that follows.</td>
</tr>

<tr>
<td>[[Field design#INTEGER-GE .28INTGE.29.2C INTEGER-GT .28INTGT.29.2C INTEGER-LE .28INTLE.29 and INTEGER-LT .28INTLT.29 attributes|INTEGER-GT]]</td>
<td>(INTGT)</td>
<td>Specifies that the integer value must be greater than the value that follows.</td>
</tr>

<tr>
<td>[[Field design#INTEGER-GE .28INTGE.29.2C INTEGER-GT .28INTGT.29.2C INTEGER-LE .28INTLE.29 and INTEGER-LT .28INTLT.29 attributes|INTEGER-LE]]</td>
<td>(INTLE)</td>
<td>Specifies that the integer value must be less than or equal to the value that follows.</td>
</tr>

<tr>
<td>[[Field design#INTEGER-GE .28INTGE.29.2C INTEGER-GT .28INTGT.29.2C INTEGER-LE .28INTLE.29 and INTEGER-LT .28INTLT.29 attributes|INTEGER-LT]]</td>
<td>(INTLT)</td>
<td>Specifies that the integer value must be less than the value that follows.</td>
</tr>

<tr>
<td>[[Field design#LENGTH-EQ .28LEQ.29 attribute|LENGTH-EQ]]</td>
<td>(LEQ)</td>
<td>Used to set a length constraint when defining a field. Specifies the required length of a field value.</td>
</tr>

<tr>
<td>[[Field design#LENGTH-GE .28LGE.29 attribute|LENGTH-GE]]</td>
<td>(LGE)</td>
<td>Specifies the minimum length of a field value.</td>
</tr>

<tr>
<td>[[Field design#LENGTH-LE .28LLE.29 attribute|LENGTH-LE]]</td>
<td>(LLE)</td>
<td>Specifies the maximum length of a field value.</td>
</tr>

<tr><td>[[Field design#Setting a pattern for a field value: the LIKE attribute|LIKE]]</td>
<td>(LK)</td>
<td>Sets a pattern that to which a field value must conform.</td>
</tr>

<tr>
<td>[[Field design#BLOB.2C CLOB.2C and MINLOBE attributes|MINLOBE]]</td>
<td>(MLBE)</td>
<td>Defines the minimum size of a BLOB or CLOB field value that will be stored in Table E. This avoids wasting Table E pages on small values that could be stored in Table B (or Table X). The default is 0.</td>
</tr>

<tr>
<td>NO-DOMAIN-CONSTRAINTS</td>
<td/>
<td>Specifies that the field has no [[Field design#Content constraints|content constraint]] attributes. Useful with <var>[[REDEFINE command|REDEFINE]]</var> to remove existing constraints on a field.</td>
</tr>

<tr>
<td>NO-DEFAULT-VALUE</td>
<td>(NDV)</td>
<td>Specifies that the field has no default value. Useful with <var>[[REDEFINE command|REDEFINE]]</var> to remove an existing default value on a field.</td>
</tr>

<tr>
<td>[[Field design#SEPARATOR .28SEP.29 attribute|SEPARATOR]]</td>
<td>(SEP)</td>
<td>Specifies a separator character used between field values in concatenated fields. The default is X'00'.</td>
</tr>

<tr>
<td>[[Field design#STORE-DEFAULT .28SD.29 and STORE-NULL .28SN.29 attributes|STORE-DEFAULT]]</td>
<td>(SD)</td>
<td>Specifies whether to physically store the default value for the field in each record, if no field value has been supplied and a default is required. The default option is LITERAL (LIT), which stores a literal string.</td>
</tr>

<tr>
<td>[[Field design#STORE-DEFAULT .28SD.29 and STORE-NULL .28SN.29 attributes|STORE-NULL]]</td>
<td>(SN)</td>
<td>Specifies whether to physically store the null value for the field in each record, if no field value has been supplied, and a default is required. The default option is LITERAL (LIT), which stores a literal string.</td>
</tr>

<tr>
<td>[[Field design#Automatic Fields|UPDATE-TIME]]</td>
<td>(UPTM)</td>
<td>Captures the time when the record was updated, as of the start of the transaction.</td>
</tr>

<tr>
<td>[[Field design#Automatic Fields|UPDATE-TIMEUTC]]</td>
<td>(UPTMU)</td>
<td>Captures the Coordinated Universal Time when the record was updated, as of the start of the transaction.</td>
</tr>

<tr>
<td>[[Field design#Automatic Fields|UPDATE-USER]]</td>
<td>(UPUS)</td>
<td>Captures the user ID of the user who updated the record.</td>
</tr>

<tr>
<td>[[Field design#UTF-8 and UTF-16 attributes|UTF-8]]</td>
<td>(UTF8)</td>
<td>Data is stored in UTF-8 format and is treated as unicode data inside SOUL programs. The default is EBCDIC.</td>
</tr>

<tr>
<td>[[Field design#UTF-8 and UTF-16 attributes|UTF-16]]</td>
<td>(UTF16)</td>
<td>Data is stored in UTF-16 format and is treated as unicode data inside SOUL programs. The default is EBCDIC.</td>
</tr>
</table>

==System management enhancements==

===Writing records to the SMF data set===
Having Model 204 write records to the SMF data set no longer requires the installation of an SVC.

Therefore, the <var>[[SMFSVC parameter|SMFSVC]]</var> parameter is no longer required and, if present, will be ignored and flagged with the following informational message:
M204.0204: PARAMETER SMFSVC OBSOLETE AND NOT RESET
However, the <var>[[SMFLORN parameter|SMFLORN]]</var> and <var>[[SMFSLRN parameter|SMFSLRN]]</var> parameters must still be present in CCAIN to specify the types of SMF record to be written.

==Performance enhancements==

===64-bit addressing and Above The Bar (ATB) storage===
Model 204 moves above the (2G) bar to increase scalability, performance, and growth potential. With this release of Model 204, 64-bit addressing becomes the de facto standard for all subsequent versions.

In addition to the ATB support for FTBL released with Model 204 version 7.4, version 7.5 adds ATB support for GTBL, NTBL, and QTBL, using the same <var>[[SERVNSA parameter|SERVNSA]]</var> and <var>[[SERVNSSZ parameter|SERVNSSZ]]</var> parameters used for FTBL.

When using non-swappable ATB server space, each user will get SERVNSSZ bytes of ATB space, even if the thread is logged out or running resident requests. For greater efficiency, Model 204 version 7.5 also provides swappable ATB server areas that can supplement or replace the non-swappable areas. These swappable ATB server areas are controlled by the <var>[[SERVGA parameter|SERVGA]]</var> and <var>[[SERVGSZ parameter|SERVGSZ]]</var> parameters.

====GTBL, NTBL, QTBL in above the bar storage====
GTBL, NTBL and QTBL can now be placed into swappable or non-swappable server storage area above the bar.
In order to store a table in ATB storage:
<ul>
<li>Increase the <var>[[SERVNSSZ parameter|SERVNSSZ]]</var> parameter by the corresponding table size.
<li>Set the proper bit in <var>[[SERVNSA parameter|SERVNSA]]</var>:
<ul>
<li>for GTBL set the second byte to <code>X'80'</code>, so the value of <var>SERVNSA</var> is <code>X'00800000'</code></li>
<li>for NTBL set the third byte to <code>X'40'</code>, so the value of <var>SERVNSA</var> is <code>X'00004000'</code></li>
<li>for QTBL set the third byte to <code>X'20'</code>, so the value of <var>SERVNSA</var> is <code>X'00002000'</code></li>
</ul>
</ul>
'''Note:'''
The settings for each server table above the bar are independent of each other.
So if FTBL, GTBL, NTBL, and QTBL are all placed above the bar, then <var>SERVNSA</var> should be set to <code>X'02806000'</code>.

====XmlDoc pages in above the bar buffer pool====
With this release, the CCATEMP pages used for <var>XmlDoc</var> objects use the above the bar buffer pool, which may allow the below the bar buffer pool to be reduced, perhaps providing more storage for server areas. It also may provide a reduction in CPU utilization, especially when the <var>[[TEMPPAGE parameter|TEMPPAGE]]</var> parameter is used to allocate CCATEMP in memory.

===Improved range searching by Ordered Index (OI) chunk===
The new <var>[[DEFINE FIELD command#Ordered index CHUNK attribute|CHUNK]]</var> attribute for the <var>DEFINE FIELD</var> command enables more efficient range searching on Ordered Index numeric (<var>ORDERED NUMERIC</var>) fields. <var>CHUNK</var> improves performance of the <var>FIND</var> statement <var>RANGE</var> and <var>BETWEEN</var> terms. The <var>CHUNK</var> field attribute defines a subrange ("OI chunk") of the data range. Searching by OI chunks on a range of data requires fewer scans of the ordered index entries to find the desired data. Once OI chunk fields are defined, they are automatically used by FIND processing, so no application code needs to be changed.

After defining an <var>ORDERED NUMERIC</var> field, you define one or more related OI chunk fields containing data from the original base field rounded down by a specified <var>CHUNK</var> size.

Example:
DEFINE FIELD YYYYMMDD WITH ORDERED NUMERIC
DEFINE FIELD YYYYMM WITH ORDERED NUMERIC INVISIBLE CHUNK 100 FOR YYYYMMDD
DEFINE FIELD YYYY WITH ORDERED NUMERIC INVISIBLE CHUNK 10000 FOR YYYYMMDD


<var>CHUNK</var> requires the <var>[[#FILEORG (new settings)|FILEORG]]</var> X'100' bit setting and the <var>INVISIBLE</var> and <var>ORDERED NUMERIC</var> field attributes.

==Debugging and testing enhancements==
The SoftSpy debugging, testing, and performance tuning product is now included as part of the Model 204 core product. For more information about SoftSpy version 7.5, see the [[Release notes for SoftSpy V7.5]].

==Connect★ enhancements==
The 7.5 version of Connect★ for JDBC and Connect★ for .NET is now available.

===Connect★ for JDBC===
Connect★ 7.5 for JDBC offers a "connection pooling" class to interface with other pooling infrastructures provided by pooling packages and web application servers. This new feature allows for a pool of connections that remain active and open during execution of an SQL and RCL (SOUL) statement.
Using connection pooling helps eliminate the overhead of creating initial connections from scratch or trying to
manage each connection via JDBC API.

Each Connection Pool can create a pool of active connections maintainable throughout the connection cycle of the pooling service.

For a sample program, see the "Connect★ for JDBC" chapter of the <var class="book">Connect★ Installation and Programming Guide</var>.

Connect★ 7.5 for JDBC has been tested with the JNDI, Apache DBCPTM, BoneCP and C3PO pooling packages.

===Connect★ for .NET===
Connect★ 7.5 for .NET offers both 32-bit and 64-bit drivers that can be used with any Web or GUI-driven application.

==MQ/204 enhancements==

===Freeing MQ/204 subtasks and associated storage===
The new <var>MQDELDTP</var> PST (pseudo subtask) checks for MQ/204 subtasks that are in a delayed detach state. <var>MQDELDTP</var> detaches MQ/204 subtasks that have finished their work and releases their associated storage areas.

==Other features==
===AT-MOST-ONE and field groups===

The <var>AT-MOST-ONE</var> attribute is now applicable to a field group definition.

===Storing and updating LOBs===

All large object data (LOBs) in a <var>FILEORG</var> X'100' file are chained. There are four bytes per Table E page overhead for chained LOBs, used to maintain a queue of pages available for reuse after LOBs are deleted. The pages used by a chained LOB are not necessarily contiguous.


Handling LOBs in <var>FILEORG</var> X'100' files also has the following effects:
<ul>
<li>LOBs can be changed as needed. The <var>RESERVE</var> clause is ignored in a LOB field <var>ADD</var> statement processing, as well as the <var>STORE RECORD</var> statement processing of fieldname=value pairs. Consequently, the <var>CHANGE</var> statement does not fail because of insufficient reserved space. If the <var>CHANGE</var> statement requires that a LOB field be extended, it is.</li>

<li>The value of the <var>[[EHIGHPG parameter|EHIGHPG]]</var> parameter is always one less than the high water mark of the number of pages used to hold LOBs. (Unless none were ever added, in which case it is zero, not -1).</li>

<li>The value of the <var>[[EPGSUSED parameter|EPGSUSED]]</var> parameter is always the number of pages currently being used to hold LOBs.</li>

<li>The <var>COMPACTE</var> command does not process <var>FILEORG</var> X'100' files, just as it does not process a file created in V6R1 or earlier. Thus, issuing a <var>COMPACTE</var> command for a <var>FILEORG</var> X'100' file produces an error message.</li>

<li>The <var>TABLEE</var> command is effectively executing a <code>VIEW ESIZE EHIGHPG EPGSUSED</code> command for a <var>FILEORG</var> X'100' file. Consequently there are no <var>TABLEE</var> overhead pages in a <var>FILEORG</var> X'100' file.</li>
</ul>

===Constraint attributes===
You can set range constraints on fields using the constraint attributes. Each set of range attributes is comprised of four attributes (<var>GE</var>, <var>GT</var>, <var>LE</var>, <var>LT</var>) that you can use to establish a range for integer values, float values, or date-time stamp values. The types of range attributes are mutually exclusive. For example, you cannot define a field with the <var>FLOAT-GE</var> and <var>INTEGER-LE</var> attributes.

If a range constraint is redefined, it replaces the existing field constraint.

 Note: 
The range constraints do not have to match the data type of the stored field. That is, you could have a date-time constraint for a <var>STRING</var> field or an integer constraint for a <var>FLOAT</var> field, and so on.

You can set the following constraint attributes:
<ul>
<li>date-time value</li>
<li>pattern for a field value</li>
<li>length</li>
<li>integer value</li>
<li>floating point value</li>
</ul>

See [[Field design#Content constraints|Content constraints]] for details.

===Changes to journal record layouts===
Four bytes have been added to the journal record header for user statistic entries:
1 byte to hold the <var>IODEV</var> number and 3 bytes for future use.

All user since-last statistics (LAST=) lines will now show the <var>IODEV</var> value:
ST $$$ USERID='<var class="term">userid</var>' ACCOUNT='<var class="term">accountname</var>' IODEV='<var class="term">devicetype</var>' LAST='<var class="term">acty</var>'

For more information on journal records and user statistics, see the <var class="book">Rocket Model 204 System Manager's Guide</var>.

==Compatibility issues==
This section describes any compatibility issues between V7.5 and prior versions of Model 204.
An incompatibility arises if an operation that was previously performed without any indication of error, now operates (given the same inputs and conditions) in a different manner.

A normal bug fix resolving behavior that, although not indicating an error, was "clearly and obviously" incorrect, also introduces an incompatibility, but it might not be included below.

===Change to the Ordered Index layout===

Formerly all ORDERED NUMERIC fields came after all ORDERED CHARACTER fields in the Ordered Index. Now, the fields are interspersed in field code order.

===ZFIELD Image===

The [[ZFIELD image detail as of Model 204 V7.5|ZFIELD image]] has been updated for this release. The image is used with $LSTFLD and $FDEF function calls. One change is that FDEF is now longer (to accommodate FDEF1, LOOPVAR, and FDEF2).

===INTERCOMM is no longer supported===
The INTERCOMM interface supports the use of Teletype and 3270 terminals in line-at-a-time mode, using the Model 204 IODEV=29 thread type.

INTERCOMM is no longer supported as of Model 204 version 7.5.

See the <var class="book">Rocket Model 204 Terminal User's Guide</var> for a discussion of terminal interfaces.

===User PDL overflow===
The new <var>[[Release notes for Model 204 version 7.5 (DRAFT)#SEQPDL parameter|SEQPDL]]</var> parameter might require you to increase the size of the user Push Down List (using UTABLE LPDLST) by up to 3072 bytes, or more if you specify a value for SEQPDL that is larger than the 4096 default value.

===LPDLST parameter maximum value===
The maximum value for the <var>[[LPDLST parameter|LPDLST]]</var> parameter has been increased from 32760 to 65536.

===SSLIBSIZE parameter maximum value===
The maximum value for the <var>JANUS DEFINE</var> command <var>[[SSLIBSIZE (JANUS DEFINE parameter)|SSLIBSIZE]]</var> parameter has been decreased from 32767 to 16384.

==New and changed commands==

===DECREASE (new option: DYNAMIC)===
The DYNAMIC option on the <var>[[DECREASE command|DECREASE]]</var> command lets you decrease Table B dynamically, even if the file is open by others or has requests compiled against it.

===DEFINE DATASET (new parameter: GDGRECNT)===
The GDGRECNT parameter for the <var>[[DEFINE DATASET command|DEFINE DATASET]]</var> command causes Model 204 to check the catalog information for the latest relative GDG generation number whenever allocating a GDG data set.

===DEFINE FIELD (new or changed attributes)===
In Model 204 version 7.5, the <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> command has new attributes information:
<ul>
<li>the new <var>[[#Improved range searching by Ordered Index .28OI.29 chunk|CHUNK]]</var> attribute, which improves the efficiency of range finds using ordered index processing</li>
<li>many other <var>[[FILEORG parameter|FILEORG=x'100']]</var> related new or changed [[Release notes for Model 204 version 7.5 (DRAFT)#New field attributes|field attributes]]</li>
</ul>

===DEFINE FIELDGROUP (new in V7.5)===
The <var>[[DEFINE FIELDGROUP command|DEFINE FIELDGROUP]]</var> command establishes the contents of a field group, including the fields and field groups associated with the field group being defined.

===DELETE FIELD (changed to handle CAT and CTO fields)===
The <var>[[DELETE command: Field|DELETE FIELD]]</var> command has been changed to take [[Field design#CONCATENATION-OF .28CAT.29 attribute|CONCATENATION-OF (CAT)]] and [[Field design#Counting occurrences of a field|COUNT-OCCURRENCES-OF (CTO)]] fields into account. DELETE FIELD does not allow deletion of fields referred to by an existing CAT or CTO field.

===DELETE FIELDGROUP (new in V7.5)===
The <var>[[DELETE FIELDGROUP command|DELETE FIELDGROUP]]</var> command deletes a field group from a Model 204 file.

===DISPLAY FIELD (new option: COMMA)===
In Model 204 version 7.5, the <var>[[DISPLAY FIELD command|DISPLAY FIELD]]</var> command has added
the <var>COMMA</var> option, which uses commas to separate displayed field attributes.

===DISPLAY MODMAP (new in V7.5)===
<var>[[DISPLAY MODMAP command|DISPLAY MODMAP]]</var> displays the Model 204 link map in address order. System manager privileges are required.
===MSGCTL (new options: UP/UPPER, NOUP/NOUPPER)===
The <var>UP</var> (or <var>UPPER</var>) option on the [[MSGCTL command]] indicates that the specified message should be converted to uppercase before display. Similarly, the <var>NOUP</var> (or <var>NOUPPER</var>) option on the MSGCTL command undoes the effects of <var>UP</var> or <var>UPPER</var>.

===REGENERATE and REGENERATE ONEPASS (improved TO UPDATE option)===
The TO UPDATE option of the <var>[[REGENERATE command|REGENERATE]]</var> and <var>[[REGENERATE ONEPASS command|REGENERATE ONEPASS]]</var> commands can now handle multiple files.
If TO UPDATE <var class="term">nn</var> OF <var class="term">id</var> is specified, it must appear only on the first FILE statement, and no other �TO� options are allowed on subsequent files.
All additional files will be recovered as though they each specified the same 'TO UPDATE' option. Once the 'end of transaction' is reached, further processing will stop and all inflight transactions will be backed out.

===RENAME FIELDGROUP (new in V7.5)===
The <var>[[RENAME FIELDGROUP command|RENAME FIELDGROUP]]</var> command changes the name of a field group.

===UNICODE (new codepage: 1154)===
The <var>[[UNICODE command|UNICODE]]</var> command now accepts 1154 as a codepage name. This codepage has 92 Unicode characters in the range U+0400 through U+045F, representing the Basic Russian alphabet and all of the Cyrillic extensions excepting the four which have grave accents.


==Reliability enhancements==
===SEQPDL parameter===
The new <var>[[SEQPDL parameter|SEQPDL]]</var> parameter controls the amount of free space that must be present in the user's Push Down List (PDL) in order for the SOUL sequencer to proceed with the next quad code. The minimum and default value is 4096 bytes. The maximum value is 8192 bytes. SEQPDL is a user resettable parameter and can be set on the user's parameter line or reset with the UTABLE command.

Formerly 1024 bytes of PDL free space were hardcoded internally in the Model 204 core. With 1024 bytes there were edge cases where abends would break files, resulting in ERROR 2126 USER'S PUSHDOWN LIST OVERFLOWED. SEQPDL is provided to allow enough PDL space so that all of the lower level journaling routines can process error conditions without breaking files.

If your applications are using close to the amount of PDL space currently set by the LPDLST value, you might need to increase LPDLST to reflect SEQPDL's increase in free space.

==New and changed parameters==
In addition to the following specific parameter changes, <var class="product">Model 204</var> parameter descriptions, for example as displayed by the <var>VIEW</var> command, are now in mixed case (unless translated to uppercase due to <var>[[#UPCASMSG (new in V7.5)|UPCASMSG]]</var>.)

Note: The [[Sirius Mods]] parameters are merged with the <var class="product">Model 204</var> base as of <var class="product">Model 204</var> version 7.5, and they are available to all version 7.5 customers. The combined set of parameters is displayed on the [[List of Model 204 parameters]] page. The former Sirius parameters in that listing are marked with an (S). 


===DEFCNTX and APDFCNTX (for $View function only, new in V7.5)===
The string
<code>DEFCNTX</code> or <code>APDFCNTX</code> can be used as an
argument to the <var>[[$VIEW|$View]]</var> function to
get the default file or group context. Using these strings is better than using <code>$View('CURFILE')</code> because:
<ul>
<li><code>CURFILE</code> returns a null string if the default context is a group.

<li><code>CURFILE</code> is affected by the <var>IN</var> clause prior to a <var>Begin</var> command and
can be affected by the <var>In</var> clause prior to many SOUL statements.
</ul>

If there is no default context, <code>$View('DEFCNTX')</code> returns a null
string.

Otherwise <code>$View('DEFCNTX')</code> returns the type of context (<code>FILE</code>, <code>TEMP GROUP</code>, or
<code>PERM GROUP</code>) followed by the file or group name, with trailing blanks
removed.

<code>$View('APDFCNTX')</code> returns the same information based on the default
context when the APSY was entered, unless that is the same as one of the files or groups in the subsystem's definition; in that case, the null string is returned.

Note: These <code>$View</code> arguments were implemented as part of
maintenance to version 7.5 (via zap number 54). They are not available as ordinary parameters on the <var>VIEW</var> command.
In version 7.6 of Model 204,
they will also be available with the <var>VIEW</var> command.


===DSPOPT (change to default setting)===
The default setting for [[DSPOPT parameter|DSPOPT]] has been changed from X'00' to X'01'. The X'01' setting allocates space for servers in memory in chunks of 4K pages, not as a permanent contiguous area. This allocation lets you move fewer 4K pages, keeping the virtual storage allocated for servers in memory less fragmented and possibly using fewer paging tables.

===ECPSIZE (change to max value)===
The maximum value setting for [[ECPSIZE parameter|ECPSIZE]] has been increased from 1310680 to 1966020 to accommodate more [[Release notes for Model 204 version 7.5 (DRAFT)#External Call Facility .28ECF.29|External Call Facility]] parameters.

===FILEORG (new settings)===
<ul>
<li>
The <var>[[FILEORG parameter|FILEORG]] X'100'</var> setting for enhanced data handling files is now available.

X'100' enables a number of enhancements to the file structure, including: 
<ul>
<li>[[Release notes for Model 204 version 7.5 (DRAFT)#Support for physical field groups|Support for physical field groups]] </li>

<li>The definition of as many as 32000 fields in a file </li>

<li>System maintained [[Field design#Automatic Fields|Automatic fields]] </li>

<li>[[Field design#Field constraints|Field constraints]] providing content validation </li>

<li>Improved space management of fields containing [[Field design#BLOB, CLOB, and MINLOBE attributes|Large Objects]] </li>

<li>[[#New field attributes|New DEFINE FIELD attributes]], such as <var>CHUNK</var>
</ul>

If X'100' is selected, the X'80' bit (optimized field extraction files) is automatically set.</li>

<li>The <var>FILEORG X'200'</var> setting for large file support is now available. </li>

X'200' allows files to hold up to 48 million records.
</li>
</ul>

===FISTAT (change to X'08' setting)===
The <var>[[FISTAT parameter|FISTAT]] X'08'</var> (file full) setting is now automatically cleared in a transaction back out file if table D is increased enough so that DSIZE is greater than or equal to DPGSRES+DPGSUSED.

===LRETBL (setting increase may be necessary)===
Because there might be a slight increase in record locking table usage in V7.5, an increase in the value of the <var>[[LRETBL parameter|LRETBL]]</var> parameter is advised. The amount of the increase is best estimated by multiplying by 16 the <code>HWM HEADERS</code> value (from a <var>[[MONITOR ENQ command|MONITOR ENQ]]</var> report), then dividing by the value of the <var>NUSERS</var> parameter. For example, if <code>HWM HEADERS = 100000</code> and <code>NUSERS=2000</code>, the recommended <var>LRETBL</var> increase is <code>16*100000/2000</code>, or 800.

===MISCOPT (obsolete)===
The <var>[[MISCOPT parameter|MISCOPT]]</var> parameter is now obsolete. In Model 204 version 7.5, MISCOPT is still viewable but is not resettable.

===MODTIM (new in V7.5)===
The <var>[[MODTIM parameter|MODTIM]]</var> system parameter displays the most recent assembly date and time of the Model 204 load module.

===OUTPUT (change to allow OUTPUT=DUMMY)===
IODEV=3 threads definitions now allow OUTPUT=DUMMY.
When defining IODEV=3 threads, if output is not required, the OUTPUT parameter can be coded as OUTPUT=DUMMY.
For example:
IODEV=3,INPUT=IOD3IN1,OUTPUT=DUMMY
IODEV=3,INPUT=IOD3IN2,OUTPUT=DUMMY
IODEV=3,INPUT=IOD3IN3,OUTPUT=DUMMY
and so on.

This means that no DD statement is required for the output data set, and in cases where many
IODEV=3 threads are defined to simulate a large number of users, this enhancement will reduce the number of DD statements required by one half.

===RECLOCKO (X'04' bit now ignored)===
The <var>[[RECLOCKO parameter|RECLOCKO]]</var> X'04' bit is now ignored, and the extra information of the conflicting user number and lock time are now always available.

===RESPAGE (new in V7.5)===
The <var>[[RESPAGE parameter|RESPAGE]]</var> parameter activates the APSY Precompiled Procedures in storage feature using above the bar pages by specifying a number of 4K operating system pages.

Specifying RESPAGE stores precompiled procedures as resident requests above the bar in the RESPAGE area. Using RESPAGE allows you to substantially increase the resident request area and decrease server swapping of QTBL and NTBL pages.

Also, when RESPAGE is used, RESSIZE is reset and the storage below the bar specified by RESSIZE is no longer used.

Storing resident requests above the bar is independent of tables above the bar. You can use a combination of resident request and swappable servers ATB to reduce below the bar server sizes and thus increase the number of servers.

===RETRVKEY (change to allow forward retrieve PF key)===
New in this release, if you specify a non-zero setting of <var>[[RETRVKEY parameter|RETRVKEY]]</var>:
<ul>
<li>If you have set the <code>X'01'</code> or <code>X'10'</code> bits of the <var>[[RETRVOPT parameter|RETRVOPT]]</var> parameter, you can use a
forward retrieve PF key, in addition to the backward retrieve PF key specified by <var>RETRVKEY</var>.
'''Note:'''
If either of these bits is set, the <code>X'02'</code> bit is strongly recommended as well.
<li>The size of the allocated storage area, and hence the number and length of input lines available for retrieval, is specified
by the value of the <var>[[RETRVBUF parameter|RETRVBUF]]</var> parameter.</ul>

===SEQPDL (new in V7.5)===
The <var>[[Release notes for Model 204 version 7.5 (DRAFT)#SEQPDL parameter|SEQPDL]]</var> parameter controls the amount of free space that must be present in the user's Push Down List in order for the SOUL sequencer to proceed with the next quad code. SEQPDL allows enough PDL space for the lower level journaling routines to handle error conditions properly without breaking files and causing ERROR 2126 USER'S PUSHDOWN LIST OVERFLOWED.

===SESMAXTO (new in V7.5)===
The <var>[[SESMAXTO parameter|SESMAXTO]]</var> parameter can be used limit the maximum [[Sessions|session]] timeout value or to cause all current closed sessions to be immediately discarded.

===SMFSVC (obsolete)===
The <var>[[SMFSVC parameter|SMFSVC]]</var> parameter is [[Release notes for Model 204 version 7.5 (DRAFT)#Writing records to the SMF data set|obsolete]] as of Model 204 version 7.5.
===SNAPCTL (change to default setting)===
The default setting for [[SNAPCTL parameter|SNAPCTL]] has been changed from X'41' (X'44' under CMS) to X'28'. The X'28' setting results in smart snaps – relatively small snaps with all the information that is likely to be required to diagnose the cause of the snap. This setting allows snaps to be taken quickly, and for those snaps being easily sent to Rocket support with little or no adverse effect on the possibility of diagnosing the cause of the snap.

===UPCASMSG (new in V7.5)===
The <var>[[UPCASMSG parameter|UPCASMSG]]</var> parameter can be used to translate messages issued by <var class="product">Model 204</var> to uppercase; otherwise (depending on the message being issued) they are displayed in mixed (upper and lower) case.




==Documentation conversion to wiki format==
Rocket Model 204 documentation is being converted from individual manuals in PDF format to a set of cross-linked HTML articles in this integrated wiki, M204wiki.

As of Model 204 release 7.5, several manuals are now in wiki format and the rest remain in PDF format, available in the M204 folder of the [http://docs.rocketsoftware.com/nxt/gateway.dll?f=templates$fn=default.htm Rocket Software Documentation Library].

For details, see [[Model 204 documentation]].

==New and updated messages==

Many messages have been updated and added in this release. See [[New and updated messages in Model 204 version 7.5]] for details.

[[Category: Release notes]]

Processing multiply occurring fields and field groups

2014-08-01T13:44:53Z

Mlarocca:

<div class="toclimit-3">

==Overview==

A single field name that has different values can be stored repeatedly in a record. For example, the field <code>CHILD</code> in the record shown below is an example of a multiply occurring field:
FATHER = JOHN DOE
CHILD = ELIZABETH
CHILD = ROBERT


Any field name except for the following types of fields can be present more than once in a record: 
<ul>
<li>A NUMERIC RANGE field </li>
<li>A sort key </li>
<li>A hash key </li>
</ul>

<div id="FIELDGROUP overview"></div> 

JOHN DOE might also have a medical record that recorded multiple surgeries, each of which is associated with a surgeon and a date. His record contains repeated instances of these three related fields:
SURGERY_TYPE
SURGEON
SURGERY_DATE 

As of version 7.5 of <var class="product">Model 204</var>, SOUL lets you define these fields as part of a "physical" field group, which means they are stored, retrieved, and updated as a single instance of, say, the <code>SURGERY</code> field group. You could define these fields as individual multiply occurring fields and group them logically in your SOUL code, but the physical field group structure has significant processing efficiencies.

Field groups may only be defined for records in files that have the <var>[[FILEORG parameter|FILEORG]]</var> parameter set to include <code>X'100'</code>. Information about how to define a field group is found in [[Field group design#Defining a field group|Defining a field group]].

===Special processing for multiply occurring fields and field groups===

Certain SOUL statements operate differently on multiply occurring fields and field groups than on singly occurring fields. SOUL provides special statements and forms of statements that can be used with multiply occurring fields and field groups, notably including the <var>EACH</var> modifier and subscripts. SOUL also provides for the use of subscripted field references for accessing a particular occurrence of a multiply occurring field or field group.

==FIND statement==

===Retrieval by an exact occurrence value===

====Example 1====

Assume this sample record: 
FATHER = JOHN DOE
CHILD = ELIZABETH
CHILD = ROBERT


You can use either of these two statements to retrieve the record: 
FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD = ELIZABETH
END FIND

FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD = ROBERT
END FIND


====Example 2====

The record is not retrieved by either of these statements:
FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD = NOT ELIZABETH
END FIND

FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD = NOT ROBERT
END FIND


===Multi-condition range retrievals===

You should pay special attention to the effect of multiply occurring fields on multi-condition range retrievals. Undesirable results can occur if a range search is specified for a multiply occurring field. For example: 
FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD IS AFTER KEN AND BEFORE PAUL
END FIND


retrieves the sample record even though neither child's name in the sample is between KEN and PAUL. <var class="product">Model 204</var> evaluates each condition of the FIND separately, then combines the results of each evaluation to build the set of records satisfying all conditions. The BETWEEN operator behaves exactly like any other multi-condition range retrieval when used on a multiply occurring field.

If a range search must be performed on a multiply occurring field, use the IN RANGE clause of the FIND statement. Refer to [[Record retrievals#NUMERIC RANGE and ORDERED NUMERIC attributes|NUMERIC RANGE and ORDERED NUMERIC attributes]] for more information about the IN RANGE clause. Better code for the previous example is: 
FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD IS ALPHA IN RANGE
AFTER KEN AND BEFORE PAUL
END FIND


===Use of subscripts===

You cannot use subscripted references with the FIND statement. Refer to [[#Subscripts|Subscripts]] for more information about using subscripts with multiply occurring fields.

==NOTE statement==

===Only first occurrence is noted===

The NOTE statement notes only the first occurrence of a multiply occurring field. For example, only the first occurrence of the field (CHILD = ELIZABETH) are noted by:
KEEP.CHILD: NOTE CHILD


===Use of subscripts===

In order to note a particular occurrence of a multiply occurring field, the field name must be subscripted. Refer to the discussion of subscripts on [[#Subscripts|Subscripts]] for detailed information on subscripted field names and usage.

==PRINT and PRINT n statements==

===PRINT statement output format===

The PRINT statement prints only the first occurrence of a field in a record. 

If there is more than one value of a field in a record, the special modifier, EACH, can be used in a PRINT statement to print out all the values on a single line, with a single space between values.

====Example 1====
PRINT EACH INCIDENT


yields:
T1 T2 T1 T3 T2 T1


====Example 2====

If the field is given a column position, as in:
PRINT FULLNAME WITH EACH INCIDENT AT COLUMN 18


values are printed one to a line and positioned at the column specified. 
ABBOTT, GAIL H T1 -
T3 -
T1 -
T3 -
T2 -
T1


====Example 3====

A field cited in a PRINT statement after a multiply occurring field is printed on the same line as the last value of the multiply occurring field. If you change the PRINT statement in the sample request as here:
PRINT FULLNAME WITH EACH INCIDENT AT COLUMN 18 -
WITH POLICY NO AT COLUMN 23 -
WITH STATE AT COLUMN 32


This output results:
ABBOTT, GAIL H T1 -
T3 -
T1 -
T3 -
T2 -
T1 100340 CALIFORNIA


===Use of subscripts===

See [[#PRINT statement|PRINT statement]] for a description of using PRINT with subscripts.

===PRINT n statement===

Long fields, such as abstracts, evaluations, or statements of purpose, can be stored as a multiply occurring field. Each occurrence can contain as many as 255 characters. 

====Syntax====

You can use this PRINT statement to print such a field as a paragraph:
PRINT n fieldname


where <var class="term">n</var> must be a number less than 32,768.

====Output format====

The <var>PRINT n</var> statement prints up to n lines of text, composed of all of the occurrences of the field concatenated in order. Nothing is inserted. At most, n lines are printed; any extra lines are ignored. 

Ordinarily, a PRINT statement that produces more than one line inserts a hyphen in the continuation column of the output device. Instead of using the continuation column, this form of PRINT attempts to end each line with a complete word delimited by spaces. If there is insufficient space to fit the last word on a line, the word is hyphenated arbitrarily and continued on the next line. 

The AT COLUMN and TO COLUMN clauses can be used to adjust the output to a narrower column. When used together with PRINT n, text is broken at word boundaries to fit within the column. The AT clause does not affect the first line, and the TO clause does not affect the last line (unless the line limit n is exceeded). This allows indenting. 

The AT or TO column options cannot accept negative numbers or numbers greater than 32767 for the column. 

Procedures containing PRINT statements with negative numbers or numbers greater than 32767 fail at compile time with the following counting error message:
M204.0263: AT/TO MUST BE BETWEEN 1 AND 32767


====Example====

This example illustrates the use of the <var>PRINT n</var> statement.
BEGIN
PRINT '1234567890123456'
STORE RECORD
TEXT = 'NOW IS THE T'
TEXT = 'IME FOR'
TEXT = ' ALL GOOD MEN TO'
ITEM = 1
END STORE
FD.REC: FIND ALL RECORDS FOR WHICH
ITEM = 1
END FIND
FOR 1 RECORD IN FD.REC

PRINT.TEXT: PRINT <nowiki>''</nowiki> AT COLUMN 5 WITH 3 TEXT -
AT COLUMN 3 TO 16
END FOR
END


The output produced is:
1234567890123456
NOW IS THE
TIME FOR ALL
GOOD MEN TO


The <code>PRINT.TEXT</code> statement concatenates a null value (two single quotes with no space between them) with the <var>PRINT n</var> form to indent the first line of text by using the location of the null value (column 5).

Note that the printing stops short of column 16 to avoid truncating TIME and GOOD. 

====Use with subscripts====

You cannot use subscripted references with the PRINT n statement. Refer to [[#Subscripts|Subscripts]] for more information about using subscripts with multiply occurring fields.

==ADD, CHANGE, and DELETE statements==

The ADD and CHANGE statements, and both forms of the DELETE statement, are supported in remote file and scattered group contexts.

===ADD statement===

The ADD statement places new occurrences of a field after existing occurrences. For example, if new children are added to the sample record, the additions are placed last. Thus: 
ADD CHILD = SARAH
ADD CHILD = PATRICK


results in the record:
FATHER = JOHN DOE
CHILD = ELIZABETH
CHILD = ROBERT
CHILD = SARAH
CHILD = PATRICK


====The INSERT statement====

If the order of occurrence is important, the INSERT statement can be used to add new occurrences. See the discussion on [[#INSERT statement|INSERT statement]]. 

===CHANGE statement===

The CHANGE statement alters only the first occurrence of a field in a record. 

====Syntax====

You can use this form of the CHANGE statement if there is more than one occurrence: 
CHANGE fieldname = value1 TO value2


This form, like the <var>CHANGE fieldname</var> statement, can be used only inside a FOR EACH RECORD loop. It deletes the first occurrence of the pair fieldname = value1 from a record, and adds the pair fieldname = value2 to the record. The new value is added either in the position occupied by the original value or at the end of the record, depending upon the update attribute specified for the field by the file manager. See the discussion in [[#UPDATE field attribute|UPDATE field attribute]]. 

If the specified field, <var class="term">fieldname</var> = <var class="term">value1</var>, does not appear in the record, <var class="term">fieldname</var> = <var class="term">value2</var> is simply added to the record. If the specified <var class="term">fieldname</var> = <var class="term">value1</var> pair appears more than once in the record, only the first occurrence of it is deleted. The pair, <var class="term">fieldname</var> = <var class="term">value2</var>, is added just once. Occurrences of the field name that have other values are not altered by the statement. 

===DELETE statement===

The DELETE statement deletes only the first occurrence of the field in the record by default. 

====Two forms of DELETE statement====

For multiply occurring fields, two forms of the DELETE statement are provided; however only for use inside a FOR EACH RECORD loop: 
<table>
<tr class="head">
<th>To delete... </th>
<th>Syntax </th>
<th>Usage</th>
</tr>

<tr>
<td>A particular occurrence </td>
<td nowrap>DELETE fieldname = value </td>
<td>

To delete the first occurrence of the pair, <var class="term">fieldname</var> = <var class="term">value</var>, from a record. Occurrences of the field that have other values are not removed. If the field with the specified value:

Occurs more than once in the record, only the first occurrence is deleted. 

Cannot be found, no deletion occurs.
</td>
</tr>

<tr>
<td>Every occurrence of the field in the record </td>
<td>DELETE EACH fieldname </td>
<td>To delete all occurrences of the specified field name. The field to be deleted cannot have the INVISIBLE attribute. </td>
</tr>
</table>

====Use with the FOR EACH OCCURRENCE statement====

See [[#Deleting occurrences of fields and field groups|Deleting occurrences]] for a discussion of deleting occurrences using the FOR EACH OCCURRENCE OF (FEO) statement.

====Use with subscripts====

See [[#DELETE statement|DELETE statement]] for a discussion of using the DELETE statement with subscripts.

==SORT RECORDS statement==

When a multiply occurring field is chosen as a sort key, each record in the set being sorted is processed once using the first occurrence of the field as the key. 

===EACH modifier with one sort field===

If the EACH modifier is present in the SORT statement and if there are n occurrences of the field in the record, similar records are created in the sorted copy of the original set. 

====Example====

The following request:
SORT RECORDS IN FIND.RECS BY EACH KEY


generates three temporary records for the single permanent record in which the field named <code>KEY</code> occurs three times:
KEY = COMPUTER
KEY = CORPORATION
KEY = AMERICA


The records generated are:
1 KEY = COMPUTER 2 KEY = CORPORATION
KEY = CORPORATION KEY = AMERICA
KEY = AMERICA KEY = COMPUTER

3 KEY = AMERICA
KEY = COMPUTER
KEY = CORPORATION


These correspond to the <var class="term">n</var> cyclic permutations of the set of field occurrences and, in this example, are sorted into the order 3, 1, 2 (if no other option is selected). Statements that refer to the sorted set, such as PRINT, PRINT EACH, NOTE, and PRINT ALL INFORMATION (PAI), reflects the permutation. No record is generated if <var class="term">n</var> = 0.

===EACH modifier with several key fields===

When the EACH option is selected for several keys, <var class="term">n</var> occurrences of one key and <var class="term">m</var> of another produce differently permuted records. If either <var class="term">n</var> or <var class="term">m</var> equal 0, no records are generated. 

====Example====

This request:
BEGIN
FIND.RECS: IN CLIENTS FIND ALL RECORDS FOR WHICH
INCIDENT = T1
END FIND
SORT.RECS: SORT RECORDS IN FIND.RECS BY FULLNAME -
AND EACH INCIDENT DATE
FOR EACH RECORD IN SORT.RECS
PRINT FULLNAME WITH INCIDENT DATE -
AT COLUMN 25
END FOR
END


produces printed output of:
ABBOTT, FRANKLIN G 860323
ABBOTT, GAIL H 861022
ABRAMS, RUTH Z 861115
ABRAMS, RUSSELL Y 870218
ABBOTT, FRANKLIN G 870424
ABBOTT, GAIL H 871123
. .
. .
. .


===If no occurrences are present===

A record that does not contain at least one occurrence of the INCIDENT DATE field produces no printed output. Similarly:
SORT RECORDS IN FIND.RECS BY EACH A AND EACH B


would produce nothing for those records that do not have at least one occurrence of both A and B. 

==FOR EACH RECORD statement==

The FOR EACH RECORD IN ORDER BY statement retrieves and loops on only the first occurrence of a field in a record. 

===EACH modifier===

If there is more than one value of a field in a record, the special modifier, EACH, can be used to retrieve and loop on all values of the field. 

The EACH modifier only can be used on a FOR EACH RECORD statement that specifies index order processing (the IN ORDER BY fieldname clause must be used and the field must have the ORDERED attribute). The VALUE IN phrase must be used to retrieve the current value of the ORDERED field driving the loop. 

====Example====

This example of the FOR EACH RECORD IN ORDER BY statement:
BEGIN
FR1: FOR EACH RECORD IN ORDER BY EACH INCIDENT DATE
PRINT VALUE IN FR1 WITH FULLNAME AT COLUMN 25
END FOR
END


returns each record in order by each value of the ORDERED field, as follows:
760323 ABBOTT, FRANKLIN G
761022 ABBOTT, GAIL H
761115 ABRAMS, RUTH Z
770218 ABRAMS, RUSSELL Y
.
.
.


==Special statements for multiply occurring fields and field groups==

SOUL provides several statements for handling multiply occurring fields and [[Field group design|field groups]]. Field groups are supported as of Model 204 version 7.5.
<ul>
<li>COUNT OCCURRENCES (used with singly occurring fields, too)</li>
<li>FOR ALL OCCURRENCES OF FIELDGROUP </li>
<li>FOR EACH OCCURRENCE (used with singly occurring fields, too)</li>
<li>FOR FIELDGROUP</li>
<li>DELETE EACH OCCURRENCE</li>
</ul>
Note: See also the [[#INSERT statement|INSERT statement]], which you can use to add new occurrences of a field.

===COUNT OCCURRENCES OF statement===

The COUNT OCCURRENCES OF (CTO) statement counts the number of occurrences of the named field in the current record. 

====Syntax====

The format of the COUNT OCCURRENCES statement is:
label: COUNT OCCURRENCES OF fieldname


or
label: CTO fieldname


The field name cannot be subscripted. The COUNT OCCURRENCES OF statement can appear only within a FOR EACH RECORD loop.

The COUNT OCCURRENCES statement is supported in remote file and scattered group contexts.

====COUNT IN clause====

The COUNT IN clause refers to the count obtained by the COUNT OCCURRENCES OF statement. This request:
BEGIN
FIND.RECS: IN VEHICLES FIND ALL RECORDS
END FIND
FOR 5 RECORDS IN FIND.RECS
NO.OF.VINS: COUNT OCCURRENCES OF VIN
PRINT OWNER POLICY WITH ' INSURES ' WITH -
COUNT IN NO.OF.VINS WITH ' VEHICLE(S)'
END FOR
END


generates the following output:
100025 INSURES 1 VEHICLE(S)
100030 INSURES 1 VEHICLE(S)
100032 INSURES 1 VEHICLE(S)
100051 INSURES 1 VEHICLE(S)
100058 INSURES 1 VEHICLE(S)


===FOR ALL OCCURRENCES OF FIELDGROUP (FAO FIELDGROUP) statement===
The FAO statement collects the field group IDs for all occurrences, then processes against that list. FAO is not valid for use against multiply-occurring fields, only against field groups (introduced in Model 204 V7.5).

====Syntax====

The format of the statement is:
FOR ALL OCCURRENCES OF FIELDGROUP (fgname | %%varGrp)

Where:
<ul>
<li><var class="term">fgname</var> specifies a field group name.</li>

<li>%%<var class="term">varGrp</var> specifies a field group name variable.</li>
</ul>
The difference between an FAO statement and an FEO statement is that the FAO statement is less affected by insertions or deletions of FIELDGROUP <var class="term">fgname</var> within the loop, due to the semantics of field group IDs. This means that deleting the current occurrence within the loop will not affect occurrences referenced in subsequent iterations.

===FOR EACH OCCURRENCE OF loops===

On each loop of FOR EACH OCCURRENCE OF (FEO), the VALUE IN and OCCURRENCE IN labels refer to value and position, respectively, of the next field occurrence, starting with occurrence 1 and increasing by 1 for each pass through the loop. When the next field occurrence number is greater than the number of field occurrences in the record, the loop terminates. 

====Syntax====

The format of the FOR EACH OCCURRENCE loop is:
label: FOR EACH OCCURRENCE OF fieldname


Alternatively,
label: FEO fieldname


The FOR EACH OCCURRENCE OF statement is supported in remote file and scattered group contexts.

To work with specific field values inside an FEO loop, two styles of reference are supported: OCCURRENCE IN {label}, which is used as a field subscript, and VALUE IN {label} with is a direct reference to a field occurrence.

====Example====

Consider this record:
FIRST NAME = RICHARD
LAST NAME = SMITH
CHILD = HENRY
CHILD = SALLY
CHILD = JANE
ADDRESS = AVON DRIVE


This request creates a separate record for each child.
BEGIN
FD.REC: FIND ALL RECORDS FOR WHICH
FIRST NAME = RICHARD
LAST NAME = SMITH
END FIND
FOR EACH RECORD IN FD.REC
NOTE.ADD: NOTE ADDRESS
CHILD.LOOP: FOR EACH OCCURRENCE OF CHILD
PRINT VALUE IN CHILD.LOOP
STORE RECORD
FIRST NAME = VALUE IN CHILD.LOOP
LAST NAME = SMITH
ADDRESS = VALUE IN NOTE.ADD
END STORE
END FOR
END FOR
END


====Simulating a FOR EACH VALUE loop====

The FOR EACH OCCURRENCE OF statement can be used to simulate a FOR EACH VALUE loop if the field contains a static collection of known values. Consider the values of states. The user sets up a single record that has a multiply occurring field in sorted sequence as follows: 
TYPE = STATE
CODE = ALABAMA
CODE = ARKANSAS
.
.
CODE = WYOMING


These statements begin a request to generate a report in order by state:
BEGIN
FIND.TYPE: FIND ALL RECORDS FOR WHICH
TYPE = STATE
END FIND
FOR EACH RECORD IN FIND.TYPE
EACH.CODE: FOR EACH OCCURRENCE OF CODE
FIND.STATE: FIND ALL RECORDS FOR WHICH
STATE = VALUE IN EACH.CODE
END FIND
FOR EACH RECORD IN FIND.STATE
.
.


This method has the advantage of eliminating the internal sort required by FOR EACH VALUE IN ORDER and provides an easy way to simulate a FOR EACH VALUE loop for a field that does not have the FRV or ORDERED attribute. However, a change in the list of values can require a recreation of the TYPE record to keep the values in order. Recreation is not required if the UPDATE IN PLACE field attribute has been specified for the CODE field and if the new and old values occupy the same place in order. Recreation also is not required if the [[#INSERT statement|INSERT statement]] is used correctly. 

====VALUE IN with FOR EACH OCCURRENCE loops====

VALUE IN references to FOR EACH OCCURRENCE (FEO) statements from outside the FEO loop does not compile. Such references receive the following error message:
M204.0311 UNACCEPTABLE STATEMENT REFERENCE


At runtime, the space occupied in STBL by the FEO value is reclaimed after each iteration of the FEO loop (including the last). This results in a reduction in the runtime STBL space requirements of some programs that use FEO.

To avoid getting that error, move the value into a %variable inside the FEO loop, and then reference the %variable outside the FEO loop.

====FOR EACH OCCURRENCE against INVISIBLE fields====

Using FOR EACH OCCURRENCE (FEO) syntax against INVISIBLE fields is a waste of processing time. An FEO causes a scan of the current Table B record, but INVISIBLE fields are not stored in Table B, so an FEO against an INVISIBLE field can never find any occurrences. Prior to V4R2.0 this programming flaw was masked because using FEO syntax against an INVISIBLE field compiled and evaluated successfully, although it never found occurrences. 

Beginning in V4R2.0, FEO syntax against an INVISIBLE field results in compilation error:
M204.0320 Field is invisible. Field = fieldname


===Deleting occurrences of fields and field groups===

The DELETE EACH statement can be used to delete all occurrences. 

Note: You must take care when deleting occurrences of a field or fieldgroup using the FOR EACH OCCURRENCE loop. When used to delete occurrences, and without a numbered occurrence reference on the field name, the first 50% of occurrences of a multiply occurring field are deleted. If there are an odd number of occurrences of the field on the record, the first half, up to and including the middle occurrence, are deleted.

====Example====
Suppose the following statement is specified for the <code>RICHARD SMITH</code> record described previously:
 for each occurrence in fd.rec
del.child: for each occurrence of child
delete child
end for
end for


The record originally contained these <code>CHILD</code> entries:
CHILD=HENRY
CHILD=SALLY
CHILD=JANE


On the first pass through the loop, the first value, <code>HENRY</code>, is selected and deleted. At the end of the first pass, the record contains these <code>CHILD</code> entries:
CHILD=SALLY
CHILD=JANE


On the second pass through the loop, the <code>DELETE CHILD</code> statement again deletes the first occurrence of the field as described in [[#DELETE statement|DELETE statement]]. Since <code>HENRY</code> has already been deleted, <var class="product">Model 204</var> deletes the first entry, <code>SALLY</code>.

After the second pass, the <var>FOR EACH OCCURRENCE</var> loop terminates. This is because the value in <code>DEL.CHILD</code> should be the next (third) occurrence, but after two passes, only one occurrence remains on the record. Therefore, at the end of the <var>FOR EACH OCCURRENCE</var> loop, the remaining value in the <code>CHILD</code> field is:
CHILD=JANE

Note: In general, it is a mistake to reference a multiply occurring field in an <var>FEO</var> loop without using an occurrence subscript. An unsubscripted reference always refers to the first occurrence of a field.

====Example 2====
Now suppose an occurrence reference is added to the field in the <var>FEO</var> loop:
 for each record in fd.rec
del.child: for each occurrence of child
delete child(occurrence in del.child)
end for
end for


The above will result in every other occurrence being deleted, because the occurrence reference continues to increment upward while the list of occurrences is also shifted, so the second time through the loop, the occurrence pointer is pointing to the item that was formerly the third item, then the fifth item, then the seventh item. Again, this is generally not what the programmer intends.

The solution is either:
<ul>
<li>Use the <var>DELETE EACH</var> syntax.</li>

<li>Loop over the occurrences in reverse order. </li>
</ul>

There is no specific syntax for reversing the order of an <var>FEO</var> loop, so you must count the occurrences and step backward through them in an index loop, like this:
childCount: -
count occurrences of child
for each record in %myRecordSet
for %x from count in childCount to 1 by -1
delete child(%x)
end for
end for


Stepping backward through a set is also the standard practice in <var>StringList</var> and <var>NamedArrayList</var> objects, when deletions may occur. This technique is especially worth keeping in mind in situations where only some occurrences may be deleted.

When using field groups, the <var>FOR ALL OCCURRENCES</var> syntax, introduced with Model 204 V7.5, performs as expected.

====Deleting with an FEO FIELDGROUP versus FAO FIELDGROUP loop====
An <var>FEO FIELDGROUP</var> statement on field groups has the same semantics as an <var>FEO</var> statement on a single field. When you iterate in an <var>FEO FIELDGROUP</var> or <var>FEO</var> loop, the next occurrence processed is the occurrence number one greater than the one processed before, whether or not it is one you have already processed (because of insertions) or whether or not you skip one or more (because of deletions). For example:
<ul>
<li>Following the standard behavior for moving forward through a set of occurrences in an <var>FEO</var> loop, <var>FEO FIELDGROUP</var> deletes every other occurrence of the field group:
xon: -
feo fieldgroup vehicle
delete fieldgroup(occurrence in xon)
end for

This behavior is a historical anomaly, but it is maintained for backward compatibility purposes. </li>

<li>To delete all occurrences of a field group, use an <var>FAO FIELDGROUP</var> statement:
fao fieldgroup vehicle
delete fieldgroup
end for
</li>
</ul>

===FOR FIELDGROUP statement===
The FOR FIELDGROUP statement operates on a specific occurrence of a field group. The occurrence is indicated by either an occurrence number or a field group ID number.

====Syntax====
The format of the statement is:
FOR FIELDGROUP (fgname | %%varFgname) { (occurrence-number) | = fieldgroupID }

Where:
<ul>
<li><var class="term">fgname</var> specifies a field group name. </li>

<li>%%<var class="term">varGrp</var> specifies a field group name variable. </li>

<li><var class="term">occurrence-number</var> specifies an occurrence within that field group. The occurrence number must be enclosed in parentheses.

The <var>[[$FieldgroupOccurrence]]</var> function returns the field group occurrence value. </li>

<li><var class="term">fieldgroupID</var> specifies a field group ID, which is unique for a record. A field group ID is assigned when a field group is added to the record, is equal to one more than the highest field group ID that has been assigned in the record, and is not reused if its field group is deleted.

<var class="term">fieldgroupID</var> must be preceded by an equal sign. 

The <var>[[$FieldgroupId]]</var> function returns the field group ID. </li>
</ul>

====Examples====
This <var>FOR FIELDGROUP</var> statement sets the third occurrence of the <code>DRIVER</code> field group as the context for the <var>Print</var> statement:
FR Where ...
For Fieldgroup DRIVER (3)
Print DRIVER_ID
End For
End For 

This <var>FOR FIELDGROUP</var> statement uses a [[Using variables and values in computation#Field name variables|field name variable]] to set the <code>DRIVER</code> field group that has ID <var class="term">%fgid</var> as the context for the <var>Print</var> statement: 
FR Where ...
%driver = 'DRIVER'
For Fieldgroup %%driver = %fgid
Print DRIVER_ID And DRIVER_NAME
End For
End For


==Setting field group context==
To access data in a field group, first establish the record context using the
<var>FOR EACH RECORD</var> (<var>FR</var>) or <var>FOR RECORD NUMBER</var> (<var>FRN</var>) statement. Then to access the occurrences of the field group, you typically use an <var>FAO FIELDGROUP</var> or <var>FEO FIELDGROUP</var> loop.

===Using a FOR ALL OCCURRENCES OF loop===
You can set field group context with an <var>FAO</var> loop. For example:
BEGIN
IN POLICIES FOR EACH RECORD
FAO: FAO FIELDGROUP VEHICLE
IF COLOR IS LIKE '*RED*' THEN
PRINT 'POLICY:' AT 5 AND POLICY_NUMBER AND -
'COLOR=' WITH COLOR
%RED = %RED + 1
END IF
END FOR
END FOR
PRINT 'NUMBER OF RED CARS:' AND %RED
END

The result is:
 POLICY: 100001 COLOR=VICTORY RED
POLICY: 100007 COLOR=RED
POLICY: 100011 COLOR=VICTORY RED
...
NUMBER OF RED CARS: 214

...and so on...


===Using a FOR EACH OCCURRENCE loop===
An <var>FEO</var> loop on a field group establishes a field group context. Inside the loop, references to field group fields are to their occurrences in their field group. For example:
BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
FEO: FEO FIELDGROUP VEHICLE
%DRIVER_ID = OTHER_DRIVER
PRINT OCCURRENCE IN FEO AND MAKE AND MODEL AND -
'OTHER DRIVER(S):' AT 30 AND EACH OTHER_DRIVER
PRINT 'FIRST:' AT 30 AND %DRIVER_ID AND -
'THIRD:' AND OTHER_DRIVER(3)
END FOR
END FOR
END 

The result is:
1 AUDI A4 QUATTRO OTHER DRIVER(S): 100035 100037 100036
FIRST: 100035 THIRD: 100036
2 CADILLAC SEVILLE OTHER DRIVER(S):
FIRST: THIRD:


An important difference between an <var>FAO FIELDGROUP</var> statement and an <var>FEO
FIELDGROUP</var> statement is that the <var>FAO FIELDGROUP</var> statement collects the
field group IDs for all occurrences, then processes against that list. Because of
this, it is less affected by insertions or deletions of occurrences of field groups
within the loop. Deleting the current occurrence within the
loop, for example, will not affect occurrences referenced in subsequent iterations.
For further discussion of this, see [[#FEO loops and field group context|FEO loops and field group context]], below. 

===Using a FOR FIELDGROUP block===
You can use a field group occurrence established by a [[#FOR FIELDGROUP statement|FOR FIELDGROUP block]] as the context for references to its members.

For example, the following <var>PAFGI</var> (<var>PRINT ALL FIELD GROUP INFORMATION</var>) statement outputs the contents of only the third occurrence of field group <code>GRP</code>:
IN FILE WHATEVER FRN %RECNO
FOR FIELDGROUP GRP(3)
PRINT ’*** Third occurrence of field group GRP’
PAFGI
END FOR
END FOR 

===Accessing field group members while not in field group context===
You can access field group occurrences by using the occurrence number
directly in the FR loop, if the field is [[Field design#AT-MOST-ONE, REPEATABLE, and EXACTLY-ONE attributes|EXACTLY-ONE or AT-MOST-ONE]]. So, instead of using this <var>FEO FIELDGROUP</var> loop to print the <code>MAKE</code> and <code>MODEL</code> for the three vehicles in the <code>VEHICLE</code> field group:
BEGIN
FR WHERE POLICY_NUMBER = 100095
FEO FIELDGROUP VEHICLE
PRINT MAKE AND MODEL
END FOR
END FOR
END


Output: 
VOLKSWAGEN NEW BEETLE
MITSUBISHI ECLIPSE
CHEVROLET SUBURBAN 

You can also access the <code>MAKE</code> and <code>MODEL</code> (<var>EXACTLY-ONE</var>) fields directly within the <var>FR</var> loop by using occurrence numbers: 
BEGIN
FR WHERE POLICY_NUMBER = 100095
PRINT MAKE AND MODEL
PRINT MAKE(2) AND MODEL(2)
PRINT MAKE(3) AND MODEL(3)
END FOR
END 

Output: 
VOLKSWAGEN NEW BEETLE
MITSUBISHI SUBURBAN
CHEVROLET SUBURBAN 
Note:
If <code>MAKE</code> and <code>MODEL</code> are <var>REPEATABLE</var> fields or defined to all field groups (<code>FIELDGROUP *</code>), attempting to access them with just an <var>FR</var> loop will fail. 

===Missing data in field groups===
As with non-field group field references for missing occurrences, the field values are returned as null (see the reference to <code>OTHER_DRIVER(3)</code> in the preceding example). The exception is <var>EXACTLY-ONE</var> fields in field groups, where the field's default value is returned for missing occurrences.

===Handling nested field group context===
If field groups are nested, you can always retrieve an <var>EXACTLY-ONE</var> field in a field group inside the current context without establishing that nested field group's context.
<var>EXACTLY-ONE</var> fields in specific field groups (as opposed to fields defined with <code>FIELDGROUP *</code> that belong to all field groups) can be retrieved outside the field group context.
In the following example, <code>CLAIM-NUMBER</code> is an <var>EXACTLY-ONE</var> field in field group <code>CLAIM</code> which is nested within field group <code>VEHICLE</code>:

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100095
PRINT POLICY_NUMBER
FEO FIELDGROUP VEHICLE
PRINT MAKE AT 5 AND MODEL
PRINT '1)' AND CLAIM_NUMBER
PRINT '2)' AND CLAIM_NUMBER(2)
PRINT '3)' AND CLAIM_NUMBER(3)
END FOR
END FOR
END 

The result is: 
100095
VOLKSWAGEN NEW BEETLE
1)
2)
3)
MITSUBISHI ECLIPSE
1) 100059
2) 100064
3)
CHEVROLET SUBURBAN
1)
2)
3)


===Updating fields in a field group===

<var>EXACTLY-ONE</var> fields cannot be <var>ADD</var>ed, <var>INSERT</var>ed or <var>DELETE</var>d. You can only <var>CHANGE</var> them.

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
FEO FIELDGROUP VEHICLE
ADD MAKE = 'XXX'
INSERT MAKE(1) = %NOTHING
DELETE MAKE
CHANGE COLOR(4) TO 'YYYY'
END FOR
END 

The result is: 
<nowiki>*** 1 M204.2853: ADD NOT ALLOWED FOR EXACTLY-ONE FIELD
== 'XXX'
*** 2 M204.0228: PART OF STATEMENT IGNORED
*** 3 M204.2853: INSERT NOT ALLOWED FOR EXACTLY-ONE
FIELD
== %NOTHING
*** 4 M204.0228: PART OF STATEMENT IGNORED
*** 5 M204.2853: DELETE NOT ALLOWED FOR EXACTLY-ONE
FIELD
*** M204.1042: COMPILATION ERRORS
</nowiki>


===Handling invalid occurrence numbers===
The following <code>PRINT MAKE(3)</code> statement prints a null and without error, even if <code>MAKE</code> was defined as <var>EXACTLY-ONE</var>. This is consistent with Model 204 behavior for non-field group <var>EXACTLY-ONE</var> and <var>OCCURS</var> fields. That is, you can request occurrence 4 of an <var>EXACTLY-ONE</var> or <var>OCCURS 1</var> field in the record, and Model 204 returns a null. Model 204 ignores invalid occurrence numbers such as negative numbers or 0. 0 is treated the same as 1.

In the following example, <code>MAKE</code> and <code>MODEL</code> are <var>EXACTLY-ONE</var> fields:

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
PRINT '1' AND MAKE AND MODEL
PRINT '2' AND MAKE(2) AND MODEL(2)
PRINT '3' AND MAKE(3) AND MODEL(3)
END FOR
END 
The result is:
1 AUDI A4 QUATTRO
2 CADILLAC SEVILLE
3



In addition to retrieving field values inside an <var>FEO FIELDGROUP</var> loop, fields in that field group can be updated, that is, added, inserted, changed, and deleted: 
BEGIN

%GLASSES IS STRING LEN 50
%GLASSES = 'CORRECTIVE LENSES REQUIRED'

IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
FEO FIELDGROUP DRIVER
PRINT 'BEFORE ..'
PAFGI
ADD DRIVER_RESTRICTIONS = 'MEDICAL RESTRICTIONS PRESENT'
INSERT DRIVER_RESTRICTIONS(3) = %GLASSES
DELETE DRIVER_RESTRICTIONS(4)
CHANGE DRIVER_MARITAL_STATUS TO 'WIDOWED'
PRINT 'AFTER ...'
PAFGI
END FOR
END 

The result is:
BEFORE ..
\DRIVER = 1
DRIVER_ID = 100034
DRIVER_NAME = CUMMINGS, BETTY S
DRIVER_MARITAL_STATUS = SINGLE
DRIVER_GENDER = F
DRIVER_DATE_OF_BIRTH = 19791225
/DRIVER = 1
AFTER ...
\DRIVER = 1
DRIVER_ID = 100034
DRIVER_NAME = CUMMINGS, BETTY S
DRIVER_MARITAL_STATUS = WIDOWED
DRIVER_GENDER = F
DRIVER_DATE_OF_BIRTH = 19791225
DRIVER_RESTRICTIONS = MEDICAL RESTRICTIONS PRESENT
DRIVER_RESTRICTIONS = CORRECTIVE LENSES REQUIRED
/DRIVER = 1
BEFORE ..
\DRIVER = 2


==Constraint violations for field groups==
For <var>ADD</var>, <var>INSERT</var>, and <var>DELETE</var> statements, you can get an <var>EXACTLY-ONE</var> constraint violation, as well as other field constraint violations. In the previous example, had you attempted to add, insert, or delete the field <code>DRIVER_ID</code>, you would have received the following error message:
M204.2853: (ADD/DELETE/INSERT) NOT ALLOWED FOR EXACTLY-ONE FIELD

In general, the behavior of updating statements mimics the Model 204 handling of exception cases. For example, a <var>DELETE</var> of an occurrence that is not there is ignored. A <var>CHANGE</var> statement for an absent occurrence becomes an <var>ADD</var> statement.

==Referencing fields in nested field groups==
You can reference a field from the containing context even inside a field group context. For example:
BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
FEO FIELDGROUP DRIVER
PRINT POLICY_NUMBER AND DRIVER_NAME
END FOR
END

100013 CUMMINGS, BETTY S
100013 CUMMINGS, EDDIE R
100013 CUMMINGS, LEE V
100013 CUMMINGS, MARY U
100013 CUMMINGS, ROBERT T


See the discussion in the next section regarding the oddities of <var>DELETE</var> processing with <var>FEO</var> loops.

==FEO loops and field group context==
On each iteration of a field group <var>FEO</var> loop, the current field group is set as the field group context. If that field group is deleted and a field in that field group is referenced you get a request canceling error.

<var>FEO</var> on field groups has the same semantics as those on a single field. When you iterate in an <var>FEO FIELDGROUP</var>, the next occurrence processed is the occurrence number one greater than the one processed before, whether or not it is one you have already processed (because of insertions) or whether or not you skip one or more (because of deletions).

The problem with deleting repeating fields, or field groups, in order in an FEO loop is that the internal pointer is updated after each deletion, resulting in a default behavior of deleting every other occurrence of the repeating field or field group, which can also cause an error when the final deletion is attempted and the pointer is now set to a value larger than the final occurrence:
BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
FEO FIELDGROUP DRIVER
PRINT POLICY_NUMBER AND DRIVER_NAME
END FOR
END

100013 CUMMINGS, BETTY S
100013 CUMMINGS, EDDIE R
100013 CUMMINGS, LEE V
100013 CUMMINGS, MARY U
100013 CUMMINGS, ROBERT T

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
PRINT POLICY_NUMBER
PRINT 'BEFORE...'
FEO FIELDGROUP DRIVER
PRINT DRIVER_NAME AT 5
END FOR
FEO FIELDGROUP DRIVER
DELETE FIELDGROUP
END FOR
PRINT 'AFTER....'
FEO FIELDGROUP DRIVER
PRINT DRIVER_NAME AT 5
END FOR
END

100013
BEFORE...
CUMMINGS, BETTY S
CUMMINGS, EDDIE R
CUMMINGS, LEE V
CUMMINGS, MARY U
CUMMINGS, ROBERT T
AFTER....
CUMMINGS, EDDIE R
CUMMINGS, MARY U


The intent of the above code is clearly to delete every occurrence of the field group, not every other occurrence, but this anomalous result is maintained as part of SOUL for backward compatibility reasons. The three approaches to deleting all occurrences are:
<ul>
<li>Use the <var>DELETE EACH</var> syntax.</li>
<li>Loop backward through the set of occurrences in an index loop.</li>
<li>Use <var>FOR ALL OCCURRENCES</var> (<var>FAO</var>), introduced in Model 204 version 7.5. </li>
</ul>

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
PRINT POLICY_NUMBER
PRINT 'BEFORE...'
FAO FIELDGROUP DRIVER
PRINT DRIVER_NAME AT 5
END FOR
FAO FIELDGROUP DRIVER
DELETE FIELDGROUP
END FOR
PRINT 'AFTER....'
FAO FIELDGROUP DRIVER
PRINT DRIVER_NAME AT 5
END FOR
END

100013
BEFORE...
CUMMINGS, BETTY S
CUMMINGS, EDDIE R
CUMMINGS, LEE V
CUMMINGS, MARY U
CUMMINGS, ROBERT T
AFTER....

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100095
PRINT '...BEFORE...'
FAO FIELDGROUP VEHICLE
PRINT MAKE AND MODEL
END FOR
PRINT 'ADD A HONDA PILOT ...'
ADD FIELDGROUP VEHICLE
MAKE = HONDA
MODEL = PILOT
* ... OTHER VEHICLE FIELDS
END ADD
PRINT '...AFTER....'
FAO FIELDGROUP VEHICLE
PRINT MAKE AND MODEL
END FOR
END

...BEFORE...
VOLKSWAGEN NEW BEETLE
MITSUBISHI ECLIPSE
CHEVROLET SUBURBAN

ADD A HONDA PILOT ...
...AFTER....
VOLKSWAGEN NEW BEETLE
MITSUBISHI ECLIPSE
CHEVROLET SUBURBAN
HONDA PILOT


==UPDATE field attribute==

===Impact of changing a value===

When the user changes the value of a field, how <var class="product">Model 204</var> changes the occurrence depends upon whether the field was defined with the <var>UPDATE IN PLACE</var> or <var>UPDATE AT END</var> attribute, as follows:
<table>
<tr class="head">
<th>Attribute </th>
<th>How the update works...</th>
</tr>

<tr>
<td><var>UPDATE IN PLACE</var> (the default) </td>
<td>The value of the field occurrence is changed but its position in the record is preserved. To change the order of values, the user must delete the old value and add the new one in separate statements. </td>
</tr>

<tr>
<td><var>UPDATE AT END</var> </td>
<td>The existing occurrence is deleted and the new one is automatically added at the end. <var>UPDATE AT END</var> is normally specified for applications that depend on value rotation to accomplish aging. </td>
</tr>
</table>

====Example====

This example includes both approaches to updating. Suppose a record has the following fields:
NAME = RICHARD SMITH
CHILD = HENRY
CHILD = SALLY
CHILD = JANE


You could use the technique illustrated below to add a last name to each child. (This technique involves the use of %variables, which are discussed in [[Using variables and values in computation]].)
BEGIN
FIND.RECS: FIND ALL RECORDS FOR WHICH
NAME = RICHARD SMITH
END FIND
FOR EACH RECORD IN FIND.RECS
EACH.CHILD FOR EACH OCCURRENCE OF CHILD
%A = VALUE IN EACH.CHILD WITH ' SMITH'
CHANGE CHILD = VALUE IN EACH.CHILD TO %A
END FOR
END FOR
END


===If the UPDATE IN PLACE option is specified===

If the <var>UPDATE IN PLACE</var> option has been specified for the <code>CHILD</code> field, then the <var>FOR EACH OCCURRENCE</var> loop change each occurrence of <code>CHILD</code> in turn. 

On the first pass through the loop, the first value, <code>HENRY</code>, is selected and changed to <code>HENRY SMITH</code>. After the first pass, the record looks like this:
NAME = RICHARD SMITH
CHILD = HENRY SMITH
CHILD = SALLY
CHILD = JANE


At the end of the second pass, SALLY is changed:
NAME = RICHARD SMITH
CHILD = HENRY SMITH
CHILD = SALLY SMITH
CHILD = JANE


At the end of the third pass, JANE is changed:
NAME = RICHARD SMITH
CHILD = HENRY SMITH
CHILD = SALLY SMITH
CHILD = JANE SMITH


===If the UPDATE AT END option is specified===

If the <var>UPDATE AT END</var> option has been specified for the <code>CHILD</code> field, the <var>FOR EACH OCCURRENCE</var> loop proceeds as described here.

On the first pass through the <var>FOR EACH OCCURRENCE</var> loop the first value, <code>HENRY</code>, is selected and changed to <code>HENRY SMITH</code>. The act of changing, however, causes the value <code>HENRY</code> to be deleted and the value <code>HENRY SMITH</code> to be added as the last child. Thus after the first pass, the record looks like this:
NAME = RICHARD SMITH
CHILD = SALLY
CHILD = JANE
CHILD = HENRY SMITH


On the second pass through the loop, <code>JANE</code>, which is now the second occurrence of <code>CHILD</code>, is deleted and <code>JANE SMITH</code> is added to the end of the record:
NAME = RICHARD SMITH
CHILD = SALLY
CHILD = HENRY SMITH
CHILD = JANE SMITH


On the third pass, the third occurrence is <code>JANE SMITH</code>, and the record ends with:
NAME = RICHARD SMITH
CHILD = SALLY
CHILD = HENRY SMITH
CHILD = JANE SMITH


==Subscripts==

Subscripts can be included in <var class="product">Model 204</var> field references to facilitate the selection of particular occurrences of multiply occurring fields. Any field name can be followed by a parenthesized expression. The value of this expression is used as an ordinal number which specifies the desired occurrence of the named field. For example: 
INCIDENT(3)
COURSE.NUMBER(2)
TRANSACTION(A+B)


====Example====

This request illustrates a class schedule where subscripts are used to change the room number for a course:
BEGIN
COURSE: FIND ALL RECORDS FOR WHICH
REC = ROOM ASSIGNMENT
END FIND
CHANGE: FOR EACH RECORD IN COURSE
IF ROOM(1) EQ '214A' THEN
CHANGE ROOM(1) TO '566A'
END IF
IF ROOM(2) EQ '214A' THEN
CHANGE ROOM(2) TO '566A'
END IF
END FOR
END


===Subscripted field extraction===

Subscripted field references attempt to maintain their position inside a record much as an FEO loop attempts to maintain its position inside a record. This means that subscripted field references tend to be as efficient as FEO loops. 

The following is an example of using subscripted field extraction for a field that is a member of a field group. An <var>FEO</var> loop populates two arrays with the corresponding values of group members <code>INCIDENT</code> and <code>INCIDENT_DATE</code>:
%inc is string array (12) no fs
%idate is string array (12) no fs
FeoIdata:
feo INCIDENT
%inc(occurence in FeoIdata) = value in FeoIdata
%idate(occurence in FeoIdata) = INCIDENT_DATE(occurence in FeoIdata)
end for


If you use multiple <var>FEO</var> loops for field group processing, it is possible that using this technique will require additional VTBL resources for procedures with an extremely large number of sorts or subscripted field references.

===Evaluation of subscript expressions===

The evaluation of subscript expressions is subject to the rules for determining an integer result for an arithmetic expression as described in [[Using variables and values in computation#Arithmetic operations|Arithmetic operations]]. 

===Statements and phrases with which you cannot use subscripts===

Subscripted field references can appear anywhere that unsubscripted references can, except in the following statements and phrases:
<table>
<tr class="head">
<th>Statements you cannot use with subscripts </th>
<th>
Because...</th>
</tr>

<tr>
<td><var>ADD</var> </td>
<td>Adds a new occurrence of a field. </td>
</tr>

<tr>
<td><var>BY EACH phrase</var> in the <var>SORT RECORDS</var> </td>
<td>Loops through all occurrences of a field. </td>
</tr>

<tr>
<td><var>DELETE EACH statement</var> </td>
<td>Loops through all occurrences of a field. </td>
</tr>

<tr>
<td><var>EACH phrase</var> in a <var>PRINT</var> specification</td>
<td>Loops through all occurrences of a field. </td>
</tr>

<tr>
<td><var>FILE</var> </td>
<td>Deals with fields having the INVISIBLE attribute, which cannot be the object of subscripted references. </td>
</tr>

<tr>
<td><var>FIND</var></td>
<td>Locates records without regard to which occurrence of a field contains the desired value. </td>
</tr>

<tr>
<td><var>FOR EACH OCCURRENCE</var></td>
<td>Loops through all occurrences of a field. Field references within FOR EACH OCCURRENCE loops can be subscripted, depending upon the individual statements in which the references appear. </td>
</tr>

<tr>
<td><var>FOR EACH VALUE</var> </td>
<td>Loops through all values of all occurrences of the specified field. Field references within FOR EACH VALUE loops are not allowed at all, unless the field reference is embedded in a nested FOR EACH RECORD loop. See [[Value loops#Setting up a value loop on one field and printing a value of another|Setting up a value loop on one field and printing a value of another]] for more information.</td>
</tr>

<tr>
<td><var>IN ORDER BY EACH phrase</var> in the <var>FOR EACH RECORD </var></td>
<td>Loops through all occurrences of a field. </td>
</tr>

<tr>
<td><var>PRINT n </var></td>
<td>Loops through all occurrences of a field. </td>
</tr>

<tr>
<td><var>STORE RECORD</var></td>
<td>Adds fields in the order of appearance in the statement. </td>
</tr>
</table>

===Unsubscripted field references===

An unsubscripted field reference in a context in which subscripted references are allowed is always equivalent to a subscripted reference with a value of one.

===Do not use subscripts with INVISIBLE fields===

You cannot make subscripted references to fields that have the <var>INVISIBLE</var> attribute (see the discussion on field attributes in [[Field attributes]]). These fields are not truly multiply occurring, although they can have several different values in a single record. A subscript specified for a field with the <var>INVISIBLE</var> attribute is ignored. 

==Subscript validity rules==

The rules presented below indicate whether or not a subscript value is valid and what action to take if the value is not valid. These rules take into account: 
<ul>
<li>The value of the subscript</li>
<li>The context in which the subscript appears</li>
<li>The description of the subscripted field </li>
</ul>

===Explanation of the rules===

In these rules, two quantities are used:
<ol>
<li>N is the maximum number of occurrences that can be stored in a record for a given field. For a preallocated field, N equals the value of <var class="term">n</var> in the <var>OCCURS</var> clause of the field's description. For other fields, N has no limit. </li>

<li>P is the number of nonempty occurrences of the referenced field found in the specified record when the reference is evaluated. </li>
</ol>

For a summary of rules for preallocated fields, refer to the discussion on preallocated fields in [[Data maintenance#Storing values in preallocated fields|Storing values in preallocated fields]]. 

===INSERT statement===

The <var>INSERT</var> statement, like the <var>ADD</var> statement, is used for adding new occurrences of a field. <var>INSERT</var> is used to add occurrences when the order of the values is important and the values are added out of order. 

The <var>INSERT</var> statement is supported in remote file and scattered group contexts. The <var>INSERT</var> statement is not supported for Large Object fields.

====Syntax====

The format of the <var>INSERT</var> statement is:
INSERT fieldname [(subscript)] = value


====Example====

Assume a record with these fields:
DEPT = PERSONNEL
DEPT = FINANCE
DEPT = MARKETING


The following statement:
INSERT DEPT(3) = ACCOUNTING


results in this record:
DEPT = PERSONNEL
DEPT = FINANCE
DEPT = ACCOUNTING
DEPT = MARKETING


====Subscript validity rules====

[[#INSERT statement|INSERT statement]] lists validity rules for subscripts. In this table:
<ul>
<li>P is the number of occurrences of the field in the record when the <var>INSERT</var> statement is issued. </li>

<li>S is the subscript specified in the <var>INSERT</var> statement.
<table>
<caption>Subscript validation rules</caption>
<tr class="head">
<th>If P and S values are: </th>
<th>
Then <var class="product">Model 204</var> takes this action:</th>
</tr>

<tr>
<td>P > S</td>
<td>Inserts the new occurrence in front of the former Sth occurrence; the new occurrence becomes the current Sth occurrence of the field.</td>
</tr>

<tr>
<td>P < S</td>
<td>Inserts the new occurrence of the field after the Pth occurrence; the new occurrence becomes the (P+1) occurrence.</td>
</tr>

<tr>
<td>P = 0</td>
<td>Adds the new value at the end of the record, as in the <var>ADD</var> statement.</td>
</tr>

<tr>
<td>S = 0, or no subscript</td>
<td>Treats the new value as if S = 1 and inserts the new value as the first occurrence, in front of any former occurrence of the field.</td>
</tr>

<tr>
<td>S < 0</td>
<td>Does not add a new occurrence.</td>
</tr>
</table>
</li>
</ul>

For fields with the <var>INVISIBLE</var> attribute, only the index is affected. 

===PRINT statement===

In retrieval statements such as <var>PRINT</var>, subscript values less than zero or greater than P are invalid. Invalid references of this kind cause the null value to be returned. A subscript of zero returns the value of the first occurrence. 

===DELETE statement===

In the <var>DELETE</var> statement, subscript values less than one or greater than P are invalid. If an invalid reference of this kind is made, no action is taken. 

If several occurrences of a field are being deleted, you should be careful not to use DELETE in the following way: 
FOR EACH RECORD IN FIND.RECS
DELETE CLIENT(1)
DELETE CLIENT(2)
DELETE CLIENT(3)
END FOR


As the statements are executed, <var class="product">Model 204</var> deletes the first occurrence, <code>CLIENT(1)</code>, then locates the current second occurrence, which is the original <code>CLIENT(3)</code>, and deletes it. Then, because a third occurrence cannot be found, the operation stops, and the original <code>CLIENT(2)</code> is never deleted.

In such a situation, deleting the occurrences in the reverse order achieves the desired result:
FOR EACH RECORD IN FIND.RECS
DELETE CLIENT(3)
DELETE CLIENT(2)
DELETE CLIENT(1)
END FOR


The desired result also can be achieved by completely omitting the subscripts, as follows:
FOR EACH RECORD IN FIND.RECS
DELETE CLIENT
DELETE CLIENT
DELETE CLIENT
END FOR


===CHANGE statement===

In the <var>CHANGE</var> statement, subscript values less than one or greater than P are treated as attempts to add a new occurrence (P+1). If (P+1) does not exceed N (the maximum number of occurrences that can be stored), the new occurrence is added to the record. If (P+1) does exceed N, the request is cancelled. 

===SORT RECORDS statement===

The use of subscripts in references to the recordset yielded by a
<var>SORT RECORDS</var> statement sometimes can produce unexpected results.
If the <var>BY EACH</var> option appears in a <var>SORT</var> statement, records in which the <var>BY EACH</var> field is multiply occurring are copied several times (once for each field occurrence) to the system scratch file CCATEMP.
In each copy, the occurrences of the <var>BY EACH</var> field are rotated, so that the occurrence used as the sort key appears first. Therefore, a subscripted reference to this field can yield different values for different copies of the record. 

</div> 

[[Category:SOUL]]

Release notes for Model 204 version 7.5

2014-08-01T13:43:37Z

Mlarocca:

These release notes list the enhancements and other changes contained in Model 204 version 7.5.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.5.0 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
This section summarizes the new features and enhancements for Model 204 version 7.5.0.

===SOUL (User Language)===
The significantly enhanced, object-oriented, version of User Language is now called [[#SOUL (User Language) enhancements|SOUL]]. All existing User Language programs will continue to work under SOUL, so User Language can be considered to be a subset of SOUL, though the name "User Language" is now deprecated.
<ul>
<li>integration of object-oriented language extensions from the Janus SOAP User Language Interface</li>
<li>[[Release notes for Model 204 version 7.5 (DRAFT)#External Call Facility .28ECF.29|ECF]] CALL statements can pass up to 60 parameters</li>
</ul>

===System Management===
<ul>
<li>Writing records to the SMF data set without an SVC installed</li>
</ul>

===Performance===
<ul>
<li>GTBL can be stored above the bar</li>
<li>[[Release notes for Model 204 version 7.5 (DRAFT)#Support for physical field groups|Support for physical field groups]]</li>
</ul>

==Operating system requirements==
Requirements for Model 204 version 7.5 are still being determined.

Model 204 version 7.5 requires the following operating system support:
<ul>
<li>For IBM z/OS: Version 1 Release 7. V1R7 is sufficient for all new functionality except for the following
features:
<ul>
<li>Large (1 MB) page support requires Version 1 Release 9.
<li>Extended address volumes (EAV) requires Version 1 Release 12.
</ul>
<li>For IBM z/VM: Version 5 Release 4.0 or later
<li>For IBM z/VSE:
<ul>
<li>Version 5 Release 1 or
<li>Version 4 Release 3 or
<li>Version 4 Release 2.1 or
<li>Version 4 Release 2.0, with these program temporary fixes (PTFs) installed:
<ul>
<li>UD53436
<li>UD53437
<li>UD53438
<li>UD53439
</ul>
</ul>
Note: z/VSE V5.1 is required to take advantage of any 64-bit capabilities under VSE.

</ul>

=== Hardware requirements ===
Requirements for Model 204 version 7.5 are still being determined.

Model 204 version 7.5 requires the IBM z/890 or above processor, except for the following feature:

The large (1 MB) page support feature requires the IBM z10 or above processor. 

===Model 204 compatibility with operating systems===
Content for version 7.5 is still being determined.
For information on Model 204 certification with IBM operating systems, see:
http://www.rocketsoftware.com/products/rocket-model-204/technical-information

<div id="Connect* compatibility with Model 204"></div>
===Connect* compatibility with Model 204===
Connect★ version 7.5.0 is compatible with all versions of Model 204.

==SOUL (User Language) enhancements==
Much of the substantial new and enhanced functionality described in the following subsections is available as a result of the acquisition of Sirius Software. The functionality that is the subject of the initial subsection, "Object oriented programming," motivates the new name for User Language, '''SOUL''' (Simple Objective User Language).

===Object oriented programming===
As of version 7.5 of Model 204 (and backward compatible with existing User Language applications), the SOUL language is equipped with [http://en.wikipedia.org/wiki/Object-oriented Object-Oriented Programming](sometimes abbreviated OO) capabilities comparable or superior to other contemporary object oriented languages. The OO features were formerly contained in the [[Janus SOAP User Language Interface]], and you can use [[Object oriented programming in SOUL]] as an entry point to the extensive SOUL OO documentation. In particular, you might want to begin with the [[Getting started with OOP for User Language programmers|OO tutorial]].

===Record capacity increase===
In this version of Model 204, the record limit is increased from sixteen million records to forty-eight million records per file.

===New SOUL statements===
{{Template:User Language statements}}

===Non-OO enhancements in SOUL===
{{Template:User Language syntax enhancements}}

===SOUL support for field groups===

====ADD (or INSERT or DELETE) FIELDGROUP statements====
The <var>ADD FIELDGROUP</var> statement and the <var>INSERT FIELDGROUP</var> statement behavior parallels the behavior of the <var>ADD</var> and <var>INSERT</var> statements for simple fields. The <var>DELETE FIELDGROUP</var> statement handles more situations and is therefore more complex.
See [[Data maintenance#Updating field groups|Updating field groups]] for details.

====Statements for handling field groups====
SOUL now provides several statements for handling field groups:
<ul>
<li><var>FOR FIELDGROUP</var></li>
<li><var>FOR ALL OCCURRENCES OF FIELDGROUP (FAO FIELDGROUP)</var></li>
<li><var>FOR EACH OCCURRENCE OF FIELDGROUP (FEO FIELDGROUP)</var></li>
</ul>

See [[Operations on multiply occurring fields#Special statements for multiply occurring fields and field groups|Special statements for multiply occurring fields and field groups]] for details.

====Output statements for field groups====

The following SOUL statements provide display output for Model 204 field groups:
AUDIT ALL FIELDGROUP INFORMATION (AAFGI)
PRINT ALL FIELDGROUP INFORMATION (PAFGI)


See [[Basic SOUL statements and commands#Output statements for fields and field groups|Output statements for fields and field groups]] for details.

====Field group SORT support====
You can use field groups in [[Sorting#Field group SORT support|sorted sets]]. <var>SORT</var> statement support for field groups lets you sort records with field groups as well as reference field groups in the sorted sets. For example, you can issue a <code>FAO FIELDGROUP</code> statement or <code>FEO FIELDGROUP</code> statement against the sorted set.

===EQ VALUE retrieval condition===

SOUL now provides the <var>EQ VALUE</var> clause to support expressions in <var>FIND</var> statements.

See [[Record retrievals#Using expressions in FIND statements|Using expressions in FIND statements]] for details.

===EQ WITH retrieval condition for concatenated fields===
SOUL now provides the <var>EQ WITH</var> clause for retrieving <var>CONCATENATION-OF</var> fields. Model 204 automatically builds the concatenated value.

See [[Record retrievals#Using expressions in FIND statements|Using expressions in FIND statements]] and [[Record retrievals#EQ WITH retrieval condition for concatenated fields|EQ with retrieval condition for concatenated fields]] for details.

===External Call Facility (ECF)===
<var>EXTERNAL CALL</var> statements can now pass more parameters.
The maximum number of parameters that can be passed in an <var>EXTERNAL CALL</var> statement has been increased from 40 to 60.
The maximum value setting for <var>[[ECPSIZE parameter|ECPSIZE]]</var> is increased from 1310680 to 1966020 to accommodate the extra parameters.

ECF is available only on z/OS systems. For more information about the External Call Facility and the <var>EXTERNAL CALL</var> statement, see the <var class="book">Rocket Model 204 System Manager's Guide</var>.

===REPEAT statement UNTIL option===
The <var>REPEAT</var> statement now supports the <var>UNTIL</var> option. In previous releases, only <var>REPEAT WHILE</var> was supported.

A <var>[[Flow of control in User Language#REPEAT UNTIL statement|REPEAT UNTIL]]</var> statement enters the loop body prior to checking the condition.

===New and changed classes and methods===

====New InvalidBitNumber class====
Objects of the [[InvalidBitNumber class|InvalidBitNumber exception class]] are thrown when an invalid bit number is requested by a bit manipulation function. It is currently thrown only by the <var>[[BitClearString (String function)|BitClearString]]</var>, <var>[[BitFlipString (String function)|BitFlipString]]</var>, <var>[[BitSetString (String function)|BitSetString]]</var>, and <var>[[BitValueString (String function)|BitValueString]]</var> functions.

====New InvalidTranslateTable class====
Objects of the [[InvalidTranslateTable class|InvalidTranslateTable exception class]] are thrown when a requested system translate table cannot be found. It is currently thrown only by the <var>[[TranslateTable (HttpRequest property)|TranslateTable]]</var> <var>HttpRequest</var> property.

====New bit manipulation String functions====
New bit manipulation functions <var>[[BitClearString (String function)|BitClearString]]</var>, <var>[[BitCountString (String function)|BitCountString]]</var>, <var>[[BitFlipString (String function)|BitFlipString]]</var>, <var>[[BitSetString (String function)|BitSetString]]</var>, and <var>[[BitValueString (String function)|BitValueString]]</var> make it easier to manipulate the bits in a string.

====New String processing functions====
New <var>String</var> functions <var>[[Before (String function)|Before]]</var> and <var>[[After (String function)|After]]</var> return the parts of a string before or after a user-specified delimiter string.

====New Stringlist subroutine====
New <var>Stringlist</var> subroutine <var>[[AppendPemData (Stringlist subroutine)|AppendPemData]]</var>
appends a PEM encode string to a <var>Stringlist</var>.

====New System methods TODClock and UUIDTime====
New System class methods [[TODClock (System function)|TODCLOCK]] and [[UUIDTime (System function)|UUIDTime]] have been created to facilitate generation of version 1 universal unique identifiers and to provide high precision time stamps for SOUL applications. These methods were actually added as a ZAP update to Model 204 7.5 (75Z109).

====New HttpRequest TranslateTable property====
The <var>[[TranslateTable (HttpRequest property)|TranslateTable]]</var> <var>HttpRequest</var> property makes it possible to set the translate table to be used for EBCDIC to ASCII translation of data in an <var>HttpRequest</var> object.

====Disable base64 encoding in LoadFromRecord and related methods====
The <var>Base64Encode</var>=<var>False</var> argument can be used with the <var>[[LoadFromRecord (XmlDoc/XmlNode subroutine)|LoadFromRecord]]</var> method to disable any base64 encoding of field values.

Alternatively, the <var>CharacterMap</var> argument (with a non-null value) can be used to disable any base64 encoding of field values, and to specify translations, which can avoid request translation due to X'00' and/or untranslatable characters in field values.

These arguments are also added to the <var>[[NewFromRecord (XmlDoc function)|NewFromRecord]]</var> and <var>[[ToXmlDoc (Record function)|ToXmlDoc]]</var> methods.

====New parameter for AppendJournalData====
The <var>QT</var> option is added to the <var>[[AppendJournalData (Stringlist function)#Options parameter|AppendJournalData]]</var> method, to include QT type audit entries.

====New parameter for AddField====
The <var>Strip</var> option is added to the <var>Screen</var> class method <var>[[AddField (Screen function)|AddField]]</var> to allow suppression of leading and trailing blank removal from input fields.

===New and changed $functions===

====Former Sirius $functions====
The $functions referred to by the link below are added to SOUL as a result of the acquisition of Sirius Software:
:[[List of $functions|Sirius $functions]]
Among these $functions are integrated [[List_of_mathematical_$functions|math $functions]]: high-performance, high-precision versions of the IBM mathematical functions. These functions eliminate the need to use external math libraries.

====$SNDMAIL attachment ASCII translation====
The <var>[[SOUL_$functions#Sending_email_messages_via_User_Language|$SNDMAIL]]</var> function can now translate an attachment to ASCII before sending it.
This translation is useful if the <var>$SNDMAIL</var> attachment is a <var>CLOB</var> (<var>CHARACTER-LARGE-OBJECT</var>) such as a text document.

The <var>$SNDMAIL</var> function now accepts an optional parameter after the name of the attached object. If this parameter is set to 'C' (or to a percent variable with the value 'C'), the object in the buffer is translated to ASCII before being attached to the email.

If this parameter is not specified, the object in the buffer is sent as a binary object.

In this example:
%RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,'CLOB.TXT','C')

the <code>CLOB.TXT</code> attachment will be translated to ASCII before being attached to the email.

====New function calls for field groups====
When a field group is added, a [[Data maintenance#Updating field groups|field group ID]] is assigned to the field group.
<ul>
<li><var>[[$FieldgroupId]]</var> returns the ID of the current field group.</li>
<li><var>[[$FIELDGROUPOCCURRENCE]]</var> returns the current occurrence number of the field group.</li>
</ul>

==Sirius products and product enhancements==
[[Sirius Software product list|The former-Sirius products]] are now available to Model 204 customers as separately purchased items as a result of the acquisition of Sirius Software.

===Changes to Janus SSL support===
Under Model 204 version 7.5, Janus products:

<ul>
<li>Drop support for version 2 of the Secure Sockets Layer encryption protocol (SSL V2)

You can use the <var>[[SSLPROT (JANUS DEFINE parameter)|SSLPROT]]</var> parameter on the <var>JANUS DEFINE</var> command for a port to explicitly specify, or limit, the SSL protocols available for a connection. The <var>SSLPROT</var> documentation describes the SSL protocols that Janus supports. 

Janus support for SSL V2 also included an option to specify a larger than "legal" input buffer for connections not strictly conforming to the V2 standard. You specify that buffer size with the <var>JANUS DEFINE</var> <var>[[SSLIBSIZE (JANUS DEFINE parameter)|SSLIBSIZE]]</var> parameter, and the <var>SSLIBSIZE</var> maximum value as of Model 204 V7.5 is reduced (from 32767 bytes) to the SSL maximum allowed size of 16384. </li>

<li>Add support for new ciphers and TLS levels

You can use the <var>[[SSLCIPH (JANUS DEFINE parameter)|SSLCIPH]]</var> <var>JANUS DEFINE</var> parameter to specify the SSL ciphers available for a connection. The <var>SSLCIPH</var> documentation describes the SSL ciphers that Janus supports. </li>
</ul>

===WEBOPT parameter change===
The <var>[[WEBOPT parameter|WEBOPT]]</var> parameter default value is changed to X'03' from 0. <var>WEBOPT</var> affects the interaction of Model 204 and RACF security.

==File-related enhancements==

===Support for physical field groups===
Model 204 supports non-relational, de-normalized data structures. Many Model 204 sites have enjoyed significant cost and performance benefits from efficiently processing multiply occurring fields. This concept has been enhanced to introduce physical field groups that let you view and process groups of fields as a logical entity.

You can define a physical field group only for files with the [[#FILEORG (new settings)|FILEORG X'100' setting]]. To take advantage of field groups in files defined before Model 204 version 7.5, you must reorganize the files with a <var>FILEORG</var> setting that includes the X'100' bit.

Files with <var>FILEORG</var> X'100' can have up to 32,000 fields.

For more information, see [[Field group design]].

===Increased Table B record number capacity===
[[Table B (File architecture)|Table B]] can now contain up to 48M possible record numbers. (The previous limit was 16M.)

Set the [[#FILEORG (new settings)|FILEORG X'200' bit]] at file creation time to allow for the increased record numbers.
<blockquote class="note">
Notes: 
<ul>
<li>The limit for <var>BSIZE</var> remains at 16M.

<code>BSIZE * BRECPPG</code> must be less than or equal to 48M (actually decimal 50,331,648 to be exact). 

For example, if <var>BSIZE</var> is 16M, <var>BRECPPG</var> cannot be more than 3. </li>

<li>The <var>FILEORG</var> X'200' bit cannot be set for files with hash key or sorted file organization.</li>
</ul>
</blockquote>

===Automatic fields===
Model 204 now lets you define a field whose value is [[Field design#Automatic fields|automatically maintained]]. A field can count occurrences of another field so that every store or delete of the field occurrence changes the count in the automatic field. The following automatically maintained field attributes are available for files defined with the FILEORG x'100' setting:
<ul>
<li><var>COUNT-OCCURRENCES-OF</var></li>
<li><var>CREATE-TIME</var></li>
<li><var>CREATE-TIMEUTC</var></li>
<li><var>CREATE-USER</var></li>
<li><var>UPDATE-TIME</var></li>
<li><var>UPDATE-TIMEUTC</var></li>
<li><var>UPDATE-USER</var></li>
</ul>

The value of an automatic field is updated at the start of a transaction by Model 204 and you cannot set it explicitly by a program. Any valid update statement causes the appropriate time and user stamps to be updated. For example, the time and user stamps will be updated when <code>DELETE FOO(8)</code> is processed, even if there are no occurrences of FOO in the record and an actual update does not take place.

Once you define an automatic value for a field, you cannot redefine the automatic value.

===Concatenated fields===
Model 204 now lets you define [[Field design#Concatenated fields|concatenated fields]].

Fields that make up concatenated field values must be <var>AT-MOST-ONE</var>, <var>EXACTLY-ONE</var>, or <var>OCCURS</var> 1 and must all be in the same field group context (or not in a field group). Fields that occur in all field groups (<var>FIELDGROUP *</var>) cannot be used in a concatenation.

If a concatenated field becomes longer than 255 bytes after adding separator and escape characters, the update request is cancelled.

===New field attributes===
Model 204 version 7.5 introduces the new <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> attributes described in this section. These attributes apply to all fields in Model 204. 

Note: These attributes all require that the <var>[[FILEORG parameter|FILEORG]]</var> parameter X'100' bit be set on the file containing the fields.

Changes in the new field attributes are detected during the redefinition of an existing field. When such a change is detected, the following messages might be issued:
M204.1260: [FIELD | FIELDGROUP] WAS PREVIOUSLY DEFINED WITH DIFFERENT ATTRIBUTES,
NEW [FIELD | FIELDGROUP] OPTIONS IGNORED

or
M204.2884: [FIELD WAS PREVIOUSLY DEFINED AS A FIELDGROUP | FIELDGROUP WAS PREVIOUSLY
DEFINED AS A FIELD], NEW DEFINITION IGNORED


The table below lists the new field attributes. For details on each attribute, click its name. For more information on how related attributes work together, see the [[Field design]] topic.
<table>
<tr class="head">
<th>Attribute</th><th>Abbreviation</th><th>Description</th>
</tr>

<tr>
<td>[[DEFINE_FIELD_command#Ordered_index_CHUNK_attribute|CHUNK]]</td>
<td>CNK</td>
<td>Defines "OI chunks" of data in ORDERED NUMERIC fields to enable more efficient range searching.</td>
</tr>

<tr>
<td>[[Field design#CONCATENATION-OF .28CAT.29 attribute|CONCATENATION-OF]]</td>
<td>(CAT)</td>
<td>Lists the fields that make up a concatenated field, and provides a concatenated value based upon the values of the constituent fields.</td>
</tr>

<tr>
<td nowrap>[[Field design#Counting occurrences of a field|COUNT-OCCURRENCES-OF]]</td>
<td>(CTO)</td>
<td>Automatically maintains a count of the number of occurrences of the specified field.</td>
</tr>

<tr>
<td>[[Field design#Automatic Fields|CREATE-TIME]]</td>
<td>(CRTM)</td>
<td>Captures the time when the record was created, as of the start of the transaction.</td>
</tr>

<tr>
<td>[[Field design#Automatic Fields|CREATE-TIMEUTC]]</td>
<td>(CRTMU)</td>
<td>Captures the Coordinated Universal Time when the record was created, as of the start of the transaction.</td>
</tr>

<tr>
<td>[[Field design)#Automatic Fields|CREATE-USER]]</td>
<td>(CRUS)</td>
<td>Captures the user ID of the user who created the record.</td>
</tr>

<tr>
<td>[[Field design#DATETIME-GE .28DTGE.29.2C DATETIME-GT .28DTGT.29.2C DATETIME-LE .28DTLE.29.2C and DATETIME-LT .28DTLT.29 attributes|DATETIME]]</td>
<td>(DT)</td>
<td>Specifies the format of the date and time data stored in Table B. The default is YYYYMMDDHHMMSSXXXXXX, i.e. to the nearest millionth of a second.</td>
</tr>

<tr><td>[[Field design#DATETIME-GE .28DTGE.29.2C DATETIME-GT .28DTGT.29.2C DATETIME-LE .28DTLE.29.2C and DATETIME-LT .28DTLT.29 attributes|DATETIME-GE]]</td>
<td>(DTGE)</td>
<td>With DATETIME-GT, DATETIME-LE, and DATETIME-LT, used to establish a range for date/time values. Specifies that the date/time value must be later than or the same as the date/time value that follows. </td>
</tr>

<tr>
<td>[[Field design#DATETIME-GE .28DTGE.29.2C DATETIME-GT .28DTGT.29.2C DATETIME-LE .28DTLE.29.2C and DATETIME-LT .28DTLT.29 attributes|DATETIME-GT]]</td>
<td>(DTGT)</td>
<td>Specifies that the date/time value must be later than the date/time value that follows.</td>
</tr>

<tr>
<td>[[Field design#DATETIME-GE .28DTGE.29.2C DATETIME-GT .28DTGT.29.2C DATETIME-LE .28DTLE.29.2C and DATETIME-LT .28DTLT.29 attributes|DATETIME-LE]]</td>
<td>(DTLE)</td>
<td>Specifies that the date/time value must be earlier than or the same as the date/time value that follows.</td>
</tr>

<tr>
<td>[[Field design#DATETIME-GE .28DTGE.29.2C DATETIME-GT .28DTGT.29.2C DATETIME-LE .28DTLE.29.2C and DATETIME-LT .28DTLT.29 attributes|DATETIME-LT]]</td>
<td>(DELT)</td>
<td>Specifies that the date/time value must be earlier than the date/time value that follows.</td>
</tr>

<tr>
<td>[[Field design#DEFAULT-VALUE .28DV.29 attribute|DEFAULT-VALUE]]</td>
<td>(DV)</td>
<td>Specifies the value to use for the field when the record is created and no value has been assigned to the field.

(The value of the STORE-DEFAULT setting determines whether the DEFAULT-VALUE is physically stored on the record or if it is just used as the default value when the field is missing.)</td>
</tr>

<tr>
<td>[[Field design#ESCAPE .28ESC.29 attribute|ESCAPE]]</td>
<td>(ESC)</td>
<td>Specifies an escape character to insert before separator and escape characters in a concatenated field, differentiating those characters from real data. The default value is X'01'.</td>
</tr>

<tr>
<td>[[Field design#AT-MOST-ONE.2C REPEATABLE and EXACTLY-ONE attributes|EXACTLY-ONE]]</td>
<td>(EXONE)</td>
<td>Specifies that a field always has exactly one occurrence in its record or field group context.
EXACTLY-ONE fields always appear first when output by a Print All Information (PAI) statement.</td>
</tr>

<tr><td>[[Field design#FIELDGROUP attribute|FIELDGROUP]]</td>
<td>(FG)</td>
<td>Specifies the name of the field group that the defined field is associated with (contained within).</td>
</tr>

<tr>
<td>[[Field design#FLOAT-GE .28FLTGE.29.2C FLOAT-GT .28FLTGT.29.2C FLOAT-LE .28FLTLE.29 and FLOAT-LT .28FLTLT.29 attributes|FLOAT-GE]]</td>
<td>(FLTGE)</td>
<td>With FLOAT-GT, FLOAT-LE, and FLOAT-LT, used to establish a range for float values when defining a field. Specifies that the float value must be greater than or equal to the value that follows.</td>
</tr>

<tr>
<td>[[Field design#FLOAT-GE .28FLTGE.29.2C FLOAT-GT .28FLTGT.29.2C FLOAT-LE .28FLTLE.29 and FLOAT-LT .28FLTLT.29 attributes|FLOAT-GT]]</td>
<td>(FLTGT)</td>
<td>Specifies that the float value must be greater than the value that follows.</td>
</tr>

<tr>
<td>[[Field design#FLOAT-GE .28FLTGE.29.2C FLOAT-GT .28FLTGT.29.2C FLOAT-LE .28FLTLE.29 and FLOAT-LT .28FLTLT.29 attributes|FLOAT-LE]]</td>
<td>(FLTLE)</td>
<td>Specifies that the float value must be less than or equal to the value that follows.</td>
</tr>

<tr>
<td>[[Field design#FLOAT-GE .28FLTGE.29.2C FLOAT-GT .28FLTGT.29.2C FLOAT-LE .28FLTLE.29 and FLOAT-LT .28FLTLT.29 attributes|FLOAT-LT]]</td>
<td>(FLTLT)</td>
<td>Specifies that the float value must be less than the value that follows.</td>
</tr>

<tr>
<td>[[Field design#INTEGER-GE .28INTGE.29.2C INTEGER-GT .28INTGT.29.2C INTEGER-LE .28INTLE.29 and INTEGER-LT .28INTLT.29 attributes|INTEGER-GE]]</td>
<td>(INTGE)</td>
<td>With INTEGER-GT, INTEGER-LE, and INTEGER-LT, used to establish a range for integer values when defining a field. Specifies that the integer value must be greater than or equal to the value that follows.</td>
</tr>

<tr>
<td>[[Field design#INTEGER-GE .28INTGE.29.2C INTEGER-GT .28INTGT.29.2C INTEGER-LE .28INTLE.29 and INTEGER-LT .28INTLT.29 attributes|INTEGER-GT]]</td>
<td>(INTGT)</td>
<td>Specifies that the integer value must be greater than the value that follows.</td>
</tr>

<tr>
<td>[[Field design#INTEGER-GE .28INTGE.29.2C INTEGER-GT .28INTGT.29.2C INTEGER-LE .28INTLE.29 and INTEGER-LT .28INTLT.29 attributes|INTEGER-LE]]</td>
<td>(INTLE)</td>
<td>Specifies that the integer value must be less than or equal to the value that follows.</td>
</tr>

<tr>
<td>[[Field design#INTEGER-GE .28INTGE.29.2C INTEGER-GT .28INTGT.29.2C INTEGER-LE .28INTLE.29 and INTEGER-LT .28INTLT.29 attributes|INTEGER-LT]]</td>
<td>(INTLT)</td>
<td>Specifies that the integer value must be less than the value that follows.</td>
</tr>

<tr>
<td>[[Field design#LENGTH-EQ .28LEQ.29 attribute|LENGTH-EQ]]</td>
<td>(LEQ)</td>
<td>Used to set a length constraint when defining a field. Specifies the required length of a field value.</td>
</tr>

<tr>
<td>[[Field design#LENGTH-GE .28LGE.29 attribute|LENGTH-GE]]</td>
<td>(LGE)</td>
<td>Specifies the minimum length of a field value.</td>
</tr>

<tr>
<td>[[Field design#LENGTH-LE .28LLE.29 attribute|LENGTH-LE]]</td>
<td>(LLE)</td>
<td>Specifies the maximum length of a field value.</td>
</tr>

<tr><td>[[Field design#Setting a pattern for a field value: the LIKE attribute|LIKE]]</td>
<td>(LK)</td>
<td>Sets a pattern that to which a field value must conform.</td>
</tr>

<tr>
<td>[[Field design#BLOB.2C CLOB.2C and MINLOBE attributes|MINLOBE]]</td>
<td>(MLBE)</td>
<td>Defines the minimum size of a BLOB or CLOB field value that will be stored in Table E. This avoids wasting Table E pages on small values that could be stored in Table B (or Table X). The default is 0.</td>
</tr>

<tr>
<td>NO-DOMAIN-CONSTRAINTS</td>
<td/>
<td>Specifies that the field has no [[Field design#Content constraints|content constraint]] attributes. Useful with <var>[[REDEFINE command|REDEFINE]]</var> to remove existing constraints on a field.</td>
</tr>

<tr>
<td>NO-DEFAULT-VALUE</td>
<td>(NDV)</td>
<td>Specifies that the field has no default value. Useful with <var>[[REDEFINE command|REDEFINE]]</var> to remove an existing default value on a field.</td>
</tr>

<tr>
<td>[[Field design#SEPARATOR .28SEP.29 attribute|SEPARATOR]]</td>
<td>(SEP)</td>
<td>Specifies a separator character used between field values in concatenated fields. The default is X'00'.</td>
</tr>

<tr>
<td>[[Field design#STORE-DEFAULT .28SD.29 and STORE-NULL .28SN.29 attributes|STORE-DEFAULT]]</td>
<td>(SD)</td>
<td>Specifies whether to physically store the default value for the field in each record, if no field value has been supplied and a default is required. The default option is LITERAL (LIT), which stores a literal string.</td>
</tr>

<tr>
<td>[[Field design#STORE-DEFAULT .28SD.29 and STORE-NULL .28SN.29 attributes|STORE-NULL]]</td>
<td>(SN)</td>
<td>Specifies whether to physically store the null value for the field in each record, if no field value has been supplied, and a default is required. The default option is LITERAL (LIT), which stores a literal string.</td>
</tr>

<tr>
<td>[[Field design#Automatic Fields|UPDATE-TIME]]</td>
<td>(UPTM)</td>
<td>Captures the time when the record was updated, as of the start of the transaction.</td>
</tr>

<tr>
<td>[[Field design#Automatic Fields|UPDATE-TIMEUTC]]</td>
<td>(UPTMU)</td>
<td>Captures the Coordinated Universal Time when the record was updated, as of the start of the transaction.</td>
</tr>

<tr>
<td>[[Field design#Automatic Fields|UPDATE-USER]]</td>
<td>(UPUS)</td>
<td>Captures the user ID of the user who updated the record.</td>
</tr>

<tr>
<td>[[Field design#UTF-8 and UTF-16 attributes|UTF-8]]</td>
<td>(UTF8)</td>
<td>Data is stored in UTF-8 format and is treated as unicode data inside SOUL programs. The default is EBCDIC.</td>
</tr>

<tr>
<td>[[Field design#UTF-8 and UTF-16 attributes|UTF-16]]</td>
<td>(UTF16)</td>
<td>Data is stored in UTF-16 format and is treated as unicode data inside SOUL programs. The default is EBCDIC.</td>
</tr>
</table>

==System management enhancements==

===Writing records to the SMF data set===
Having Model 204 write records to the SMF data set no longer requires the installation of an SVC.

Therefore, the <var>[[SMFSVC parameter|SMFSVC]]</var> parameter is no longer required and, if present, will be ignored and flagged with the following informational message:
M204.0204: PARAMETER SMFSVC OBSOLETE AND NOT RESET
However, the <var>[[SMFLORN parameter|SMFLORN]]</var> and <var>[[SMFSLRN parameter|SMFSLRN]]</var> parameters must still be present in CCAIN to specify the types of SMF record to be written.

==Performance enhancements==

===64-bit addressing and Above The Bar (ATB) storage===
Model 204 moves above the (2G) bar to increase scalability, performance, and growth potential. With this release of Model 204, 64-bit addressing becomes the de facto standard for all subsequent versions.

In addition to the ATB support for FTBL released with Model 204 version 7.4, version 7.5 adds ATB support for GTBL, NTBL, and QTBL, using the same <var>[[SERVNSA parameter|SERVNSA]]</var> and <var>[[SERVNSSZ parameter|SERVNSSZ]]</var> parameters used for FTBL.

When using non-swappable ATB server space, each user will get SERVNSSZ bytes of ATB space, even if the thread is logged out or running resident requests. For greater efficiency, Model 204 version 7.5 also provides swappable ATB server areas that can supplement or replace the non-swappable areas. These swappable ATB server areas are controlled by the <var>[[SERVGA parameter|SERVGA]]</var> and <var>[[SERVGSZ parameter|SERVGSZ]]</var> parameters.

====GTBL, NTBL, QTBL in above the bar storage====
GTBL, NTBL and QTBL can now be placed into swappable or non-swappable server storage area above the bar.
In order to store a table in ATB storage:
<ul>
<li>Increase the <var>[[SERVNSSZ parameter|SERVNSSZ]]</var> parameter by the corresponding table size.
<li>Set the proper bit in <var>[[SERVNSA parameter|SERVNSA]]</var>:
<ul>
<li>for GTBL set the second byte to <code>X'80'</code>, so the value of <var>SERVNSA</var> is <code>X'00800000'</code></li>
<li>for NTBL set the third byte to <code>X'40'</code>, so the value of <var>SERVNSA</var> is <code>X'00004000'</code></li>
<li>for QTBL set the third byte to <code>X'20'</code>, so the value of <var>SERVNSA</var> is <code>X'00002000'</code></li>
</ul>
</ul>
'''Note:'''
The settings for each server table above the bar are independent of each other.
So if FTBL, GTBL, NTBL, and QTBL are all placed above the bar, then <var>SERVNSA</var> should be set to <code>X'02806000'</code>.

====XmlDoc pages in above the bar buffer pool====
With this release, the CCATEMP pages used for <var>XmlDoc</var> objects use the above the bar buffer pool, which may allow the below the bar buffer pool to be reduced, perhaps providing more storage for server areas. It also may provide a reduction in CPU utilization, especially when the <var>[[TEMPPAGE parameter|TEMPPAGE]]</var> parameter is used to allocate CCATEMP in memory.

===Improved range searching by Ordered Index (OI) chunk===
The new <var>[[DEFINE FIELD command#Ordered index CHUNK attribute|CHUNK]]</var> attribute for the <var>DEFINE FIELD</var> command enables more efficient range searching on Ordered Index numeric (<var>ORDERED NUMERIC</var>) fields. <var>CHUNK</var> improves performance of the <var>FIND</var> statement <var>RANGE</var> and <var>BETWEEN</var> terms. The <var>CHUNK</var> field attribute defines a subrange ("OI chunk") of the data range. Searching by OI chunks on a range of data requires fewer scans of the ordered index entries to find the desired data. Once OI chunk fields are defined, they are automatically used by FIND processing, so no application code needs to be changed.

After defining an <var>ORDERED NUMERIC</var> field, you define one or more related OI chunk fields containing data from the original base field rounded down by a specified <var>CHUNK</var> size.

Example:
DEFINE FIELD YYYYMMDD WITH ORDERED NUMERIC
DEFINE FIELD YYYYMM WITH ORDERED NUMERIC INVISIBLE CHUNK 100 FOR YYYYMMDD
DEFINE FIELD YYYY WITH ORDERED NUMERIC INVISIBLE CHUNK 10000 FOR YYYYMMDD


<var>CHUNK</var> requires the <var>[[#FILEORG (new settings)|FILEORG]]</var> X'100' bit setting and the <var>INVISIBLE</var> and <var>ORDERED NUMERIC</var> field attributes.

==Debugging and testing enhancements==
The SoftSpy debugging, testing, and performance tuning product is now included as part of the Model 204 core product. For more information about SoftSpy version 7.5, see the [[Release notes for SoftSpy V7.5]].

==Connect★ enhancements==
The 7.5 version of Connect★ for JDBC and Connect★ for .NET is now available.

===Connect★ for JDBC===
Connect★ 7.5 for JDBC offers a "connection pooling" class to interface with other pooling infrastructures provided by pooling packages and web application servers. This new feature allows for a pool of connections that remain active and open during execution of an SQL and RCL (SOUL) statement.
Using connection pooling helps eliminate the overhead of creating initial connections from scratch or trying to
manage each connection via JDBC API.

Each Connection Pool can create a pool of active connections maintainable throughout the connection cycle of the pooling service.

For a sample program, see the "Connect★ for JDBC" chapter of the <var class="book">Connect★ Installation and Programming Guide</var>.

Connect★ 7.5 for JDBC has been tested with the JNDI, Apache DBCPTM, BoneCP and C3PO pooling packages.

===Connect★ for .NET===
Connect★ 7.5 for .NET offers both 32-bit and 64-bit drivers that can be used with any Web or GUI-driven application.

==MQ/204 enhancements==

===Freeing MQ/204 subtasks and associated storage===
The new <var>MQDELDTP</var> PST (pseudo subtask) checks for MQ/204 subtasks that are in a delayed detach state. <var>MQDELDTP</var> detaches MQ/204 subtasks that have finished their work and releases their associated storage areas.

==Other features==
===AT-MOST-ONE and field groups===

The <var>AT-MOST-ONE</var> attribute is now applicable to a field group definition.

===Storing and updating LOBs===

All large object data (LOBs) in a <var>FILEORG</var> X'100' file are chained. There are four bytes per Table E page overhead for chained LOBs, used to maintain a queue of pages available for reuse after LOBs are deleted. The pages used by a chained LOB are not necessarily contiguous.


Handling LOBs in <var>FILEORG</var> X'100' files also has the following effects:
<ul>
<li>LOBs can be changed as needed. The <var>RESERVE</var> clause is ignored in a LOB field <var>ADD</var> statement processing, as well as the <var>STORE RECORD</var> statement processing of fieldname=value pairs. Consequently, the <var>CHANGE</var> statement does not fail because of insufficient reserved space. If the <var>CHANGE</var> statement requires that a LOB field be extended, it is.</li>

<li>The value of the <var>[[EHIGHPG parameter|EHIGHPG]]</var> parameter is always one less than the high water mark of the number of pages used to hold LOBs. (Unless none were ever added, in which case it is zero, not -1).</li>

<li>The value of the <var>[[EPGSUSED parameter|EPGSUSED]]</var> parameter is always the number of pages currently being used to hold LOBs.</li>

<li>The <var>COMPACTE</var> command does not process <var>FILEORG</var> X'100' files, just as it does not process a file created in V6R1 or earlier. Thus, issuing a <var>COMPACTE</var> command for a <var>FILEORG</var> X'100' file produces an error message.</li>

<li>The <var>TABLEE</var> command is effectively executing a <code>VIEW ESIZE EHIGHPG EPGSUSED</code> command for a <var>FILEORG</var> X'100' file. Consequently there are no <var>TABLEE</var> overhead pages in a <var>FILEORG</var> X'100' file.</li>
</ul>

===Constraint attributes===
You can set range constraints on fields using the constraint attributes. Each set of range attributes is comprised of four attributes (<var>GE</var>, <var>GT</var>, <var>LE</var>, <var>LT</var>) that you can use to establish a range for integer values, float values, or date-time stamp values. The types of range attributes are mutually exclusive. For example, you cannot define a field with the <var>FLOAT-GE</var> and <var>INTEGER-LE</var> attributes.

If a range constraint is redefined, it replaces the existing field constraint.

 Note: 
The range constraints do not have to match the data type of the stored field. That is, you could have a date-time constraint for a <var>STRING</var> field or an integer constraint for a <var>FLOAT</var> field, and so on.

You can set the following constraint attributes:
<ul>
<li>date-time value</li>
<li>pattern for a field value</li>
<li>length</li>
<li>integer value</li>
<li>floating point value</li>
</ul>

See [[Field design#Content constraints|Content constraints]] for details.

===Changes to journal record layouts===
Four bytes have been added to the journal record header for user statistic entries:
1 byte to hold the <var>IODEV</var> number and 3 bytes for future use.

All user since-last statistics (LAST=) lines will now show the <var>IODEV</var> value:
ST $$$ USERID='<var class="term">userid</var>' ACCOUNT='<var class="term">accountname</var>' IODEV='<var class="term">devicetype</var>' LAST='<var class="term">acty</var>'

For more information on journal records and user statistics, see the <var class="book">Rocket Model 204 System Manager's Guide</var>.

==Compatibility issues==
This section describes any compatibility issues between V7.5 and prior versions of Model 204.
An incompatibility arises if an operation that was previously performed without any indication of error, now operates (given the same inputs and conditions) in a different manner.

A normal bug fix resolving behavior that, although not indicating an error, was "clearly and obviously" incorrect, also introduces an incompatibility, but it might not be included below.

===Change to the Ordered Index layout===

Formerly all ORDERED NUMERIC fields came after all ORDERED CHARACTER fields in the Ordered Index. Now, the fields are interspersed in field code order.

===ZFIELD Image===

The [[ZFIELD image detail as of Model 204 V7.5|ZFIELD image]] has been updated for this release. The image is used with $LSTFLD and $FDEF function calls. One change is that FDEF is now longer (to accommodate FDEF1, LOOPVAR, and FDEF2).

===INTERCOMM is no longer supported===
The INTERCOMM interface supports the use of Teletype and 3270 terminals in line-at-a-time mode, using the Model 204 IODEV=29 thread type.

INTERCOMM is no longer supported as of Model 204 version 7.5.

See the <var class="book">Rocket Model 204 Terminal User's Guide</var> for a discussion of terminal interfaces.

===User PDL overflow===
The new <var>[[Release notes for Model 204 version 7.5 (DRAFT)#SEQPDL parameter|SEQPDL]]</var> parameter might require you to increase the size of the user Push Down List (using UTABLE LPDLST) by up to 3072 bytes, or more if you specify a value for SEQPDL that is larger than the 4096 default value.

===LPDLST parameter maximum value===
The maximum value for the <var>[[LPDLST parameter|LPDLST]]</var> parameter has been increased from 32760 to 65536.

===SSLIBSIZE parameter maximum value===
The maximum value for the <var>JANUS DEFINE</var> command <var>[[SSLIBSIZE (JANUS DEFINE parameter)|SSLIBSIZE]]</var> parameter has been decreased from 32767 to 16384.

==New and changed commands==

===DECREASE (new option: DYNAMIC)===
The DYNAMIC option on the <var>[[DECREASE command|DECREASE]]</var> command lets you decrease Table B dynamically, even if the file is open by others or has requests compiled against it.

===DEFINE DATASET (new parameter: GDGRECNT)===
The GDGRECNT parameter for the <var>[[DEFINE DATASET command|DEFINE DATASET]]</var> command causes Model 204 to check the catalog information for the latest relative GDG generation number whenever allocating a GDG data set.

===DEFINE FIELD (new or changed attributes)===
In Model 204 version 7.5, the <var>[[DEFINE FIELD command|DEFINE FIELD]]</var> command has new attributes information:
<ul>
<li>the new <var>[[#Improved range searching by Ordered Index .28OI.29 chunk|CHUNK]]</var> attribute, which improves the efficiency of range finds using ordered index processing</li>
<li>many other <var>[[FILEORG parameter|FILEORG=x'100']]</var> related new or changed [[Release notes for Model 204 version 7.5 (DRAFT)#New field attributes|field attributes]]</li>
</ul>

===DEFINE FIELDGROUP (new in V7.5)===
The <var>[[DEFINE FIELDGROUP command|DEFINE FIELDGROUP]]</var> command establishes the contents of a field group, including the fields and field groups associated with the field group being defined.

===DELETE FIELD (changed to handle CAT and CTO fields)===
The <var>[[DELETE command: Field|DELETE FIELD]]</var> command has been changed to take [[Field design#CONCATENATION-OF .28CAT.29 attribute|CONCATENATION-OF (CAT)]] and [[Field design#Counting occurrences of a field|COUNT-OCCURRENCES-OF (CTO)]] fields into account. DELETE FIELD does not allow deletion of fields referred to by an existing CAT or CTO field.

===DELETE FIELDGROUP (new in V7.5)===
The <var>[[DELETE FIELDGROUP command|DELETE FIELDGROUP]]</var> command deletes a field group from a Model 204 file.

===DISPLAY FIELD (new option: COMMA)===
In Model 204 version 7.5, the <var>[[DISPLAY FIELD command|DISPLAY FIELD]]</var> command has added
the <var>COMMA</var> option, which uses commas to separate displayed field attributes.

===DISPLAY MODMAP (new in V7.5)===
<var>[[DISPLAY MODMAP command|DISPLAY MODMAP]]</var> displays the Model 204 link map in address order. System manager privileges are required.
===MSGCTL (new options: UP/UPPER, NOUP/NOUPPER)===
The <var>UP</var> (or <var>UPPER</var>) option on the [[MSGCTL command]] indicates that the specified message should be converted to uppercase before display. Similarly, the <var>NOUP</var> (or <var>NOUPPER</var>) option on the MSGCTL command undoes the effects of <var>UP</var> or <var>UPPER</var>.

===REGENERATE and REGENERATE ONEPASS (improved TO UPDATE option)===
The TO UPDATE option of the <var>[[REGENERATE command|REGENERATE]]</var> and <var>[[REGENERATE ONEPASS command|REGENERATE ONEPASS]]</var> commands can now handle multiple files.
If TO UPDATE <var class="term">nn</var> OF <var class="term">id</var> is specified, it must appear only on the first FILE statement, and no other �TO� options are allowed on subsequent files.
All additional files will be recovered as though they each specified the same 'TO UPDATE' option. Once the 'end of transaction' is reached, further processing will stop and all inflight transactions will be backed out.

===RENAME FIELDGROUP (new in V7.5)===
The <var>[[RENAME FIELDGROUP command|RENAME FIELDGROUP]]</var> command changes the name of a field group.

===UNICODE (new codepage: 1154)===
The <var>[[UNICODE command|UNICODE]]</var> command now accepts 1154 as a codepage name. This codepage has 92 Unicode characters in the range U+0400 through U+045F, representing the Basic Russian alphabet and all of the Cyrillic extensions excepting the four which have grave accents.


==Reliability enhancements==
===SEQPDL parameter===
The new <var>[[SEQPDL parameter|SEQPDL]]</var> parameter controls the amount of free space that must be present in the user's Push Down List (PDL) in order for the SOUL sequencer to proceed with the next quad code. The minimum and default value is 4096 bytes. The maximum value is 8192 bytes. SEQPDL is a user resettable parameter and can be set on the user's parameter line or reset with the UTABLE command.

Formerly 1024 bytes of PDL free space were hardcoded internally in the Model 204 core. With 1024 bytes there were edge cases where abends would break files, resulting in ERROR 2126 USER'S PUSHDOWN LIST OVERFLOWED. SEQPDL is provided to allow enough PDL space so that all of the lower level journaling routines can process error conditions without breaking files.

If your applications are using close to the amount of PDL space currently set by the LPDLST value, you might need to increase LPDLST to reflect SEQPDL's increase in free space.

==New and changed parameters==
In addition to the following specific parameter changes, <var class="product">Model 204</var> parameter descriptions, for example as displayed by the <var>VIEW</var> command, are now in mixed case (unless translated to uppercase due to <var>[[#UPCASMSG (new in V7.5)|UPCASMSG]]</var>.)

Note: The [[Sirius Mods]] parameters are merged with the <var class="product">Model 204</var> base as of <var class="product">Model 204</var> version 7.5, and they are available to all version 7.5 customers. The combined set of parameters is displayed on the [[List of Model 204 parameters]] page. The former Sirius parameters in that listing are marked with an (S). 


===DEFCNTX and APDFCNTX (for $View function only, new in V7.5)===
The string
<code>DEFCNTX</code> or <code>APDFCNTX</code> can be used as an
argument to the <var>[[$VIEW|$View]]</var> function to
get the default file or group context. Using these strings is better than using <code>$View('CURFILE')</code> because:
<ul>
<li><code>CURFILE</code> returns a null string if the default context is a group.

<li><code>CURFILE</code> is affected by the <var>IN</var> clause prior to a <var>Begin</var> command and
can be affected by the <var>In</var> clause prior to many SOUL statements.
</ul>

If there is no default context, <code>$View('DEFCNTX')</code> returns a null
string.

Otherwise <code>$View('DEFCNTX')</code> returns the type of context (<code>FILE</code>, <code>TEMP GROUP</code>, or
<code>PERM GROUP</code>) followed by the file or group name, with trailing blanks
removed.

<code>$View('APDFCNTX')</code> returns the same information based on the default
context when the APSY was entered, unless that is the same as one of the files or groups in the subsystem's definition; in that case, the null string is returned.

Note: These <code>$View</code> arguments were implemented as part of
maintenance to version 7.5 (via zap number 54). They are not available as ordinary parameters on the <var>VIEW</var> command.
In version 7.6 of Model 204,
they will also be available with the <var>VIEW</var> command.


===DSPOPT (change to default setting)===
The default setting for [[DSPOPT parameter|DSPOPT]] has been changed from X'00' to X'01'. The X'01' setting allocates space for servers in memory in chunks of 4K pages, not as a permanent contiguous area. This allocation lets you move fewer 4K pages, keeping the virtual storage allocated for servers in memory less fragmented and possibly using fewer paging tables.

===ECPSIZE (change to max value)===
The maximum value setting for [[ECPSIZE parameter|ECPSIZE]] has been increased from 1310680 to 1966020 to accommodate more [[Release notes for Model 204 version 7.5 (DRAFT)#External Call Facility .28ECF.29|External Call Facility]] parameters.

===FILEORG (new settings)===
<ul>
<li>
The <var>[[FILEORG parameter|FILEORG]] X'100'</var> setting for enhanced data handling files is now available.

X'100' enables a number of enhancements to the file structure, including: 
<ul>
<li>[[Release notes for Model 204 version 7.5 (DRAFT)#Support for physical field groups|Support for physical field groups]] </li>

<li>The definition of as many as 32000 fields in a file </li>

<li>System maintained [[Field design#Automatic Fields|Automatic fields]] </li>

<li>[[Field design#Field constraints|Field constraints]] providing content validation </li>

<li>Improved space management of fields containing [[Field design#BLOB, CLOB, and MINLOBE attributes|Large Objects]] </li>

<li>[[#New field attributes|New DEFINE FIELD attributes]], such as <var>CHUNK</var>
</ul>

If X'100' is selected, the X'80' bit (optimized field extraction files) is automatically set.</li>

<li>The <var>FILEORG X'200'</var> setting for large file support is now available. </li>

X'200' allows files to hold up to 48 million records.
</li>
</ul>

===FISTAT (change to X'08' setting)===
The <var>[[FISTAT parameter|FISTAT]] X'08'</var> (file full) setting is now automatically cleared in a transaction back out file if table D is increased enough so that DSIZE is greater than or equal to DPGSRES+DPGSUSED.

===LRETBL (setting increase may be necessary)===
Because there might be a slight increase in record locking table usage in V7.5, an increase in the value of the <var>[[LRETBL parameter|LRETBL]]</var> parameter is advised. The amount of the increase is best estimated by multiplying by 16 the <code>HWM HEADERS</code> value (from a <var>[[MONITOR ENQ command|MONITOR ENQ]]</var> report), then dividing by the value of the <var>NUSERS</var> parameter. For example, if <code>HWM HEADERS = 100000</code> and <code>NUSERS=2000</code>, the recommended <var>LRETBL</var> increase is <code>16*100000/2000</code>, or 800.

===MISCOPT (obsolete)===
The <var>[[MISCOPT parameter|MISCOPT]]</var> parameter is now obsolete. In Model 204 version 7.5, MISCOPT is still viewable but is not resettable.

===MODTIM (new in V7.5)===
The <var>[[MODTIM parameter|MODTIM]]</var> system parameter displays the most recent assembly date and time of the Model 204 load module.

===OUTPUT (change to allow OUTPUT=DUMMY)===
IODEV=3 threads definitions now allow OUTPUT=DUMMY.
When defining IODEV=3 threads, if output is not required, the OUTPUT parameter can be coded as OUTPUT=DUMMY.
For example:
IODEV=3,INPUT=IOD3IN1,OUTPUT=DUMMY
IODEV=3,INPUT=IOD3IN2,OUTPUT=DUMMY
IODEV=3,INPUT=IOD3IN3,OUTPUT=DUMMY
and so on.

This means that no DD statement is required for the output data set, and in cases where many
IODEV=3 threads are defined to simulate a large number of users, this enhancement will reduce the number of DD statements required by one half.

===RECLOCKO (X'04' bit now ignored)===
The <var>[[RECLOCKO parameter|RECLOCKO]]</var> X'04' bit is now ignored, and the extra information of the conflicting user number and lock time are now always available.

===RESPAGE (new in V7.5)===
The <var>[[RESPAGE parameter|RESPAGE]]</var> parameter activates the APSY Precompiled Procedures in storage feature using above the bar pages by specifying a number of 4K operating system pages.

Specifying RESPAGE stores precompiled procedures as resident requests above the bar in the RESPAGE area. Using RESPAGE allows you to substantially increase the resident request area and decrease server swapping of QTBL and NTBL pages.

Also, when RESPAGE is used, RESSIZE is reset and the storage below the bar specified by RESSIZE is no longer used.

Storing resident requests above the bar is independent of tables above the bar. You can use a combination of resident request and swappable servers ATB to reduce below the bar server sizes and thus increase the number of servers.

===RETRVKEY (change to allow forward retrieve PF key)===
New in this release, if you specify a non-zero setting of <var>[[RETRVKEY parameter|RETRVKEY]]</var>:
<ul>
<li>If you have set the <code>X'01'</code> or <code>X'10'</code> bits of the <var>[[RETRVOPT parameter|RETRVOPT]]</var> parameter, you can use a
forward retrieve PF key, in addition to the backward retrieve PF key specified by <var>RETRVKEY</var>.
'''Note:'''
If either of these bits is set, the <code>X'02'</code> bit is strongly recommended as well.
<li>The size of the allocated storage area, and hence the number and length of input lines available for retrieval, is specified
by the value of the <var>[[RETRVBUF parameter|RETRVBUF]]</var> parameter.</ul>

===SEQPDL (new in V7.5)===
The <var>[[Release notes for Model 204 version 7.5 (DRAFT)#SEQPDL parameter|SEQPDL]]</var> parameter controls the amount of free space that must be present in the user's Push Down List in order for the SOUL sequencer to proceed with the next quad code. SEQPDL allows enough PDL space for the lower level journaling routines to handle error conditions properly without breaking files and causing ERROR 2126 USER'S PUSHDOWN LIST OVERFLOWED.

===SESMAXTO (new in V7.5)===
The <var>[[SESMAXTO parameter|SESMAXTO]]</var> parameter can be used limit the maximum [[Sessions|session]] timeout value or to cause all current closed sessions to be immediately discarded.

===SMFSVC (obsolete)===
The <var>[[SMFSVC parameter|SMFSVC]]</var> parameter is [[Release notes for Model 204 version 7.5 (DRAFT)#Writing records to the SMF data set|obsolete]] as of Model 204 version 7.5.
===SNAPCTL (change to default setting)===
The default setting for [[SNAPCTL parameter|SNAPCTL]] has been changed from X'41' (X'44' under CMS) to X'28'. The X'28' setting results in smart snaps – relatively small snaps with all the information that is likely to be required to diagnose the cause of the snap. This setting allows snaps to be taken quickly, and for those snaps being easily sent to Rocket support with little or no adverse effect on the possibility of diagnosing the cause of the snap.

===UPCASMSG (new in V7.5)===
The <var>[[UPCASMSG parameter|UPCASMSG]]</var> parameter can be used to translate messages issued by <var class="product">Model 204</var> to uppercase; otherwise (depending on the message being issued) they are displayed in mixed (upper and lower) case.




==Documentation conversion to wiki format==
Rocket Model 204 documentation is being converted from individual manuals in PDF format to a set of cross-linked HTML articles in this integrated wiki, M204wiki.

As of Model 204 release 7.5, several manuals are now in wiki format and the rest remain in PDF format, available in the M204 folder of the [http://docs.rocketsoftware.com/nxt/gateway.dll?f=templates$fn=default.htm Rocket Software Documentation Library].

For details, see [[Model 204 documentation]].

==New and updated messages==

Many messages have been updated and added in this release. See [[New and updated messages in Model 204 version 7.5]] for details.

[[Category: Release notes]]

Field group (File architecture)

2014-08-01T13:43:01Z

Mlarocca:

==Overview==

Data items do not normally exist on their own. In the case of addresses, for example, a series of fields exist for each address (house number, city, state, zip code) which clearly operate interdependently. 

The idea of a physical field group is to take these related fields and package them as a single entity so they can be read and updated with a single operation. (See [[Field group design]] for details.)

Such packaging not only improves the readability and maintainability of SOUL programs (see [[Operations on multiply occurring fields]] for the details of the SOUL statements involved), but it also makes the Model 204 processing far more efficient.

==Performance==

Code that accesses field groups performs better in three main areas:
<ul>
<li>Improved record scanning</li>

<li>Performing adds/inserts or deletes as a single operation</li>

<li>Retrieval of all field groups on a record (requires only one I/O if the entire record is stored on a single page)</li>
</ul>

===Improved record scanning===

In general, much of the time spent in Model 204 processing is used to scan across a record, and this scan reads a field at a time. If a field is not the field that is needed, scanning moves to the next field, and so forth. As records grow in length, such a scan obviously takes longer.

With field groups, the scan skips a group rather than a field at a time, so it can find a specified data item faster.

In reality, however, the improvement is better than this. If you are looking for a number of related (but non-field-group) fields, a separate scan is required to find each field (insert rules mean that the data cannot be presumed to be contiguous). So if you are looking for six individual fields, the record must be scanned once for each.

If the related fields are packaged as a field group, a single scan of the record finds all the fields. In addition, all of the related data items are in a single location.

===Adds/inserts and deletes are performed as single operations===

Consider the following blocks of code:

INSERT ADDRESS_TYPE(%LOC) = %ADDR:TYPE
INSERT HOUSE_NUMBER(%LOC) = %ADDR:NUM
INSERT STREET(%LOC) = %ADDR:STREET
INSERT CITY(%LOC) = %ADDR:CITY
INSERT STATE(%LOC) = %ADDR:STATE
INSERT ZIP(%LOC) = %ADDR:ZIP

Each of these statements is a separate operation. For each one, the correct position in the record must be found, then the field is inserted. This sequence is repeated six times. 

Instead, with a field group, the following syntax does the entire insert as a single operation. Only one insert position needs to be found, and then the entire set of fields is inserted:
INSERT FIELDGROUP ADDRESS(%LOC)
ADDRESS_TYPE = %ADDR:TYPE
HOUSE_NUMBER = %ADDR:NUM
STREET = %ADDR:STREET
CITY = %ADDR:CITY
STATE = %ADDR:STATE
ZIP = %ADDR:ZIP
END INSERT

==Field groups and Table B storage considerations==

At first glance, the performance improvement of field groups comes at a cost of space (but this can usually be offset).

The costs:
<ul>
<li>Every record in a FILEORG=X'100' file contains the 4-byte highest allocated field group ID. Every occurrence of a field group has a unique binary ID that occupies from two to five bytes, thus supporting up to four gigabytes of field group IDs.</li>

<li>As is true of all FILEORG=X'100' files, the field name representations (as held in [[Table A (File architecture)|Table A]] and thus in the record), are three bytes in length. Depending on the definitions of the fields within the group, this might be offset by the physical absence of fields defined as part of the group.</li>
</ul>

===Space saving and default and null values===

Depending on the characteristics of the data you are storing, using field groups might actually save space.

Take as an example a financial application where you are tracking a number of types of income over time. You have a field group containing a date and a number of income types: salary, interest, dividends, and so forth. It is likely that the majority of people whose data you are keeping have only a few of the many types of interest, so your record might have mostly zeros.

If so, by adding a [[Field design#DEFAULT-VALUE (DV) attribute|default value]] of 0 and a [[Field design#STORE-DEFAULT (SD) and STORE-NULL (SN) attributes|store default]] of NONE (the default for [[Field design#AT-MOST-ONE, REPEATABLE and EXACTLY-ONE attributes|exactly one]] fields in field groups), none of the 0s would be physically stored (but would be treated as if they were).

For many files, implementing field groups will improve both performance and space utilization.

==Field group identifiers==
As mentioned above, every field group has a unique ID.

This ID can be read with the <var>[[$FieldgroupId]]</var> function, and it is also displayed by the <var>[[Basic SOUL statements and commands#PRINT ALL INFORMATION (or PAI) statement|Print All Information]]</var> statement.

By itself, the ID is just for uniqueness, but it has an interesting use that is invaluable in debugging: you can determine the order in which things happened to a file.

[[Category:File architecture]]

Processing multiply occurring fields and field groups

2014-08-01T13:42:11Z

Mlarocca:

<div class="toclimit-3">

==Overview==

A single field name that has different values can be stored repeatedly in a record. For example, the field <code>CHILD</code> in the record shown below is an example of a multiply occurring field:
FATHER = JOHN DOE
CHILD = ELIZABETH
CHILD = ROBERT


Any field name except for the following types of fields can be present more than once in a record: 
<ul>
<li>A NUMERIC RANGE field </li>
<li>A sort key </li>
<li>A hash key </li>
</ul>

<div id="FIELDGROUP overview"></div> 

JOHN DOE might also have a medical record that recorded multiple surgeries, each of which is associated with a surgeon and a date. His record contains repeated instances of these three related fields:
SURGERY_TYPE
SURGEON
SURGERY_DATE 

As of version 7.5 of <var class="product">Model 204</var>, SOUL lets you define these fields as part of a "physical" field group, which means they are stored, retrieved, and updated as a single instance of, say, the <code>SURGERY</code> field group. You could define these fields as individual multiply occurring fields and group them logically in your SOUL code, but the physical field group structure has significant processing efficiencies.

Field groups may only be defined for records in files that have the <var>[[FILEORG parameter|FILEORG]]</var> parameter set to include <code>X'100'</code>. Information about how to define a field group is found in [[Field group design#Defining a field group|Defining a field group]].

===Special processing for multiply occurring fields and field groups===

Certain SOUL statements operate differently on multiply occurring fields and field groups than on singly occurring fields. SOUL provides special statements and forms of statements that can be used with multiply occurring fields and field groups, notably including the <var>EACH</var> modifier and subscripts. SOUL also provides for the use of subscripted field references for accessing a particular occurrence of a multiply occurring field or field group.

==FIND statement==

===Retrieval by an exact occurrence value===

====Example 1====

Assume this sample record: 
FATHER = JOHN DOE
CHILD = ELIZABETH
CHILD = ROBERT


You can use either of these two statements to retrieve the record: 
FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD = ELIZABETH
END FIND

FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD = ROBERT
END FIND


====Example 2====

The record is not retrieved by either of these statements:
FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD = NOT ELIZABETH
END FIND

FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD = NOT ROBERT
END FIND


===Multi-condition range retrievals===

You should pay special attention to the effect of multiply occurring fields on multi-condition range retrievals. Undesirable results can occur if a range search is specified for a multiply occurring field. For example: 
FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD IS AFTER KEN AND BEFORE PAUL
END FIND


retrieves the sample record even though neither child's name in the sample is between KEN and PAUL. <var class="product">Model 204</var> evaluates each condition of the FIND separately, then combines the results of each evaluation to build the set of records satisfying all conditions. The BETWEEN operator behaves exactly like any other multi-condition range retrieval when used on a multiply occurring field.

If a range search must be performed on a multiply occurring field, use the IN RANGE clause of the FIND statement. Refer to [[Record retrievals#NUMERIC RANGE and ORDERED NUMERIC attributes|NUMERIC RANGE and ORDERED NUMERIC attributes]] for more information about the IN RANGE clause. Better code for the previous example is: 
FIND.RECS: FIND ALL RECORDS FOR WHICH
CHILD IS ALPHA IN RANGE
AFTER KEN AND BEFORE PAUL
END FIND


===Use of subscripts===

You cannot use subscripted references with the FIND statement. Refer to [[#Subscripts|Subscripts]] for more information about using subscripts with multiply occurring fields.

==NOTE statement==

===Only first occurrence is noted===

The NOTE statement notes only the first occurrence of a multiply occurring field. For example, only the first occurrence of the field (CHILD = ELIZABETH) are noted by:
KEEP.CHILD: NOTE CHILD


===Use of subscripts===

In order to note a particular occurrence of a multiply occurring field, the field name must be subscripted. Refer to the discussion of subscripts on [[#Subscripts|Subscripts]] for detailed information on subscripted field names and usage.

==PRINT and PRINT n statements==

===PRINT statement output format===

The PRINT statement prints only the first occurrence of a field in a record. 

If there is more than one value of a field in a record, the special modifier, EACH, can be used in a PRINT statement to print out all the values on a single line, with a single space between values.

====Example 1====
PRINT EACH INCIDENT


yields:
T1 T2 T1 T3 T2 T1


====Example 2====

If the field is given a column position, as in:
PRINT FULLNAME WITH EACH INCIDENT AT COLUMN 18


values are printed one to a line and positioned at the column specified. 
ABBOTT, GAIL H T1 -
T3 -
T1 -
T3 -
T2 -
T1


====Example 3====

A field cited in a PRINT statement after a multiply occurring field is printed on the same line as the last value of the multiply occurring field. If you change the PRINT statement in the sample request as here:
PRINT FULLNAME WITH EACH INCIDENT AT COLUMN 18 -
WITH POLICY NO AT COLUMN 23 -
WITH STATE AT COLUMN 32


This output results:
ABBOTT, GAIL H T1 -
T3 -
T1 -
T3 -
T2 -
T1 100340 CALIFORNIA


===Use of subscripts===

See [[#PRINT statement|PRINT statement]] for a description of using PRINT with subscripts.

===PRINT n statement===

Long fields, such as abstracts, evaluations, or statements of purpose, can be stored as a multiply occurring field. Each occurrence can contain as many as 255 characters. 

====Syntax====

You can use this PRINT statement to print such a field as a paragraph:
PRINT n fieldname


where <var class="term">n</var> must be a number less than 32,768.

====Output format====

The <var>PRINT n</var> statement prints up to n lines of text, composed of all of the occurrences of the field concatenated in order. Nothing is inserted. At most, n lines are printed; any extra lines are ignored. 

Ordinarily, a PRINT statement that produces more than one line inserts a hyphen in the continuation column of the output device. Instead of using the continuation column, this form of PRINT attempts to end each line with a complete word delimited by spaces. If there is insufficient space to fit the last word on a line, the word is hyphenated arbitrarily and continued on the next line. 

The AT COLUMN and TO COLUMN clauses can be used to adjust the output to a narrower column. When used together with PRINT n, text is broken at word boundaries to fit within the column. The AT clause does not affect the first line, and the TO clause does not affect the last line (unless the line limit n is exceeded). This allows indenting. 

The AT or TO column options cannot accept negative numbers or numbers greater than 32767 for the column. 

Procedures containing PRINT statements with negative numbers or numbers greater than 32767 fail at compile time with the following counting error message:
M204.0263: AT/TO MUST BE BETWEEN 1 AND 32767


====Example====

This example illustrates the use of the <var>PRINT n</var> statement.
BEGIN
PRINT '1234567890123456'
STORE RECORD
TEXT = 'NOW IS THE T'
TEXT = 'IME FOR'
TEXT = ' ALL GOOD MEN TO'
ITEM = 1
END STORE
FD.REC: FIND ALL RECORDS FOR WHICH
ITEM = 1
END FIND
FOR 1 RECORD IN FD.REC

PRINT.TEXT: PRINT <nowiki>''</nowiki> AT COLUMN 5 WITH 3 TEXT -
AT COLUMN 3 TO 16
END FOR
END


The output produced is:
1234567890123456
NOW IS THE
TIME FOR ALL
GOOD MEN TO


The <code>PRINT.TEXT</code> statement concatenates a null value (two single quotes with no space between them) with the <var>PRINT n</var> form to indent the first line of text by using the location of the null value (column 5).

Note that the printing stops short of column 16 to avoid truncating TIME and GOOD. 

====Use with subscripts====

You cannot use subscripted references with the PRINT n statement. Refer to [[#Subscripts|Subscripts]] for more information about using subscripts with multiply occurring fields.

==ADD, CHANGE, and DELETE statements==

The ADD and CHANGE statements, and both forms of the DELETE statement, are supported in remote file and scattered group contexts.

===ADD statement===

The ADD statement places new occurrences of a field after existing occurrences. For example, if new children are added to the sample record, the additions are placed last. Thus: 
ADD CHILD = SARAH
ADD CHILD = PATRICK


results in the record:
FATHER = JOHN DOE
CHILD = ELIZABETH
CHILD = ROBERT
CHILD = SARAH
CHILD = PATRICK


====The INSERT statement====

If the order of occurrence is important, the INSERT statement can be used to add new occurrences. See the discussion on [[#INSERT statement|INSERT statement]]. 

===CHANGE statement===

The CHANGE statement alters only the first occurrence of a field in a record. 

====Syntax====

You can use this form of the CHANGE statement if there is more than one occurrence: 
CHANGE fieldname = value1 TO value2


This form, like the <var>CHANGE fieldname</var> statement, can be used only inside a FOR EACH RECORD loop. It deletes the first occurrence of the pair fieldname = value1 from a record, and adds the pair fieldname = value2 to the record. The new value is added either in the position occupied by the original value or at the end of the record, depending upon the update attribute specified for the field by the file manager. See the discussion in [[#UPDATE field attribute|UPDATE field attribute]]. 

If the specified field, <var class="term">fieldname</var> = <var class="term">value1</var>, does not appear in the record, <var class="term">fieldname</var> = <var class="term">value2</var> is simply added to the record. If the specified <var class="term">fieldname</var> = <var class="term">value1</var> pair appears more than once in the record, only the first occurrence of it is deleted. The pair, <var class="term">fieldname</var> = <var class="term">value2</var>, is added just once. Occurrences of the field name that have other values are not altered by the statement. 

===DELETE statement===

The DELETE statement deletes only the first occurrence of the field in the record by default. 

====Two forms of DELETE statement====

For multiply occurring fields, two forms of the DELETE statement are provided; however only for use inside a FOR EACH RECORD loop: 
<table>
<tr class="head">
<th>To delete... </th>
<th>Syntax </th>
<th>Usage</th>
</tr>

<tr>
<td>A particular occurrence </td>
<td nowrap>DELETE fieldname = value </td>
<td>

To delete the first occurrence of the pair, <var class="term">fieldname</var> = <var class="term">value</var>, from a record. Occurrences of the field that have other values are not removed. If the field with the specified value:

Occurs more than once in the record, only the first occurrence is deleted. 

Cannot be found, no deletion occurs.
</td>
</tr>

<tr>
<td>Every occurrence of the field in the record </td>
<td>DELETE EACH fieldname </td>
<td>To delete all occurrences of the specified field name. The field to be deleted cannot have the INVISIBLE attribute. </td>
</tr>
</table>

====Use with the FOR EACH OCCURRENCE statement====

See [[#Deleting occurrences of fields and field groups|Deleting occurrences]] for a discussion of deleting occurrences using the FOR EACH OCCURRENCE OF (FEO) statement.

====Use with subscripts====

See [[#DELETE statement|DELETE statement]] for a discussion of using the DELETE statement with subscripts.

==SORT RECORDS statement==

When a multiply occurring field is chosen as a sort key, each record in the set being sorted is processed once using the first occurrence of the field as the key. 

===EACH modifier with one sort field===

If the EACH modifier is present in the SORT statement and if there are n occurrences of the field in the record, similar records are created in the sorted copy of the original set. 

====Example====

The following request:
SORT RECORDS IN FIND.RECS BY EACH KEY


generates three temporary records for the single permanent record in which the field named <code>KEY</code> occurs three times:
KEY = COMPUTER
KEY = CORPORATION
KEY = AMERICA


The records generated are:
1 KEY = COMPUTER 2 KEY = CORPORATION
KEY = CORPORATION KEY = AMERICA
KEY = AMERICA KEY = COMPUTER

3 KEY = AMERICA
KEY = COMPUTER
KEY = CORPORATION


These correspond to the <var class="term">n</var> cyclic permutations of the set of field occurrences and, in this example, are sorted into the order 3, 1, 2 (if no other option is selected). Statements that refer to the sorted set, such as PRINT, PRINT EACH, NOTE, and PRINT ALL INFORMATION (PAI), reflects the permutation. No record is generated if <var class="term">n</var> = 0.

===EACH modifier with several key fields===

When the EACH option is selected for several keys, <var class="term">n</var> occurrences of one key and <var class="term">m</var> of another produce differently permuted records. If either <var class="term">n</var> or <var class="term">m</var> equal 0, no records are generated. 

====Example====

This request:
BEGIN
FIND.RECS: IN CLIENTS FIND ALL RECORDS FOR WHICH
INCIDENT = T1
END FIND
SORT.RECS: SORT RECORDS IN FIND.RECS BY FULLNAME -
AND EACH INCIDENT DATE
FOR EACH RECORD IN SORT.RECS
PRINT FULLNAME WITH INCIDENT DATE -
AT COLUMN 25
END FOR
END


produces printed output of:
ABBOTT, FRANKLIN G 860323
ABBOTT, GAIL H 861022
ABRAMS, RUTH Z 861115
ABRAMS, RUSSELL Y 870218
ABBOTT, FRANKLIN G 870424
ABBOTT, GAIL H 871123
. .
. .
. .


===If no occurrences are present===

A record that does not contain at least one occurrence of the INCIDENT DATE field produces no printed output. Similarly:
SORT RECORDS IN FIND.RECS BY EACH A AND EACH B


would produce nothing for those records that do not have at least one occurrence of both A and B. 

==FOR EACH RECORD statement==

The FOR EACH RECORD IN ORDER BY statement retrieves and loops on only the first occurrence of a field in a record. 

===EACH modifier===

If there is more than one value of a field in a record, the special modifier, EACH, can be used to retrieve and loop on all values of the field. 

The EACH modifier only can be used on a FOR EACH RECORD statement that specifies index order processing (the IN ORDER BY fieldname clause must be used and the field must have the ORDERED attribute). The VALUE IN phrase must be used to retrieve the current value of the ORDERED field driving the loop. 

====Example====

This example of the FOR EACH RECORD IN ORDER BY statement:
BEGIN
FR1: FOR EACH RECORD IN ORDER BY EACH INCIDENT DATE
PRINT VALUE IN FR1 WITH FULLNAME AT COLUMN 25
END FOR
END


returns each record in order by each value of the ORDERED field, as follows:
760323 ABBOTT, FRANKLIN G
761022 ABBOTT, GAIL H
761115 ABRAMS, RUTH Z
770218 ABRAMS, RUSSELL Y
.
.
.


==Special statements for multiply occurring fields and field groups==

SOUL provides several statements for handling multiply occurring fields and [[Field group design|field groups]]. Field groups are supported as of Model 204 version 7.5.
<ul>
<li>COUNT OCCURRENCES (used with singly occurring fields, too)</li>
<li>FOR ALL OCCURRENCES OF FIELDGROUP </li>
<li>FOR EACH OCCURRENCE (used with singly occurring fields, too)</li>
<li>FOR FIELDGROUP</li>
<li>DELETE EACH OCCURRENCE</li>
</ul>
Note: See also the [[#INSERT statement|INSERT statement]], which you can use to add new occurrences of a field.

===COUNT OCCURRENCES OF statement===

The COUNT OCCURRENCES OF (CTO) statement counts the number of occurrences of the named field in the current record. 

====Syntax====

The format of the COUNT OCCURRENCES statement is:
label: COUNT OCCURRENCES OF fieldname


or
label: CTO fieldname


The field name cannot be subscripted. The COUNT OCCURRENCES OF statement can appear only within a FOR EACH RECORD loop.

The COUNT OCCURRENCES statement is supported in remote file and scattered group contexts.

====COUNT IN clause====

The COUNT IN clause refers to the count obtained by the COUNT OCCURRENCES OF statement. This request:
BEGIN
FIND.RECS: IN VEHICLES FIND ALL RECORDS
END FIND
FOR 5 RECORDS IN FIND.RECS
NO.OF.VINS: COUNT OCCURRENCES OF VIN
PRINT OWNER POLICY WITH ' INSURES ' WITH -
COUNT IN NO.OF.VINS WITH ' VEHICLE(S)'
END FOR
END


generates the following output:
100025 INSURES 1 VEHICLE(S)
100030 INSURES 1 VEHICLE(S)
100032 INSURES 1 VEHICLE(S)
100051 INSURES 1 VEHICLE(S)
100058 INSURES 1 VEHICLE(S)


===FOR ALL OCCURRENCES OF FIELDGROUP (FAO FIELDGROUP) statement===
The FAO statement collects the field group IDs for all occurrences, then processes against that list. FAO is not valid for use against multiply-occurring fields, only against field groups (introduced in Model 204 V7.5).

====Syntax====

The format of the statement is:
FOR ALL OCCURRENCES OF FIELDGROUP (fgname | %%varGrp)

Where:
<ul>
<li><var class="term">fgname</var> specifies a field group name.</li>

<li>%%<var class="term">varGrp</var> specifies a field group name variable.</li>
</ul>
The difference between an FAO statement and an FEO statement is that the FAO statement is less affected by insertions or deletions of FIELDGROUP <var class="term">fgname</var> within the loop, due to the semantics of field group IDs. This means that deleting the current occurrence within the loop will not affect occurrences referenced in subsequent iterations.

===FOR EACH OCCURRENCE OF loops===

On each loop of FOR EACH OCCURRENCE OF (FEO), the VALUE IN and OCCURRENCE IN labels refer to value and position, respectively, of the next field occurrence, starting with occurrence 1 and increasing by 1 for each pass through the loop. When the next field occurrence number is greater than the number of field occurrences in the record, the loop terminates. 

====Syntax====

The format of the FOR EACH OCCURRENCE loop is:
label: FOR EACH OCCURRENCE OF fieldname


Alternatively,
label: FEO fieldname


The FOR EACH OCCURRENCE OF statement is supported in remote file and scattered group contexts.

To work with specific field values inside an FEO loop, two styles of reference are supported: OCCURRENCE IN {label}, which is used as a field subscript, and VALUE IN {label} with is a direct reference to a field occurrence.

====Example====

Consider this record:
FIRST NAME = RICHARD
LAST NAME = SMITH
CHILD = HENRY
CHILD = SALLY
CHILD = JANE
ADDRESS = AVON DRIVE


This request creates a separate record for each child.
BEGIN
FD.REC: FIND ALL RECORDS FOR WHICH
FIRST NAME = RICHARD
LAST NAME = SMITH
END FIND
FOR EACH RECORD IN FD.REC
NOTE.ADD: NOTE ADDRESS
CHILD.LOOP: FOR EACH OCCURRENCE OF CHILD
PRINT VALUE IN CHILD.LOOP
STORE RECORD
FIRST NAME = VALUE IN CHILD.LOOP
LAST NAME = SMITH
ADDRESS = VALUE IN NOTE.ADD
END STORE
END FOR
END FOR
END


====Simulating a FOR EACH VALUE loop====

The FOR EACH OCCURRENCE OF statement can be used to simulate a FOR EACH VALUE loop if the field contains a static collection of known values. Consider the values of states. The user sets up a single record that has a multiply occurring field in sorted sequence as follows: 
TYPE = STATE
CODE = ALABAMA
CODE = ARKANSAS
.
.
CODE = WYOMING


These statements begin a request to generate a report in order by state:
BEGIN
FIND.TYPE: FIND ALL RECORDS FOR WHICH
TYPE = STATE
END FIND
FOR EACH RECORD IN FIND.TYPE
EACH.CODE: FOR EACH OCCURRENCE OF CODE
FIND.STATE: FIND ALL RECORDS FOR WHICH
STATE = VALUE IN EACH.CODE
END FIND
FOR EACH RECORD IN FIND.STATE
.
.


This method has the advantage of eliminating the internal sort required by FOR EACH VALUE IN ORDER and provides an easy way to simulate a FOR EACH VALUE loop for a field that does not have the FRV or ORDERED attribute. However, a change in the list of values can require a recreation of the TYPE record to keep the values in order. Recreation is not required if the UPDATE IN PLACE field attribute has been specified for the CODE field and if the new and old values occupy the same place in order. Recreation also is not required if the [[#INSERT statement|INSERT statement]] is used correctly. 

====VALUE IN with FOR EACH OCCURRENCE loops====

VALUE IN references to FOR EACH OCCURRENCE (FEO) statements from outside the FEO loop does not compile. Such references receive the following error message:
M204.0311 UNACCEPTABLE STATEMENT REFERENCE


At runtime, the space occupied in STBL by the FEO value is reclaimed after each iteration of the FEO loop (including the last). This results in a reduction in the runtime STBL space requirements of some programs that use FEO.

To avoid getting that error, move the value into a %variable inside the FEO loop, and then reference the %variable outside the FEO loop.

====FOR EACH OCCURRENCE against INVISIBLE fields====

Using FOR EACH OCCURRENCE (FEO) syntax against INVISIBLE fields is a waste of processing time. An FEO causes a scan of the current Table B record, but INVISIBLE fields are not stored in Table B, so an FEO against an INVISIBLE field can never find any occurrences. Prior to V4R2.0 this programming flaw was masked because using FEO syntax against an INVISIBLE field compiled and evaluated successfully, although it never found occurrences. 

Beginning in V4R2.0, FEO syntax against an INVISIBLE field results in compilation error:
M204.0320 Field is invisible. Field = fieldname


===Deleting occurrences of fields and field groups===

The DELETE EACH statement can be used to delete all occurrences. 

Note: You must take care when deleting occurrences of a field or fieldgroup using the FOR EACH OCCURRENCE loop. When used to delete occurrences, and without a numbered occurrence reference on the field name, the first 50% of occurrences of a multiply occurring field are deleted. If there are an odd number of occurrences of the field on the record, the first half, up to and including the middle occurrence, are deleted.

====Example====
Suppose the following statement is specified for the <code>RICHARD SMITH</code> record described previously:
 for each occurrence in fd.rec
del.child: for each occurrence of child
delete child
end for
end for


The record originally contained these <code>CHILD</code> entries:
CHILD=HENRY
CHILD=SALLY
CHILD=JANE


On the first pass through the loop, the first value, <code>HENRY</code>, is selected and deleted. At the end of the first pass, the record contains these <code>CHILD</code> entries:
CHILD=SALLY
CHILD=JANE


On the second pass through the loop, the <code>DELETE CHILD</code> statement again deletes the first occurrence of the field as described in [[#DELETE statement|DELETE statement]]. Since <code>HENRY</code> has already been deleted, <var class="product">Model 204</var> deletes the first entry, <code>SALLY</code>.

After the second pass, the <var>FOR EACH OCCURRENCE</var> loop terminates. This is because the value in <code>DEL.CHILD</code> should be the next (third) occurrence, but after two passes, only one occurrence remains on the record. Therefore, at the end of the <var>FOR EACH OCCURRENCE</var> loop, the remaining value in the <code>CHILD</code> field is:
CHILD=JANE

Note: In general, it is a mistake to reference a multiply occurring field in an <var>FEO</var> loop without using an occurrence subscript. An unsubscripted reference always refers to the first occurrence of a field.

====Example 2====
Now suppose an occurrence reference is added to the field in the <var>FEO</var> loop:
 for each record in fd.rec
del.child: for each occurrence of child
delete child(occurrence in del.child)
end for
end for


The above will result in every other occurrence being deleted, because the occurrence reference continues to increment upward while the list of occurrences is also shifted, so the second time through the loop, the occurrence pointer is pointing to the item that was formerly the third item, then the fifth item, then the seventh item. Again, this is generally not what the programmer intends.

The solution is either:
<ul>
<li>Use the <var>DELETE EACH</var> syntax.</li>

<li>Loop over the occurrences in reverse order. </li>
</ul>

There is no specific syntax for reversing the order of an <var>FEO</var> loop, so you must count the occurrences and step backward through them in an index loop, like this:
childCount: -
count occurrences of child
for each record in %myRecordSet
for %x from count in childCount to 1 by -1
delete child(%x)
end for
end for


Stepping backward through a set is also the standard practice in <var>StringList</var> and <var>NamedArrayList</var> objects, when deletions may occur. This technique is especially worth keeping in mind in situations where only some occurrences may be deleted.

When using field groups, the <var>FOR ALL OCCURRENCES</var> syntax, introduced with Model 204 V7.5, performs as expected.

====Deleting with an FEO FIELDGROUP versus FAO FIELDGROUP loop====
An <var>FEO FIELDGROUP</var> statement on field groups has the same semantics as an <var>FEO</var> statement on a single field. When you iterate in an <var>FEO FIELDGROUP</var> or <var>FEO</var> loop, the next occurrence processed is the occurrence number one greater than the one processed before, whether or not it is one you have already processed (because of insertions) or whether or not you skip one or more (because of deletions). For example:
<ul>
<li>Following the standard behavior for moving forward through a set of occurrences in an <var>FEO</var> loop, <var>FEO FIELDGROUP</var> deletes every other occurrence of the field group:
xon: -
feo fieldgroup vehicle
delete fieldgroup(occurrence in xon)
end for

This behavior is a historical anomaly, but it is maintained for backward compatibility purposes. </li>

<li>To delete all occurrences of a field group, use an <var>FAO FIELDGROUP</var> statement:
fao fieldgroup vehicle
delete fieldgroup
end for
</li>
</ul>

===FOR FIELDGROUP statement===
The FOR FIELDGROUP statement operates on a specific occurrence of a field group. The occurrence is indicated by either an occurrence number or a field group ID number.

====Syntax====
The format of the statement is:
FOR FIELDGROUP (fgname | %%varFgname) { (occurrence-number) | = fieldgroupID }

Where:
<ul>
<li><var class="term">fgname</var> specifies a field group name. </li>

<li>%%<var class="term">varGrp</var> specifies a field group name variable. </li>

<li><var class="term">occurrence-number</var> specifies an occurrence within that field group. The occurrence number must be enclosed in parentheses.

The <var>[[$FIELDGROUPOCCURRENCE]]</var> function returns the field group occurrence value. </li>

<li><var class="term">fieldgroupID</var> specifies a field group ID, which is unique for a record. A field group ID is assigned when a field group is added to the record, is equal to one more than the highest field group ID that has been assigned in the record, and is not reused if its field group is deleted.

<var class="term">fieldgroupID</var> must be preceded by an equal sign. 

The <var>[[$FieldgroupId]]</var> function returns the field group ID. </li>
</ul>

====Examples====
This <var>FOR FIELDGROUP</var> statement sets the third occurrence of the <code>DRIVER</code> field group as the context for the <var>Print</var> statement:
FR Where ...
For Fieldgroup DRIVER (3)
Print DRIVER_ID
End For
End For 

This <var>FOR FIELDGROUP</var> statement uses a [[Using variables and values in computation#Field name variables|field name variable]] to set the <code>DRIVER</code> field group that has ID <var class="term">%fgid</var> as the context for the <var>Print</var> statement: 
FR Where ...
%driver = 'DRIVER'
For Fieldgroup %%driver = %fgid
Print DRIVER_ID And DRIVER_NAME
End For
End For


==Setting field group context==
To access data in a field group, first establish the record context using the
<var>FOR EACH RECORD</var> (<var>FR</var>) or <var>FOR RECORD NUMBER</var> (<var>FRN</var>) statement. Then to access the occurrences of the field group, you typically use an <var>FAO FIELDGROUP</var> or <var>FEO FIELDGROUP</var> loop.

===Using a FOR ALL OCCURRENCES OF loop===
You can set field group context with an <var>FAO</var> loop. For example:
BEGIN
IN POLICIES FOR EACH RECORD
FAO: FAO FIELDGROUP VEHICLE
IF COLOR IS LIKE '*RED*' THEN
PRINT 'POLICY:' AT 5 AND POLICY_NUMBER AND -
'COLOR=' WITH COLOR
%RED = %RED + 1
END IF
END FOR
END FOR
PRINT 'NUMBER OF RED CARS:' AND %RED
END

The result is:
 POLICY: 100001 COLOR=VICTORY RED
POLICY: 100007 COLOR=RED
POLICY: 100011 COLOR=VICTORY RED
...
NUMBER OF RED CARS: 214

...and so on...


===Using a FOR EACH OCCURRENCE loop===
An <var>FEO</var> loop on a field group establishes a field group context. Inside the loop, references to field group fields are to their occurrences in their field group. For example:
BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
FEO: FEO FIELDGROUP VEHICLE
%DRIVER_ID = OTHER_DRIVER
PRINT OCCURRENCE IN FEO AND MAKE AND MODEL AND -
'OTHER DRIVER(S):' AT 30 AND EACH OTHER_DRIVER
PRINT 'FIRST:' AT 30 AND %DRIVER_ID AND -
'THIRD:' AND OTHER_DRIVER(3)
END FOR
END FOR
END 

The result is:
1 AUDI A4 QUATTRO OTHER DRIVER(S): 100035 100037 100036
FIRST: 100035 THIRD: 100036
2 CADILLAC SEVILLE OTHER DRIVER(S):
FIRST: THIRD:


An important difference between an <var>FAO FIELDGROUP</var> statement and an <var>FEO
FIELDGROUP</var> statement is that the <var>FAO FIELDGROUP</var> statement collects the
field group IDs for all occurrences, then processes against that list. Because of
this, it is less affected by insertions or deletions of occurrences of field groups
within the loop. Deleting the current occurrence within the
loop, for example, will not affect occurrences referenced in subsequent iterations.
For further discussion of this, see [[#FEO loops and field group context|FEO loops and field group context]], below. 

===Using a FOR FIELDGROUP block===
You can use a field group occurrence established by a [[#FOR FIELDGROUP statement|FOR FIELDGROUP block]] as the context for references to its members.

For example, the following <var>PAFGI</var> (<var>PRINT ALL FIELD GROUP INFORMATION</var>) statement outputs the contents of only the third occurrence of field group <code>GRP</code>:
IN FILE WHATEVER FRN %RECNO
FOR FIELDGROUP GRP(3)
PRINT ’*** Third occurrence of field group GRP’
PAFGI
END FOR
END FOR 

===Accessing field group members while not in field group context===
You can access field group occurrences by using the occurrence number
directly in the FR loop, if the field is [[Field design#AT-MOST-ONE, REPEATABLE, and EXACTLY-ONE attributes|EXACTLY-ONE or AT-MOST-ONE]]. So, instead of using this <var>FEO FIELDGROUP</var> loop to print the <code>MAKE</code> and <code>MODEL</code> for the three vehicles in the <code>VEHICLE</code> field group:
BEGIN
FR WHERE POLICY_NUMBER = 100095
FEO FIELDGROUP VEHICLE
PRINT MAKE AND MODEL
END FOR
END FOR
END


Output: 
VOLKSWAGEN NEW BEETLE
MITSUBISHI ECLIPSE
CHEVROLET SUBURBAN 

You can also access the <code>MAKE</code> and <code>MODEL</code> (<var>EXACTLY-ONE</var>) fields directly within the <var>FR</var> loop by using occurrence numbers: 
BEGIN
FR WHERE POLICY_NUMBER = 100095
PRINT MAKE AND MODEL
PRINT MAKE(2) AND MODEL(2)
PRINT MAKE(3) AND MODEL(3)
END FOR
END 

Output: 
VOLKSWAGEN NEW BEETLE
MITSUBISHI SUBURBAN
CHEVROLET SUBURBAN 
Note:
If <code>MAKE</code> and <code>MODEL</code> are <var>REPEATABLE</var> fields or defined to all field groups (<code>FIELDGROUP *</code>), attempting to access them with just an <var>FR</var> loop will fail. 

===Missing data in field groups===
As with non-field group field references for missing occurrences, the field values are returned as null (see the reference to <code>OTHER_DRIVER(3)</code> in the preceding example). The exception is <var>EXACTLY-ONE</var> fields in field groups, where the field's default value is returned for missing occurrences.

===Handling nested field group context===
If field groups are nested, you can always retrieve an <var>EXACTLY-ONE</var> field in a field group inside the current context without establishing that nested field group's context.
<var>EXACTLY-ONE</var> fields in specific field groups (as opposed to fields defined with <code>FIELDGROUP *</code> that belong to all field groups) can be retrieved outside the field group context.
In the following example, <code>CLAIM-NUMBER</code> is an <var>EXACTLY-ONE</var> field in field group <code>CLAIM</code> which is nested within field group <code>VEHICLE</code>:

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100095
PRINT POLICY_NUMBER
FEO FIELDGROUP VEHICLE
PRINT MAKE AT 5 AND MODEL
PRINT '1)' AND CLAIM_NUMBER
PRINT '2)' AND CLAIM_NUMBER(2)
PRINT '3)' AND CLAIM_NUMBER(3)
END FOR
END FOR
END 

The result is: 
100095
VOLKSWAGEN NEW BEETLE
1)
2)
3)
MITSUBISHI ECLIPSE
1) 100059
2) 100064
3)
CHEVROLET SUBURBAN
1)
2)
3)


===Updating fields in a field group===

<var>EXACTLY-ONE</var> fields cannot be <var>ADD</var>ed, <var>INSERT</var>ed or <var>DELETE</var>d. You can only <var>CHANGE</var> them.

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
FEO FIELDGROUP VEHICLE
ADD MAKE = 'XXX'
INSERT MAKE(1) = %NOTHING
DELETE MAKE
CHANGE COLOR(4) TO 'YYYY'
END FOR
END 

The result is: 
<nowiki>*** 1 M204.2853: ADD NOT ALLOWED FOR EXACTLY-ONE FIELD
== 'XXX'
*** 2 M204.0228: PART OF STATEMENT IGNORED
*** 3 M204.2853: INSERT NOT ALLOWED FOR EXACTLY-ONE
FIELD
== %NOTHING
*** 4 M204.0228: PART OF STATEMENT IGNORED
*** 5 M204.2853: DELETE NOT ALLOWED FOR EXACTLY-ONE
FIELD
*** M204.1042: COMPILATION ERRORS
</nowiki>


===Handling invalid occurrence numbers===
The following <code>PRINT MAKE(3)</code> statement prints a null and without error, even if <code>MAKE</code> was defined as <var>EXACTLY-ONE</var>. This is consistent with Model 204 behavior for non-field group <var>EXACTLY-ONE</var> and <var>OCCURS</var> fields. That is, you can request occurrence 4 of an <var>EXACTLY-ONE</var> or <var>OCCURS 1</var> field in the record, and Model 204 returns a null. Model 204 ignores invalid occurrence numbers such as negative numbers or 0. 0 is treated the same as 1.

In the following example, <code>MAKE</code> and <code>MODEL</code> are <var>EXACTLY-ONE</var> fields:

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
PRINT '1' AND MAKE AND MODEL
PRINT '2' AND MAKE(2) AND MODEL(2)
PRINT '3' AND MAKE(3) AND MODEL(3)
END FOR
END 
The result is:
1 AUDI A4 QUATTRO
2 CADILLAC SEVILLE
3



In addition to retrieving field values inside an <var>FEO FIELDGROUP</var> loop, fields in that field group can be updated, that is, added, inserted, changed, and deleted: 
BEGIN

%GLASSES IS STRING LEN 50
%GLASSES = 'CORRECTIVE LENSES REQUIRED'

IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
FEO FIELDGROUP DRIVER
PRINT 'BEFORE ..'
PAFGI
ADD DRIVER_RESTRICTIONS = 'MEDICAL RESTRICTIONS PRESENT'
INSERT DRIVER_RESTRICTIONS(3) = %GLASSES
DELETE DRIVER_RESTRICTIONS(4)
CHANGE DRIVER_MARITAL_STATUS TO 'WIDOWED'
PRINT 'AFTER ...'
PAFGI
END FOR
END 

The result is:
BEFORE ..
\DRIVER = 1
DRIVER_ID = 100034
DRIVER_NAME = CUMMINGS, BETTY S
DRIVER_MARITAL_STATUS = SINGLE
DRIVER_GENDER = F
DRIVER_DATE_OF_BIRTH = 19791225
/DRIVER = 1
AFTER ...
\DRIVER = 1
DRIVER_ID = 100034
DRIVER_NAME = CUMMINGS, BETTY S
DRIVER_MARITAL_STATUS = WIDOWED
DRIVER_GENDER = F
DRIVER_DATE_OF_BIRTH = 19791225
DRIVER_RESTRICTIONS = MEDICAL RESTRICTIONS PRESENT
DRIVER_RESTRICTIONS = CORRECTIVE LENSES REQUIRED
/DRIVER = 1
BEFORE ..
\DRIVER = 2


==Constraint violations for field groups==
For <var>ADD</var>, <var>INSERT</var>, and <var>DELETE</var> statements, you can get an <var>EXACTLY-ONE</var> constraint violation, as well as other field constraint violations. In the previous example, had you attempted to add, insert, or delete the field <code>DRIVER_ID</code>, you would have received the following error message:
M204.2853: (ADD/DELETE/INSERT) NOT ALLOWED FOR EXACTLY-ONE FIELD

In general, the behavior of updating statements mimics the Model 204 handling of exception cases. For example, a <var>DELETE</var> of an occurrence that is not there is ignored. A <var>CHANGE</var> statement for an absent occurrence becomes an <var>ADD</var> statement.

==Referencing fields in nested field groups==
You can reference a field from the containing context even inside a field group context. For example:
BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
FEO FIELDGROUP DRIVER
PRINT POLICY_NUMBER AND DRIVER_NAME
END FOR
END

100013 CUMMINGS, BETTY S
100013 CUMMINGS, EDDIE R
100013 CUMMINGS, LEE V
100013 CUMMINGS, MARY U
100013 CUMMINGS, ROBERT T


See the discussion in the next section regarding the oddities of <var>DELETE</var> processing with <var>FEO</var> loops.

==FEO loops and field group context==
On each iteration of a field group <var>FEO</var> loop, the current field group is set as the field group context. If that field group is deleted and a field in that field group is referenced you get a request canceling error.

<var>FEO</var> on field groups has the same semantics as those on a single field. When you iterate in an <var>FEO FIELDGROUP</var>, the next occurrence processed is the occurrence number one greater than the one processed before, whether or not it is one you have already processed (because of insertions) or whether or not you skip one or more (because of deletions).

The problem with deleting repeating fields, or field groups, in order in an FEO loop is that the internal pointer is updated after each deletion, resulting in a default behavior of deleting every other occurrence of the repeating field or field group, which can also cause an error when the final deletion is attempted and the pointer is now set to a value larger than the final occurrence:
BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
FEO FIELDGROUP DRIVER
PRINT POLICY_NUMBER AND DRIVER_NAME
END FOR
END

100013 CUMMINGS, BETTY S
100013 CUMMINGS, EDDIE R
100013 CUMMINGS, LEE V
100013 CUMMINGS, MARY U
100013 CUMMINGS, ROBERT T

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
PRINT POLICY_NUMBER
PRINT 'BEFORE...'
FEO FIELDGROUP DRIVER
PRINT DRIVER_NAME AT 5
END FOR
FEO FIELDGROUP DRIVER
DELETE FIELDGROUP
END FOR
PRINT 'AFTER....'
FEO FIELDGROUP DRIVER
PRINT DRIVER_NAME AT 5
END FOR
END

100013
BEFORE...
CUMMINGS, BETTY S
CUMMINGS, EDDIE R
CUMMINGS, LEE V
CUMMINGS, MARY U
CUMMINGS, ROBERT T
AFTER....
CUMMINGS, EDDIE R
CUMMINGS, MARY U


The intent of the above code is clearly to delete every occurrence of the field group, not every other occurrence, but this anomalous result is maintained as part of SOUL for backward compatibility reasons. The three approaches to deleting all occurrences are:
<ul>
<li>Use the <var>DELETE EACH</var> syntax.</li>
<li>Loop backward through the set of occurrences in an index loop.</li>
<li>Use <var>FOR ALL OCCURRENCES</var> (<var>FAO</var>), introduced in Model 204 version 7.5. </li>
</ul>

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100013
PRINT POLICY_NUMBER
PRINT 'BEFORE...'
FAO FIELDGROUP DRIVER
PRINT DRIVER_NAME AT 5
END FOR
FAO FIELDGROUP DRIVER
DELETE FIELDGROUP
END FOR
PRINT 'AFTER....'
FAO FIELDGROUP DRIVER
PRINT DRIVER_NAME AT 5
END FOR
END

100013
BEFORE...
CUMMINGS, BETTY S
CUMMINGS, EDDIE R
CUMMINGS, LEE V
CUMMINGS, MARY U
CUMMINGS, ROBERT T
AFTER....

BEGIN
IN POLICIES FOR EACH RECORD WHERE POLICY_NUMBER = 100095
PRINT '...BEFORE...'
FAO FIELDGROUP VEHICLE
PRINT MAKE AND MODEL
END FOR
PRINT 'ADD A HONDA PILOT ...'
ADD FIELDGROUP VEHICLE
MAKE = HONDA
MODEL = PILOT
* ... OTHER VEHICLE FIELDS
END ADD
PRINT '...AFTER....'
FAO FIELDGROUP VEHICLE
PRINT MAKE AND MODEL
END FOR
END

...BEFORE...
VOLKSWAGEN NEW BEETLE
MITSUBISHI ECLIPSE
CHEVROLET SUBURBAN

ADD A HONDA PILOT ...
...AFTER....
VOLKSWAGEN NEW BEETLE
MITSUBISHI ECLIPSE
CHEVROLET SUBURBAN
HONDA PILOT


==UPDATE field attribute==

===Impact of changing a value===

When the user changes the value of a field, how <var class="product">Model 204</var> changes the occurrence depends upon whether the field was defined with the <var>UPDATE IN PLACE</var> or <var>UPDATE AT END</var> attribute, as follows:
<table>
<tr class="head">
<th>Attribute </th>
<th>How the update works...</th>
</tr>

<tr>
<td><var>UPDATE IN PLACE</var> (the default) </td>
<td>The value of the field occurrence is changed but its position in the record is preserved. To change the order of values, the user must delete the old value and add the new one in separate statements. </td>
</tr>

<tr>
<td><var>UPDATE AT END</var> </td>
<td>The existing occurrence is deleted and the new one is automatically added at the end. <var>UPDATE AT END</var> is normally specified for applications that depend on value rotation to accomplish aging. </td>
</tr>
</table>

====Example====

This example includes both approaches to updating. Suppose a record has the following fields:
NAME = RICHARD SMITH
CHILD = HENRY
CHILD = SALLY
CHILD = JANE


You could use the technique illustrated below to add a last name to each child. (This technique involves the use of %variables, which are discussed in [[Using variables and values in computation]].)
BEGIN
FIND.RECS: FIND ALL RECORDS FOR WHICH
NAME = RICHARD SMITH
END FIND
FOR EACH RECORD IN FIND.RECS
EACH.CHILD FOR EACH OCCURRENCE OF CHILD
%A = VALUE IN EACH.CHILD WITH ' SMITH'
CHANGE CHILD = VALUE IN EACH.CHILD TO %A
END FOR
END FOR
END


===If the UPDATE IN PLACE option is specified===

If the <var>UPDATE IN PLACE</var> option has been specified for the <code>CHILD</code> field, then the <var>FOR EACH OCCURRENCE</var> loop change each occurrence of <code>CHILD</code> in turn. 

On the first pass through the loop, the first value, <code>HENRY</code>, is selected and changed to <code>HENRY SMITH</code>. After the first pass, the record looks like this:
NAME = RICHARD SMITH
CHILD = HENRY SMITH
CHILD = SALLY
CHILD = JANE


At the end of the second pass, SALLY is changed:
NAME = RICHARD SMITH
CHILD = HENRY SMITH
CHILD = SALLY SMITH
CHILD = JANE


At the end of the third pass, JANE is changed:
NAME = RICHARD SMITH
CHILD = HENRY SMITH
CHILD = SALLY SMITH
CHILD = JANE SMITH


===If the UPDATE AT END option is specified===

If the <var>UPDATE AT END</var> option has been specified for the <code>CHILD</code> field, the <var>FOR EACH OCCURRENCE</var> loop proceeds as described here.

On the first pass through the <var>FOR EACH OCCURRENCE</var> loop the first value, <code>HENRY</code>, is selected and changed to <code>HENRY SMITH</code>. The act of changing, however, causes the value <code>HENRY</code> to be deleted and the value <code>HENRY SMITH</code> to be added as the last child. Thus after the first pass, the record looks like this:
NAME = RICHARD SMITH
CHILD = SALLY
CHILD = JANE
CHILD = HENRY SMITH


On the second pass through the loop, <code>JANE</code>, which is now the second occurrence of <code>CHILD</code>, is deleted and <code>JANE SMITH</code> is added to the end of the record:
NAME = RICHARD SMITH
CHILD = SALLY
CHILD = HENRY SMITH
CHILD = JANE SMITH


On the third pass, the third occurrence is <code>JANE SMITH</code>, and the record ends with:
NAME = RICHARD SMITH
CHILD = SALLY
CHILD = HENRY SMITH
CHILD = JANE SMITH


==Subscripts==

Subscripts can be included in <var class="product">Model 204</var> field references to facilitate the selection of particular occurrences of multiply occurring fields. Any field name can be followed by a parenthesized expression. The value of this expression is used as an ordinal number which specifies the desired occurrence of the named field. For example: 
INCIDENT(3)
COURSE.NUMBER(2)
TRANSACTION(A+B)


====Example====

This request illustrates a class schedule where subscripts are used to change the room number for a course:
BEGIN
COURSE: FIND ALL RECORDS FOR WHICH
REC = ROOM ASSIGNMENT
END FIND
CHANGE: FOR EACH RECORD IN COURSE
IF ROOM(1) EQ '214A' THEN
CHANGE ROOM(1) TO '566A'
END IF
IF ROOM(2) EQ '214A' THEN
CHANGE ROOM(2) TO '566A'
END IF
END FOR
END


===Subscripted field extraction===

Subscripted field references attempt to maintain their position inside a record much as an FEO loop attempts to maintain its position inside a record. This means that subscripted field references tend to be as efficient as FEO loops. 

The following is an example of using subscripted field extraction for a field that is a member of a field group. An <var>FEO</var> loop populates two arrays with the corresponding values of group members <code>INCIDENT</code> and <code>INCIDENT_DATE</code>:
%inc is string array (12) no fs
%idate is string array (12) no fs
FeoIdata:
feo INCIDENT
%inc(occurence in FeoIdata) = value in FeoIdata
%idate(occurence in FeoIdata) = INCIDENT_DATE(occurence in FeoIdata)
end for


If you use multiple <var>FEO</var> loops for field group processing, it is possible that using this technique will require additional VTBL resources for procedures with an extremely large number of sorts or subscripted field references.

===Evaluation of subscript expressions===

The evaluation of subscript expressions is subject to the rules for determining an integer result for an arithmetic expression as described in [[Using variables and values in computation#Arithmetic operations|Arithmetic operations]]. 

===Statements and phrases with which you cannot use subscripts===

Subscripted field references can appear anywhere that unsubscripted references can, except in the following statements and phrases:
<table>
<tr class="head">
<th>Statements you cannot use with subscripts </th>
<th>
Because...</th>
</tr>

<tr>
<td><var>ADD</var> </td>
<td>Adds a new occurrence of a field. </td>
</tr>

<tr>
<td><var>BY EACH phrase</var> in the <var>SORT RECORDS</var> </td>
<td>Loops through all occurrences of a field. </td>
</tr>

<tr>
<td><var>DELETE EACH statement</var> </td>
<td>Loops through all occurrences of a field. </td>
</tr>

<tr>
<td><var>EACH phrase</var> in a <var>PRINT</var> specification</td>
<td>Loops through all occurrences of a field. </td>
</tr>

<tr>
<td><var>FILE</var> </td>
<td>Deals with fields having the INVISIBLE attribute, which cannot be the object of subscripted references. </td>
</tr>

<tr>
<td><var>FIND</var></td>
<td>Locates records without regard to which occurrence of a field contains the desired value. </td>
</tr>

<tr>
<td><var>FOR EACH OCCURRENCE</var></td>
<td>Loops through all occurrences of a field. Field references within FOR EACH OCCURRENCE loops can be subscripted, depending upon the individual statements in which the references appear. </td>
</tr>

<tr>
<td><var>FOR EACH VALUE</var> </td>
<td>Loops through all values of all occurrences of the specified field. Field references within FOR EACH VALUE loops are not allowed at all, unless the field reference is embedded in a nested FOR EACH RECORD loop. See [[Value loops#Setting up a value loop on one field and printing a value of another|Setting up a value loop on one field and printing a value of another]] for more information.</td>
</tr>

<tr>
<td><var>IN ORDER BY EACH phrase</var> in the <var>FOR EACH RECORD </var></td>
<td>Loops through all occurrences of a field. </td>
</tr>

<tr>
<td><var>PRINT n </var></td>
<td>Loops through all occurrences of a field. </td>
</tr>

<tr>
<td><var>STORE RECORD</var></td>
<td>Adds fields in the order of appearance in the statement. </td>
</tr>
</table>

===Unsubscripted field references===

An unsubscripted field reference in a context in which subscripted references are allowed is always equivalent to a subscripted reference with a value of one.

===Do not use subscripts with INVISIBLE fields===

You cannot make subscripted references to fields that have the <var>INVISIBLE</var> attribute (see the discussion on field attributes in [[Field attributes]]). These fields are not truly multiply occurring, although they can have several different values in a single record. A subscript specified for a field with the <var>INVISIBLE</var> attribute is ignored. 

==Subscript validity rules==

The rules presented below indicate whether or not a subscript value is valid and what action to take if the value is not valid. These rules take into account: 
<ul>
<li>The value of the subscript</li>
<li>The context in which the subscript appears</li>
<li>The description of the subscripted field </li>
</ul>

===Explanation of the rules===

In these rules, two quantities are used:
<ol>
<li>N is the maximum number of occurrences that can be stored in a record for a given field. For a preallocated field, N equals the value of <var class="term">n</var> in the <var>OCCURS</var> clause of the field's description. For other fields, N has no limit. </li>

<li>P is the number of nonempty occurrences of the referenced field found in the specified record when the reference is evaluated. </li>
</ol>

For a summary of rules for preallocated fields, refer to the discussion on preallocated fields in [[Data maintenance#Storing values in preallocated fields|Storing values in preallocated fields]]. 

===INSERT statement===

The <var>INSERT</var> statement, like the <var>ADD</var> statement, is used for adding new occurrences of a field. <var>INSERT</var> is used to add occurrences when the order of the values is important and the values are added out of order. 

The <var>INSERT</var> statement is supported in remote file and scattered group contexts. The <var>INSERT</var> statement is not supported for Large Object fields.

====Syntax====

The format of the <var>INSERT</var> statement is:
INSERT fieldname [(subscript)] = value


====Example====

Assume a record with these fields:
DEPT = PERSONNEL
DEPT = FINANCE
DEPT = MARKETING


The following statement:
INSERT DEPT(3) = ACCOUNTING


results in this record:
DEPT = PERSONNEL
DEPT = FINANCE
DEPT = ACCOUNTING
DEPT = MARKETING


====Subscript validity rules====

[[#INSERT statement|INSERT statement]] lists validity rules for subscripts. In this table:
<ul>
<li>P is the number of occurrences of the field in the record when the <var>INSERT</var> statement is issued. </li>

<li>S is the subscript specified in the <var>INSERT</var> statement.
<table>
<caption>Subscript validation rules</caption>
<tr class="head">
<th>If P and S values are: </th>
<th>
Then <var class="product">Model 204</var> takes this action:</th>
</tr>

<tr>
<td>P > S</td>
<td>Inserts the new occurrence in front of the former Sth occurrence; the new occurrence becomes the current Sth occurrence of the field.</td>
</tr>

<tr>
<td>P < S</td>
<td>Inserts the new occurrence of the field after the Pth occurrence; the new occurrence becomes the (P+1) occurrence.</td>
</tr>

<tr>
<td>P = 0</td>
<td>Adds the new value at the end of the record, as in the <var>ADD</var> statement.</td>
</tr>

<tr>
<td>S = 0, or no subscript</td>
<td>Treats the new value as if S = 1 and inserts the new value as the first occurrence, in front of any former occurrence of the field.</td>
</tr>

<tr>
<td>S < 0</td>
<td>Does not add a new occurrence.</td>
</tr>
</table>
</li>
</ul>

For fields with the <var>INVISIBLE</var> attribute, only the index is affected. 

===PRINT statement===

In retrieval statements such as <var>PRINT</var>, subscript values less than zero or greater than P are invalid. Invalid references of this kind cause the null value to be returned. A subscript of zero returns the value of the first occurrence. 

===DELETE statement===

In the <var>DELETE</var> statement, subscript values less than one or greater than P are invalid. If an invalid reference of this kind is made, no action is taken. 

If several occurrences of a field are being deleted, you should be careful not to use DELETE in the following way: 
FOR EACH RECORD IN FIND.RECS
DELETE CLIENT(1)
DELETE CLIENT(2)
DELETE CLIENT(3)
END FOR


As the statements are executed, <var class="product">Model 204</var> deletes the first occurrence, <code>CLIENT(1)</code>, then locates the current second occurrence, which is the original <code>CLIENT(3)</code>, and deletes it. Then, because a third occurrence cannot be found, the operation stops, and the original <code>CLIENT(2)</code> is never deleted.

In such a situation, deleting the occurrences in the reverse order achieves the desired result:
FOR EACH RECORD IN FIND.RECS
DELETE CLIENT(3)
DELETE CLIENT(2)
DELETE CLIENT(1)
END FOR


The desired result also can be achieved by completely omitting the subscripts, as follows:
FOR EACH RECORD IN FIND.RECS
DELETE CLIENT
DELETE CLIENT
DELETE CLIENT
END FOR


===CHANGE statement===

In the <var>CHANGE</var> statement, subscript values less than one or greater than P are treated as attempts to add a new occurrence (P+1). If (P+1) does not exceed N (the maximum number of occurrences that can be stored), the new occurrence is added to the record. If (P+1) does exceed N, the request is cancelled. 

===SORT RECORDS statement===

The use of subscripts in references to the recordset yielded by a
<var>SORT RECORDS</var> statement sometimes can produce unexpected results.
If the <var>BY EACH</var> option appears in a <var>SORT</var> statement, records in which the <var>BY EACH</var> field is multiply occurring are copied several times (once for each field occurrence) to the system scratch file CCATEMP.
In each copy, the occurrences of the <var>BY EACH</var> field are rotated, so that the occurrence used as the sort key appears first. Therefore, a subscripted reference to this field can yield different values for different copies of the record. 

</div> 

[[Category:SOUL]]

Obsolete features

2014-08-01T13:40:23Z

Mlarocca:

===Statement numbers===
This appendix describes certain features of User Language which, while still supported, are generally considered obsolete. They have been superseded by other, more efficient features or techniques. Rocket Software does not recommend using these features in newly written requests and procedures.
Rocket Software strongly recommends that you use statement labels (see [[Request composition rules#Statement labels|Statement labels]]) rather than statement numbers. Although statement numbers are still supported, this section is included primarily as documentation for applications developed using earlier releases of <var class="product">Model 204</var>.
====FOPT parameter====
The setting of the FOPT (File Options) parameter determines whether procedures within a file must be labeled or numbered. For more information on the FOPT parameter, refer to the Rocket <var class="product">Model 204</var> Parameter and Command Reference Manual. 
====Rules for using statement numbers====
The rules for specifying statement numbers in User Language statements are summarized below.
<ul>
<li>A statement number is made up of the digits 0-9 and an optional period (.). The number must begin with a digit and cannot contain blanks, although blanks preceding or following it are optional. </li>
</li>
<li>A statement number can start in any column up to but not including column INCCC.</li>
</li>
<li>Any statement can be numbered, but some statements must be numbered. In particular, a statement must be numbered if:</li>
</li>
</ul>
It immediately follows a STORE RECORD or a FIND statement, in which case the statement number indicates the end of the preceding statement.
It is referred to by later statements. In most requests, COUNT RECORDS IN n, COUNT RECORD ON LIST m, NOTE, FIND, FOR EACH VALUE, and FOR EACH OCCURRENCE are referred to later and should therefore be numbered.
It is the first statement after a loop, in which case a number is needed to indicate the end of the loop. An END statement following a loop does not require a number.
It is the statement following a THEN or ELSE clause which is to be executed if the condition is false.
<ul>
<li>The retrieval conditions of a FIND statement, the subexpressions of an IF statement, and the fields of a STORE RECORD statement must not be numbered, even if they start new lines. </li>
</li>
<li>A statement number can have any number of parts, which are delimited by periods. Thus, 2.3 and 0.1 are two part numbers, and 0.05.4 is a three part number. </li>
</li>
<li>A period (.) following a statement number is optional, but the periods separating the parts are required. </li>
For example:
1.1

and
1.1.

are both legal and are interpreted as the same number. 
This rule also applies when referring to statements by number. Thus:
FOR EACH RECORD IN 1.

and
FOR EACH RECORD IN 1

refer to the same statement. 
</li>
<li>Any part of a statement number can be arbitrarily large. </li>
</li>
<li>The number of parts in a statement number must be the same as the level on which the statement is nested. For example, the following sequence is illegal because 2.1.1 has three parts but is nested at the second level:</li>
2. FOR EACH RECORD IN 1
2.1.1 PRINT ALL INFORMATION
</li>
<li>If a statement is not numbered, it is assigned a default level of nesting. The default level is the same as the level of the previous statement. If there is no previous statement, the default is the first level. If the previous statement starts a loop or a THEN, ELSE, or ELSEIF clause, or is a SUBROUTINE statement, the default level is one greater than the level of the previous statement. </li>
</li>
<li>Any part of a statement number can have leading zeros. However, a number with leading zeros is not equivalent to one without. Thus 01 and 1 are both legal but not equivalent; the same is true of 1.1 and 1.01. </li>
</li>
<li>Statements need not be numbered in sequential order. The statement number is just a label for the statement; its numerical value has no significance. </li>
The following, for instance, is a legal request:
BEGIN
3. FIND ALL RECORDS FOR WHICH
COMPANY = ROCKET
1. FOR EACH RECORD IN 3.
3.1 PRINT ALL INFORMATION
2.6. SKIP 1 LINE
END
</li>
<li>Within a request, statement numbers should be unique. If not, <var class="product">Model 204</var> prints the message:</li>
M204.0223: STATEMENT LABEL MULTIPLY DEFINED

This is a warning message; the request can still be run. 
</li>
<li>A statement number followed by a label is allowed with or without a space between the number and the label. If a statement number is followed by a label and there is no space between them, User Language separates them into statement number and label. Although a statement number can be followed by a label, it is strongly recommended that you avoid placing statement numbers and labels on the same line. </li>
</li>
</ul>
Examples
The following request addresses an automated library card catalogue. Each record in the file contains information that would normally appear on a single card in the catalogue, such as AUTHOR, TITLE, SUBJECT, and CATALOGUE NUMBER.
BEGIN
1. FIND ALL RECORDS FOR WHICH
AUTHOR = PAULING
2. FOR EACH RECORD IN 1
2.1 NOTE SUBJECT
2.2 FIND ALL RECORDS FOR WHICH
SUBJECT = VALUE IN 2.1
2.3 FOR EACH RECORD IN 2.2
2.3.1 PRINT TITLE
3. COUNT RECORDS IN 1
PRINT COUNT IN 3
END

The following request uses a subroutine to validate full-screen input entries. A screen named DATA is defined with input areas named ITEM6, ITEM7, etc. Values entered during the READ SCREEN statement are validated one at a time by subroutine 900. Each screen item is assigned to the argument variable %A before the subroutine is called. If the item fails the validation, the subroutine sets %TAG to a nonzero value before returning. The request sets a tag on the screen for each incorrect item. The REREAD statement is issued if a screen item fails the validity tests.
BEGIN
SCREEN DATA
.
.
.
END SCREEN
READ SCREEN DATA NO REREAD
*VALIDATE DATA ITEMS
1. %A = %DATA:ITEM6
CALL 900
IF %TAG THEN TAG %DATA:ITEM6
2. %A = DATA:ITEM7
CALL 900
.
.
.
50. IF $chktag('DATA') THEN
REREAD SCREEN DATA
JUMP TO 1
51. *PROCESS DATA
.
.
.
*SUBROUTINE TO PERFORM VALIDATION BY TABLE LOOKUP
* IN: %A VALUE
* OUT: %TAG NONZERO IF INVALID
900. SUBROUTINE
.
.
.
END


===$DSCR function===
The $DSCR function interprets its character string argument as a field name. It returns a variable-length character string describing the specified field. New application development should incorporate [[$FDef#$FDef|$FDef]] that supplanted the $DSCR function.
The following discussion is provided to maintain existing code. Each letter in the returned string represents a particular field attribute. Attributes are listed in [[#$DSCR function|$DSCR function]]. 
<table>
<caption>$DSCR field attribute codes (file context)</caption>
<tr class="head">
<th>Character</th>
<th>Attribute</th>
</tr>
<tr>
<td>A</td>
<td>ORDERED CHARACTER</td>
</tr>
<tr>
<td>C</td>
<td>CODED</td>
</tr>
<tr>
<td>D</td>
<td>DEFERRABLE</td>
</tr>
<tr>
<td>F</td>
<td>FRV</td>
</tr>
<tr>
<td>I</td>
<td>INVISIBLE</td>
</tr>
<tr>
<td>K</td>
<td>KEY</td>
</tr>
<tr>
<td>L</td>
<td>LEVEL</td>
</tr>
<tr>
<td>M</td>
<td>MANY-VALUED</td>
</tr>
<tr>
<td>N</td>
<td>ORDERED NUMERIC</td>
</tr>
<tr>
<td>O</td>
<td>OCCURS</td>
</tr>
<tr>
<td>P</td>
<td>UPDATE IN PLACE</td>
</tr>
<tr>
<td>Q</td>
<td>UNIQUE</td>
</tr>
<tr>
<td>R</td>
<td>NUMERIC RANGE</td>
</tr>
<tr>
<td>S</td>
<td>STRING</td>
</tr>
<tr>
<td>T</td>
<td>FLOAT</td>
</tr>
<tr>
<td><var>U</var></td>
<td><var>Undefined</var></td>
</tr>
<tr>
<td>W</td>
<td>AT-MOST-ONE</td>
</tr>
</table>
How $DSCR works
When $DSCR is invoked in file context, the returned string represents the description of the specified field in the current file. 
Each letter that appears in the return value corresponds to an attribute in the field description. For example, if K is one of the letters in the returned string, then the field is KEY. 
If a particular letter does not appear in the result of a $DSCR call, then either the corresponding attribute does not apply or the attribute's opposite is in effect. For example, if M (many-valued) does not appear, the field is NON-CODED and NON-FRV, in which case M does not apply, or it is FEW-VALUED. You can resolve this by looking for C and F in the returned string. 
When $DSCR is invoked in group context, the returned string represents a composite description of the field in all of the files of the current group. Some of the letters imply that the corresponding field attribute is present in all of the files in the group; others imply that the attribute is present in some (at least one) file in the group. If the field specified as the $DSCR argument is not defined in the current file or group, $DSCR returns the character string "U" (undefined). [[#$DSCR function|$DSCR function]] lists the individual letters and their meanings in group context. 
<table>
<caption>$DSCR field attribute codes (group context)</caption>
<tr class="head">
<th>Character</th>
<th>Attribute</th>
</tr>
<tr>
<td>A</td>
<td>ORDERED CHARACTER in some</td>
</tr>
<tr>
<td>C</td>
<td>CODED in all</td>
</tr>
<tr>
<td>D</td>
<td>DEFERRABLE in some</td>
</tr>
<tr>
<td>F</td>
<td>FRV in some</td>
</tr>
<tr>
<td>I</td>
<td>INVISIBLE in all</td>
</tr>
<tr>
<td>K</td>
<td>KEY in all</td>
</tr>
<tr>
<td>L</td>
<td>LEVEL in some</td>
</tr>
<tr>
<td>M</td>
<td>MANY-VALUED in all</td>
</tr>
<tr>
<td>N</td>
<td>ORDERED NUMERIC in some</td>
</tr>
<tr>
<td>O</td>
<td>OCCURS in some</td>
</tr>
<tr>
<td>P</td>
<td>UPDATE IN PLACE in some</td>
</tr>
<tr>
<td>Q</td>
<td>UNIQUE in some</td>
</tr>
<tr>
<td>R</td>
<td>NUMERIC RANGE in all</td>
</tr>
<tr>
<td>S</td>
<td>STRING in all</td>
</tr>
<tr>
<td>T</td>
<td>FLOAT in some</td>
</tr>
<tr>
<td>W</td>
<td>AT-MOST-ONE in all</td>
</tr>
<tr>
<td>U</td>
<td>Undefined</td>
</tr>
</table>
Example
This request determines the attributes of a field and performs one of three types of searches, depending on the results of $DSCR.
BEGIN
%A = $READ ('FIELD NAME')
%B = $READ ('FIELD VALUE')
%C = $DSCR (%A)
IF %C EQ 'U' THEN
PRINT 'ILLEGAL FIELD'
JUMP TO STOP
END IF
*CHECK FOR NON-KEY
IF $INDEX (%C, 'K') EQ 0 THEN
JUMP TO NUM.RNG.CHK
END IF
FIND AND PRINT COUNT
%%A = %B
END FIND
JUMP TO STOP

*CHECK FOR NUMERIC RANGE
NUM.RNG.CHK: IF $INDEX (%C, 'R') EQ 0 THEN
JUMP TO ALL.RECS
END IF
FIND AND PRINT COUNT
%%A IS %B
END FIND
JUMP TO STOP
*NEITHER KEY FOR NUMERIC RANGE
ALL.RECS: FIND ALL RECORDS
END FIND
FOR EACH RECORD IN ALL.RECS
IF %%A = %B THEN
PLACE RECORD ON LIST OK
END IF
END FOR
OKS: COUNT RECORDS ON LIST OK
PRINT COUNT IN OKS
STOP: END
END


[[Category:SOUL]]

$LstFld

2014-08-01T13:39:36Z

Mlarocca:

The $LSTFLD function returns field names in alphabetical order and the field description for each field in a file into an image. $LSTFLD requires that you have an image prepared with which <var class="product">Model 204</var> can create the field description. $LSTFLD works only for files (not groups).
Syntax
The format for the $LSTFLD function is:
%variable = $LSTFLD(<var>[</var>FILE<var>]</var> filename

<var>[</var>AT location<var>]</var>,imagename,loopvar)

where:
<ul>
<li>%variable is the %variable in which the return codes are stored. The return codes are:</li>
<table>
<tr class="head">
<th>Setting</th>
<th>Meaning</th>
</tr>
<tr>
<td align="right">0</td>
<td>Success</td>
</tr>
<tr>
<td align="right">1</td>
<td>End of field list reached</td>
</tr>
<tr>
<td align="right">2</td>
<td>Requested file not available, or is not open, or is not initialized</td>
</tr>
<tr>
<td align="right">3</td>
<td>VTBL full or sort not available</td>
</tr>
<tr>
<td align="right">4</td>
<td>Error occurred during function processing</td>
</tr>
</table>
</li>
<li>filename (required) is the name of the file that contains the fields. A file synonym name can also be used. If you do not enter a location, specifying a null argument, <var class="product">Model 204</var> uses the reference context (at compile time) of the statement which calls the function. When filename=groupname the $LSTFLD function assumes that the name passed is a file name, not a group name.</li>
</li>
<li>imagename (required) is the name of the image where the information is to return.</li>
</li>
<li>loopvar (required) is the loop variable of the image. You must initialize the loop variable (as in the sample image shown with the $FDef function) before invoking $LSTFLD. The value returned in loopvar is used the next time $LSTFLD is invoked to retrieve subsequent field names. </li>
</li>
</ul>
Note
Like $LSTPROC, changing any of the loop control information in the $LSTFLD loop variable after the image is initialized is not allowed and might cause the run to snap.
Locating the ZFIELD image
An image is required by the $FDef and $LSTFLD functions. The ZFIELD image is provided with the <var class="product">Model 204</var> installation. It can give you complete field attribute information; see the discussion on [[$FDef#$FDef|$FDef]]. The size of the name field for the ZFIELD image is 255 bytes. The location of ZFIELD for your site is listed in this table: 
<table>
<tr class="head">
<th>Operating system</th>
<th>Storage location of the ZFIELD image</th>
</tr>
<tr>
<td>z/OS</td>
<td>The JCL library</td>
</tr>
<tr>
<td>z/VM</td>
<td>On the 193 MAINT204 disk as an EXEC</td>
</tr>
<tr>
<td>z/VSE</td>
<td>The JCL library</td>
</tr>
</table>
Example
In this example, the procedure DFIELDS displays the name and definition of each field in the file specified by %FILE.
PROCEDURE DFIELDS
BEGIN
*
* include ZFIELD IMAGE as defined for $FDef *
*
PRINT 'DFIELDS STARTS'
%FILE = '??FILE'
NP
PREPARE ZFIELD
%ZFIELD:BIN1 = 0
%ZFIELD:BIN2 = 0
%ZFIELD:BIN3 = 0
%ZFIELD:BIN4 = 0
%X = 0
REPEAT WHILE %X = 0
%X = $LSTFLD(%FILE,'ZFIELD',%ZFIELD:LOOPVAR)
IF %X = 0 THEN
PRINT %ZFIELD:NAME
PRINT %ZFIELD:FDEF
END IF
END REPEAT
PRINT '-- END OF FIELDS RC=' %X
END
END PROCEDURE

[[Category:SOUL $functions]]

$LstFld

2014-08-01T13:37:35Z

Mlarocca:

The $LSTFLD function returns field names in alphabetical order and the field description for each field in a file into an image. $LSTFLD requires that you have an image prepared with which <var class="product">Model 204</var> can create the field description. $LSTFLD works only for files (not groups).
Syntax
The format for the $LSTFLD function is:
%variable = $LSTFLD(<var>[</var>FILE<var>]</var> filename

<var>[</var>AT location<var>]</var>,imagename,loopvar)

where:
<ul>
<li>%variable is the %variable in which the return codes are stored. The return codes are:</li>
<table>
<tr class="head">
<th>Setting</th>
<th>Meaning</th>
</tr>
<tr>
<td align="right">0</td>
<td>Success</td>
</tr>
<tr>
<td align="right">1</td>
<td>End of field list reached</td>
</tr>
<tr>
<td align="right">2</td>
<td>Requested file not available, or is not open, or is not initialized</td>
</tr>
<tr>
<td align="right">3</td>
<td>VTBL full or sort not available</td>
</tr>
<tr>
<td align="right">4</td>
<td>Error occurred during function processing</td>
</tr>
</table>
</li>
<li>filename (required) is the name of the file that contains the fields. A file synonym name can also be used. If you do not enter a location, specifying a null argument, <var class="product">Model 204</var> uses the reference context (at compile time) of the statement which calls the function. When filename=groupname the $LSTFLD function assumes that the name passed is a file name, not a group name.</li>
</li>
<li>imagename (required) is the name of the image where the information is to return.</li>
</li>
<li>loopvar (required) is the loop variable of the image. You must initialize the loop variable (as in the sample image shown with the $Fdef function) before invoking $LSTFLD. The value returned in loopvar is used the next time $LSTFLD is invoked to retrieve subsequent field names. </li>
</li>
</ul>
Note
Like $LSTPROC, changing any of the loop control information in the $LSTFLD loop variable after the image is initialized is not allowed and might cause the run to snap.
Locating the ZFIELD image
An image is required by the $Fdef and $LSTFLD functions. The ZFIELD image is provided with the <var class="product">Model 204</var> installation. It can give you complete field attribute information; see the discussion on [[$Fdef#$Fdef|$Fdef]]. The size of the name field for the ZFIELD image is 255 bytes. The location of ZFIELD for your site is listed in this table: 
<table>
<tr class="head">
<th>Operating system</th>
<th>Storage location of the ZFIELD image</th>
</tr>
<tr>
<td>z/OS</td>
<td>The JCL library</td>
</tr>
<tr>
<td>z/VM</td>
<td>On the 193 MAINT204 disk as an EXEC</td>
</tr>
<tr>
<td>z/VSE</td>
<td>The JCL library</td>
</tr>
</table>
Example
In this example, the procedure DFIELDS displays the name and definition of each field in the file specified by %FILE.
PROCEDURE DFIELDS
BEGIN
*
* include ZFIELD IMAGE as defined for $Fdef *
*
PRINT 'DFIELDS STARTS'
%FILE = '??FILE'
NP
PREPARE ZFIELD
%ZFIELD:BIN1 = 0
%ZFIELD:BIN2 = 0
%ZFIELD:BIN3 = 0
%ZFIELD:BIN4 = 0
%X = 0
REPEAT WHILE %X = 0
%X = $LSTFLD(%FILE,'ZFIELD',%ZFIELD:LOOPVAR)
IF %X = 0 THEN
PRINT %ZFIELD:NAME
PRINT %ZFIELD:FDEF
END IF
END REPEAT
PRINT '-- END OF FIELDS RC=' %X
END
END PROCEDURE

[[Category:SOUL $functions]]

Obsolete features

2014-08-01T13:36:05Z

Mlarocca: /* $DSCR function */

===Statement numbers===
This appendix describes certain features of User Language which, while still supported, are generally considered obsolete. They have been superseded by other, more efficient features or techniques. Rocket Software does not recommend using these features in newly written requests and procedures.
Rocket Software strongly recommends that you use statement labels (see [[Request composition rules#Statement labels|Statement labels]]) rather than statement numbers. Although statement numbers are still supported, this section is included primarily as documentation for applications developed using earlier releases of <var class="product">Model 204</var>.
====FOPT parameter====
The setting of the FOPT (File Options) parameter determines whether procedures within a file must be labeled or numbered. For more information on the FOPT parameter, refer to the Rocket <var class="product">Model 204</var> Parameter and Command Reference Manual. 
====Rules for using statement numbers====
The rules for specifying statement numbers in User Language statements are summarized below.
<ul>
<li>A statement number is made up of the digits 0-9 and an optional period (.). The number must begin with a digit and cannot contain blanks, although blanks preceding or following it are optional. </li>
</li>
<li>A statement number can start in any column up to but not including column INCCC.</li>
</li>
<li>Any statement can be numbered, but some statements must be numbered. In particular, a statement must be numbered if:</li>
</li>
</ul>
It immediately follows a STORE RECORD or a FIND statement, in which case the statement number indicates the end of the preceding statement.
It is referred to by later statements. In most requests, COUNT RECORDS IN n, COUNT RECORD ON LIST m, NOTE, FIND, FOR EACH VALUE, and FOR EACH OCCURRENCE are referred to later and should therefore be numbered.
It is the first statement after a loop, in which case a number is needed to indicate the end of the loop. An END statement following a loop does not require a number.
It is the statement following a THEN or ELSE clause which is to be executed if the condition is false.
<ul>
<li>The retrieval conditions of a FIND statement, the subexpressions of an IF statement, and the fields of a STORE RECORD statement must not be numbered, even if they start new lines. </li>
</li>
<li>A statement number can have any number of parts, which are delimited by periods. Thus, 2.3 and 0.1 are two part numbers, and 0.05.4 is a three part number. </li>
</li>
<li>A period (.) following a statement number is optional, but the periods separating the parts are required. </li>
For example:
1.1

and
1.1.

are both legal and are interpreted as the same number. 
This rule also applies when referring to statements by number. Thus:
FOR EACH RECORD IN 1.

and
FOR EACH RECORD IN 1

refer to the same statement. 
</li>
<li>Any part of a statement number can be arbitrarily large. </li>
</li>
<li>The number of parts in a statement number must be the same as the level on which the statement is nested. For example, the following sequence is illegal because 2.1.1 has three parts but is nested at the second level:</li>
2. FOR EACH RECORD IN 1
2.1.1 PRINT ALL INFORMATION
</li>
<li>If a statement is not numbered, it is assigned a default level of nesting. The default level is the same as the level of the previous statement. If there is no previous statement, the default is the first level. If the previous statement starts a loop or a THEN, ELSE, or ELSEIF clause, or is a SUBROUTINE statement, the default level is one greater than the level of the previous statement. </li>
</li>
<li>Any part of a statement number can have leading zeros. However, a number with leading zeros is not equivalent to one without. Thus 01 and 1 are both legal but not equivalent; the same is true of 1.1 and 1.01. </li>
</li>
<li>Statements need not be numbered in sequential order. The statement number is just a label for the statement; its numerical value has no significance. </li>
The following, for instance, is a legal request:
BEGIN
3. FIND ALL RECORDS FOR WHICH
COMPANY = ROCKET
1. FOR EACH RECORD IN 3.
3.1 PRINT ALL INFORMATION
2.6. SKIP 1 LINE
END
</li>
<li>Within a request, statement numbers should be unique. If not, <var class="product">Model 204</var> prints the message:</li>
M204.0223: STATEMENT LABEL MULTIPLY DEFINED

This is a warning message; the request can still be run. 
</li>
<li>A statement number followed by a label is allowed with or without a space between the number and the label. If a statement number is followed by a label and there is no space between them, User Language separates them into statement number and label. Although a statement number can be followed by a label, it is strongly recommended that you avoid placing statement numbers and labels on the same line. </li>
</li>
</ul>
Examples
The following request addresses an automated library card catalogue. Each record in the file contains information that would normally appear on a single card in the catalogue, such as AUTHOR, TITLE, SUBJECT, and CATALOGUE NUMBER.
BEGIN
1. FIND ALL RECORDS FOR WHICH
AUTHOR = PAULING
2. FOR EACH RECORD IN 1
2.1 NOTE SUBJECT
2.2 FIND ALL RECORDS FOR WHICH
SUBJECT = VALUE IN 2.1
2.3 FOR EACH RECORD IN 2.2
2.3.1 PRINT TITLE
3. COUNT RECORDS IN 1
PRINT COUNT IN 3
END

The following request uses a subroutine to validate full-screen input entries. A screen named DATA is defined with input areas named ITEM6, ITEM7, etc. Values entered during the READ SCREEN statement are validated one at a time by subroutine 900. Each screen item is assigned to the argument variable %A before the subroutine is called. If the item fails the validation, the subroutine sets %TAG to a nonzero value before returning. The request sets a tag on the screen for each incorrect item. The REREAD statement is issued if a screen item fails the validity tests.
BEGIN
SCREEN DATA
.
.
.
END SCREEN
READ SCREEN DATA NO REREAD
*VALIDATE DATA ITEMS
1. %A = %DATA:ITEM6
CALL 900
IF %TAG THEN TAG %DATA:ITEM6
2. %A = DATA:ITEM7
CALL 900
.
.
.
50. IF $chktag('DATA') THEN
REREAD SCREEN DATA
JUMP TO 1
51. *PROCESS DATA
.
.
.
*SUBROUTINE TO PERFORM VALIDATION BY TABLE LOOKUP
* IN: %A VALUE
* OUT: %TAG NONZERO IF INVALID
900. SUBROUTINE
.
.
.
END


===$DSCR function===
The $DSCR function interprets its character string argument as a field name. It returns a variable-length character string describing the specified field. New application development should incorporate [[$Fdef#$Fdef|$Fdef]] that supplanted the $DSCR function.
The following discussion is provided to maintain existing code. Each letter in the returned string represents a particular field attribute. Attributes are listed in [[#$DSCR function|$DSCR function]]. 
<table>
<caption>$DSCR field attribute codes (file context)</caption>
<tr class="head">
<th>Character</th>
<th>Attribute</th>
</tr>
<tr>
<td>A</td>
<td>ORDERED CHARACTER</td>
</tr>
<tr>
<td>C</td>
<td>CODED</td>
</tr>
<tr>
<td>D</td>
<td>DEFERRABLE</td>
</tr>
<tr>
<td>F</td>
<td>FRV</td>
</tr>
<tr>
<td>I</td>
<td>INVISIBLE</td>
</tr>
<tr>
<td>K</td>
<td>KEY</td>
</tr>
<tr>
<td>L</td>
<td>LEVEL</td>
</tr>
<tr>
<td>M</td>
<td>MANY-VALUED</td>
</tr>
<tr>
<td>N</td>
<td>ORDERED NUMERIC</td>
</tr>
<tr>
<td>O</td>
<td>OCCURS</td>
</tr>
<tr>
<td>P</td>
<td>UPDATE IN PLACE</td>
</tr>
<tr>
<td>Q</td>
<td>UNIQUE</td>
</tr>
<tr>
<td>R</td>
<td>NUMERIC RANGE</td>
</tr>
<tr>
<td>S</td>
<td>STRING</td>
</tr>
<tr>
<td>T</td>
<td>FLOAT</td>
</tr>
<tr>
<td><var>U</var></td>
<td><var>Undefined</var></td>
</tr>
<tr>
<td>W</td>
<td>AT-MOST-ONE</td>
</tr>
</table>
How $DSCR works
When $DSCR is invoked in file context, the returned string represents the description of the specified field in the current file. 
Each letter that appears in the return value corresponds to an attribute in the field description. For example, if K is one of the letters in the returned string, then the field is KEY. 
If a particular letter does not appear in the result of a $DSCR call, then either the corresponding attribute does not apply or the attribute's opposite is in effect. For example, if M (many-valued) does not appear, the field is NON-CODED and NON-FRV, in which case M does not apply, or it is FEW-VALUED. You can resolve this by looking for C and F in the returned string. 
When $DSCR is invoked in group context, the returned string represents a composite description of the field in all of the files of the current group. Some of the letters imply that the corresponding field attribute is present in all of the files in the group; others imply that the attribute is present in some (at least one) file in the group. If the field specified as the $DSCR argument is not defined in the current file or group, $DSCR returns the character string "U" (undefined). [[#$DSCR function|$DSCR function]] lists the individual letters and their meanings in group context. 
<table>
<caption>$DSCR field attribute codes (group context)</caption>
<tr class="head">
<th>Character</th>
<th>Attribute</th>
</tr>
<tr>
<td>A</td>
<td>ORDERED CHARACTER in some</td>
</tr>
<tr>
<td>C</td>
<td>CODED in all</td>
</tr>
<tr>
<td>D</td>
<td>DEFERRABLE in some</td>
</tr>
<tr>
<td>F</td>
<td>FRV in some</td>
</tr>
<tr>
<td>I</td>
<td>INVISIBLE in all</td>
</tr>
<tr>
<td>K</td>
<td>KEY in all</td>
</tr>
<tr>
<td>L</td>
<td>LEVEL in some</td>
</tr>
<tr>
<td>M</td>
<td>MANY-VALUED in all</td>
</tr>
<tr>
<td>N</td>
<td>ORDERED NUMERIC in some</td>
</tr>
<tr>
<td>O</td>
<td>OCCURS in some</td>
</tr>
<tr>
<td>P</td>
<td>UPDATE IN PLACE in some</td>
</tr>
<tr>
<td>Q</td>
<td>UNIQUE in some</td>
</tr>
<tr>
<td>R</td>
<td>NUMERIC RANGE in all</td>
</tr>
<tr>
<td>S</td>
<td>STRING in all</td>
</tr>
<tr>
<td>T</td>
<td>FLOAT in some</td>
</tr>
<tr>
<td>W</td>
<td>AT-MOST-ONE in all</td>
</tr>
<tr>
<td>U</td>
<td>Undefined</td>
</tr>
</table>
Example
This request determines the attributes of a field and performs one of three types of searches, depending on the results of $DSCR.
BEGIN
%A = $READ ('FIELD NAME')
%B = $READ ('FIELD VALUE')
%C = $DSCR (%A)
IF %C EQ 'U' THEN
PRINT 'ILLEGAL FIELD'
JUMP TO STOP
END IF
*CHECK FOR NON-KEY
IF $INDEX (%C, 'K') EQ 0 THEN
JUMP TO NUM.RNG.CHK
END IF
FIND AND PRINT COUNT
%%A = %B
END FIND
JUMP TO STOP

*CHECK FOR NUMERIC RANGE
NUM.RNG.CHK: IF $INDEX (%C, 'R') EQ 0 THEN
JUMP TO ALL.RECS
END IF
FIND AND PRINT COUNT
%%A IS %B
END FIND
JUMP TO STOP
*NEITHER KEY FOR NUMERIC RANGE
ALL.RECS: FIND ALL RECORDS
END FIND
FOR EACH RECORD IN ALL.RECS
IF %%A = %B THEN
PLACE RECORD ON LIST OK
END IF
END FOR
OKS: COUNT RECORDS ON LIST OK
PRINT COUNT IN OKS
STOP: END
END


[[Category:SOUL]]

Program Communication facilities

2014-07-31T19:49:15Z

Mlarocca: /* Usage notes */

<div class="toclimit-3">

==Overview==

<var class="product">Model 204</var> provides facilities that allow a User Language request to communicate with user-written CICS programs, CMS EXECs, or SNA Communications Server (formerly VTAM) application programs. These facilities for program, or intersystem, communication (between <var class="product">Model 204</var> and another system — CICS or CMS — on the same machine or between <var class="product">Model 204</var> and another system on a different machine) are as follows:
<ul>
<li>TPROCESS, or Terminal Process, a process-to-process communication facility in CICS and CMS — A request can identify a CICS program or CMS EXEC and trigger its execution. In addition, the User Language request can communicate with the CICS program or CMS EXEC. </li>

<li>Transfer Control — A request can identify a CICS program or SNA Communications Server application and transfer control to it. </li>
</ul>

===Horizon===

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

===BATCH2===

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

===Partner process definition===

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

With Horizon, when a request communicates with another request that resides in a separate <var class="product">Model 204</var> Online, the initiating request is the client process, while the responding request is referred to as the server process.

===Network entity definition===

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

===TCP/IP Sockets Interface for Model 204===

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

==TPROCESS (terminal process) communication==

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

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

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

TPROCESS applications cannot use the SECTRLOG trusted login option. Using trusted Login results in the following message:
M204.1786: PROCESS-TO-PROCESS NOT SUPPORTED ON THIS THREAD


==User Language TPROCESS communication==

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

===Controlling the conversation===

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

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

===User Language communication statements===

The User Language TPROCESS communication statements are summarized in [[#User Language communication statements|User Language communication statements]] and is discussed in detail on the pages that follow. Handling errors during statement processing is described in [[#Error handling for TPROCESS statements|Error handling for TPROCESS statements]]. 
<table>
<caption>TPROCESS User Language statements</caption>
<tr class="head">
<th>Statement</th>
<th>Description</th>
</tr>

<tr>
<td>CLOSE PROCESS</td>
<td>Ends the conversation between the request and the partner process. </td>
</tr>

<tr>
<td>FLUSH PROCESS</td>
<td>Supports increased router method independence in User Language.</td>
</tr>

<tr>
<td>OPEN PROCESS</td>
<td>Begins a conversation between a request and a partner process.</td>
</tr>

<tr>
<td>RECEIVE </td>
<td>Receives data from a partner process.</td>
</tr>

<tr>
<td>SEND</td>
<td>Transmits data from a request to a partner process.</td>
</tr>

<tr>
<td>SIGNAL PROCESS</td>
<td>Signals interruption of the conversation in process.</td>
</tr>
</table>

===CLOSE PROCESS statement===

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

====Syntax====

The format of the CLOSE PROCESS statement is:
CLOSE PROCESS {cid | processname | %variable}
[SYNCLEVEL | FLUSH | %variable]

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

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

<li>SYNCLEVEL, FLUSH, and %variable (used as the second parameter) have no effect, except to allow portability from one TRANSPORT/PROTOCOL combination to another (see the DEFINE LINK command). </li>
</ul>

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

===OPEN PROCESS statement===

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

====Syntax====

The format of the OPEN PROCESS statement is: 
OPEN PROCESS {processname | %variable}
[CID {name | %variable}]

Where:
<ul>
<li>processname refers to a partner process defined in a DEFINE PROCESS command. The partner process name also can be provided as the value of a %variable.</li>

<li>CID specifies the ID for use in subsequent User Language statements for the conversation. If CID is not given, the process name is used as the ID. CID must be specified if there are two or more active conversations with the same process name. And, if CID is specified, subsequent conversation statements must also specify the same CID value. </li>
</ul>

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

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

===RECEIVE statement===

The RECEIVE statement receives data from a partner process. 

====Syntax====

The format of the RECEIVE statement is:
RECEIVE {IMAGE imagename | %variable}
FROM {cid | processname | %variable}
[ERESULT %variable]

Where:
<ul>
<li>imagename specifies that the receiving area is an image previously defined by an image definition. The image automatically is set active by the RECEIVE statement.

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

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

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

<li>RESULT returns the following values:
<ul>
<li>If $STATUS = 0, "Data complete" </li>

<li>If $STATUS = 1, "Data truncated" </li>

<li>If i$STATUS > 1, "Null" </li>
</ul>
</ul>

If the receiving area is not large enough to accommodate the data transmitted by the partner process, the following actions occur: 
<ul>
<li>If the receiving area is an image, truncation occurs. However, a warning message is not issued. This type of truncation is caused by one of the following conditions:

<ul>
<li>The full screen buffer area (that is, FSCB) is not large enough to accommodate the data; therefore, the excess data is lost.

Refer to [[Large request considerations#FSCB (full-screen buffer)|FSCB (full-screen buffer)]] for more information on its size requirements.</li>

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

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

<li>If the receiving area is a %variable, truncation occurs. </li>
</ul>

===SEND statement===

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

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

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

====Syntax====

The format of the SEND statement is:
SEND {IMAGE imagename |'string' | %variable}
TO {cid | processname | %variable}
[REQSENT %variable] [FLUSH]

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

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

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

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

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

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

===SIGNAL PROCESS statement===

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

====Syntax====

The format of the SIGNAL PROCESS statement is:
SIGNAL PROCESS {cid | processname | %variable} {nnn | %variable}


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

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

<li>n is an arbitrary number assigned to this SIGNAL. This number must be an integer in the range of -2,147,483,648 through +2,147,483,647 (a four-byte binary value). This number also can be provided as a %variable. If neither n nor a %variable is specified, a default value of 0 is used.
</li>
</ul>

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

===Error handling for TPROCESS statements===

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

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

The values returned by $Status are summarized in [[#Error handling for TPROCESS statements|Error handling for TPROCESS statements]]. 
<table>
<caption>$Status return values</caption>
<tr class="head">
<th>Return
value</th>
<th>Error
level</th>
<th>
Result/action</th>
</tr>

<tr>
<td>0</td>
<td>Success</td>
<td>The message text set to null.</td>
</tr>

<tr>
<td>1</td>
<td>Warning</td>
<td>The statement generating this code has completed, but a warning condition was encountered. $StatusD provides a detailed warning code.</td>
</tr>

<tr>
<td>2</td>
<td>Signal</td>
<td>

A SIGNAL has been received from the partner process.
The $StatusD function provides the SIGNAL value. If this code is received on a:

SIGNAL statement, then the SIGNAL was transmitted to the partner process. 

SEND statement, the data transmitted was not received by the partner process and was discarded. 

RECEIVE statement, no data was received and the contents of the receiving area are unpredictable.
</td>
</tr>

<tr>
<td>3</td>
<td> </td>
<td>The User Language statement is invalid in this conversation state.</td>
</tr>

<tr>
<td>4
or greater</td>
<td>Serious Error</td>
<td>If this code is generated by a CLOSE PROCESS statement, then the CLOSE PROCESS functions have been completed to the greatest degree possible. Any other statement that generates this code did not complete at all. $StatusD provides a detailed error code.</td>
</tr>
</table>

[[#Error handling for TPROCESS statements|Error handling for TPROCESS statements]] provides the message text returned by the $ERRMSG function, depending upon the values returned by the $Status and $StatusD functions.
For a detailed explanation of these messages, see the M204.xxxx descriptions in the
[http://www.rocketsoftware.com/m204/products/index/documentation/v7r4/Model-204-Messages/view Model 204 core messages],
where <var class="term">xxxx</var> is the $StatusD value. 
<table>
<caption>$ERRMSG text per $Status / $StatusD</caption>
<tr class="head">
<th>[[$Status]]</th>
<th>[[$StatusD]]</th>
<th>Text returned by the $ERRMSG function</th>
</tr>

<tr>
<td align="right">0</td>
<td align="right">0</td>
<td>Successful: Error message area set to null</td>
</tr>

<tr>
<td align="right">1</td>
<td align="right">1785</td>
<td>Data received has been truncated</td>
</tr>

<tr>
<td align="right">2</td>
<td align="right">ANY</td>
<td>A SIGNAL has been received: Error message area is set to null</td>
</tr>

<tr>
<td align="right">3</td>
<td align="right">1254</td>
<td>User Language statement invalid in this conversation state</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">89</td>
<td>No I/O allowed on terminal while TPROCESS is in effect</td>
</tr>

<tr>
<td align="right">5</td>
<td align="right">1521</td>
<td>Remote process does not exist or required access not authorized</td>
</tr>

<tr>
<td align="right">5</td>
<td align="right">1572</td>
<td>Process xxxxxxxx is not open</td>
</tr>

<tr>
<td align="right">5</td>
<td align="right">1746</td>
<td>PROCESS, PROCESSGROUP, or LINK not found</td>
</tr>

<tr>
<td align="right">5</td>
<td align="right">1786</td>
<td>TPROCESS not supported on this thread</td>
</tr>

<tr>
<td align="right">5</td>
<td align="right">1791</td>
<td>Partner process will not accept defined protocol, mode, or terminal</td>
</tr>

<tr>
<td align="right">5</td>
<td align="right">1806</td>
<td>Process not defined for transfer</td>
</tr>

<tr>
<td align="right">10</td>
<td align="right">1787</td>
<td>The defined TPROCESS buffer size is too large</td>
</tr>

<tr>
<td align="right">10</td>
<td align="right">1788</td>
<td>Unable to allocate necessary TPROCESS data areas</td>
</tr>

<tr>
<td align="right">51</td>
<td align="right">1793</td>
<td>Partner process is not active</td>
</tr>

<tr>
<td align="right">52</td>
<td align="right">1796</td>
<td>TPROCESS communications link has been closed</td>
</tr>

<tr>
<td align="right">54</td>
<td align="right">1784</td>
<td>Invalid TPROCESS status code</td>
</tr>

<tr>
<td align="right">54</td>
<td align="right">1789</td>
<td>Invalid TPROCESS message</td>
</tr>
</table>

==CICS TPROCESS communication==

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

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

===Support required for CICS TPROCESS===

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

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

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

M204PSFS, the CICS full screen interface module, must have a TWA defined.
For more information about the <var class="product">Model 204</var> CICS full screen interface, see the
Rocket Model 204 Installation Guide for your operating system. 

==CICS TPROCESS calls==

The IFPPCI module, described further in the <var class="book">Rocket Model 204 Installation Guide for IBM z/OS</var>, has five entry points that can be called by the CICS program.
The entry points, and the functions they provide, are summarized in [[#CICS TPROCESS calls|CICS TPROCESS calls]]. Each call is discussed in greater detail on the pages that follow. The notation conventions used for the individual call descriptions are discussed below. 
<table>
<caption>CICS TPROCESS calls</caption>
<tr class="head">
<th>Call</th>
<th>Description</th>
</tr>

<tr>
<td>IFCSA</td>
<td>Prior to <var class="product">Model 204</var> V3R1, passed the address of the Common System Area (CSA) to the CICS Interface. As of V3R1, the IFCSA call does not function, but is not upwardly incompatible.</td>
</tr>

<tr>
<td>IFPREP</td>
<td>Allows the CICS program to set session defaults and retrieve information regarding the TPROCESS conversation.</td>
</tr>

<tr>
<td>IFRECV</td>
<td>Receives data from the User Language request.</td>
</tr>

<tr>
<td>IFSEND</td>
<td>Sends data to the User Language request.</td>
</tr>

<tr>
<td>IFSGNL</td>
<td>Signals the User Language request, interrupting the conversation.</td>
</tr>
</table>

===Notation conventions for CICS call descriptions===

====Call name and syntax====

The syntax of calls is presented in this format:
callname|alias (parm1, parm2,...parmn)


Where: 
<ul>
<li><var class="term">callname</var> is a keyword that specifies the name of the function. </li>

<li><var class="term">parm1</var> is the first parameter in the call list. You must specify parameters in the proper sequence, as shown (<var class="term">parm2</var> follows <var class="term">parm1</var>; <var class="term">parmn</var> is last).

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

====Parameters====

Each parameter description provides a three-character code having the following format: 
[X,y,z]


Where: 
<ul>
<li>X specifies that the parameter is used for input or output operations, and is either of the following codes:
<ul>
<li>I (input) </li>
<li>O (output) </li>
</ul>

<li><var class="term">y</var> specifies that the parameter, if coded, must be defined in the host language program as one of three possible data type variables, and is one of the following codes:
<ul>
<li>i (integer whose maximum length is 4 bytes) </li>

<li>s (short character string whose maximum length is 32 bytes) </li>

<li>c (character string whose maximum length is the buffer size)</li>
</ul>

<li><var class="term">z</var> specifies whether the parameter must be coded in the call, and is either (or both) of the following codes:
<ul>
<li>r (required)</li>
<li>o (optional) </li>
</ul></li>
</ul>

====Example====

For example, RETCODE [O,i,r] where:
<ul>
<li>O specifies that RETCODE is an output parameter</li>

<li>i specifies an integer type variable (maximum length is 4 bytes) </li>

<li>r specifies that RETCODE is required</li>
</ul>

===Individual call descriptions===

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

===IFCSA===

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

Prior to <var class="product">Model 204</var> Version 3.1, the IFCSA call was required to be the first call issued during the IFAM2 session. The IFCSA call passed the Common System Area (CSA) address. 

===IFPREP===

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

====Syntax====

The format of the IFPREP call is:
IFPREP(RETCODE,RC_DETAIL,PROCESS_ID,LANG_IND,DATA_LEN)


====Parameters====

Specify the parameters in the syntax order shown above. 
<table>
<tr class="head">
<th>Parameter </th>
<th>Discussion</th>
</tr>

<tr>
<td>RETCODE</td>
<td>[O,i,r] The <var class="product">Model 204</var> return code is a required output parameter. The code is a binary integer value. [[#CICS completion codes|CICS completion codes]] displays all the CICS TPROCESS return codes.</td>
</tr>

<tr>
<td>RC_DETAIL</td>
<td>[O,i,r] The return code detail is a required output parameter. The code is a binary integer value. <var class="product">Model 204</var> returns a second level code which indicates the status of the TPROCESS conversation. </td>
</tr>

<tr>
<td>PROCESS_ID</td>
<td>[O,i,r] The process identifier is a required output parameter. Specify an integer variable. <var class="product">Model 204</var> returns a value that must be referenced in subsequent IFSEND, IFRECV, and IFSGNL calls to transmit data in TPROCESS applications. </td>
</tr>

<tr>
<td>LANG_IND</td>
<td>

[I,i,r] The language indicator is a required input parameter which establishes the calling sequence convention to be used corresponding to the host language. The indicator specifies the format of arguments that are passed in subsequent calls. 

Specify one of the following integer values: 

1 - PL/I F-level, and BAL languages 

2 - COBOL, Fortran, and BAL languages 

3 - PL/I with + Optimizer / Checkout compilers, VS/Fortran, and BAL languages 

Any convention can be specified for use with the BAL language, and the BAL programmer must adhere to the convention that is specified when coding arguments.
</td>
</tr>

<tr>
<td>DATA_LEN</td>
<td>[O,i,r] The data length is a required output parameter. Specify an integer value. <var class="product">Model 204</var> returns the value of the DATALEN parameter in the DEFINE PROCESS command.</td>
</tr>
</table>

====Notes and tips====

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

====Completion codes (RETCODE) applicable====

The completion codes that apply to the IFPREP call are:
<table>
<tr class="head">
<td align="right">0</td>
<td> Successful</td>
</tr>

<tr>
<td align="right">4</td>
<td> Error. Refer to [[#CICS completion codes|CICS completion codes]]. </td>
</tr>
</table>

===IFRECV===

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

====Syntax====

The format for the IFRECV call is:
IFRECV(RETCODE,RC_DETAIL,PROCESS_ID,DATA_AREA,DATA_LEN)


====Parameters====

Specify the parameters in the syntax order shown above.
<table>
<tr class="head">
<th>Parameter </th>
<th>Discussion</th>
</tr>

<tr>
<td>RETCODE</td>
<td>[O,i,r] The <var class="product">Model 204</var> return code is a required output parameter. The code is a binary integer value. [[#CICS completion codes|CICS completion codes]] displays all the CICS TPROCESS return codes. </td>
</tr>

<tr>
<td>RC_DETAIL</td>
<td>[O,i,r] The return code detail is a required output parameter. The code is a binary integer value. <var class="product">Model 204</var> returns a second level code which, indicates the status of the TPROCESS conversation. </td>
</tr>

<tr>
<td>PROCESS_ID</td>
<td>[I,i,r] The process identifier is a required input parameter. Specify an integer variable, the value that is returned by <var class="product">Model 204</var> in the preceding IFPREP call.</td>
</tr>

<tr>
<td>DATA_AREA</td>
<td>[O,c,r] The data area is a required output parameter which specifies the address of the user's data area. Specify a character string variable. This area receives the data stream that is sent by the User Language request to the HLI program. </td>
</tr>

<tr>
<td>DATA_LEN</td>
<td>[I,i,r] The data length is a required input parameter if the language indicator parameter (LANG_IND) setting is 2 (COBOL, Fortran, BAL) in the preceding IFPREP call. Specify an integer value, the length of the receiving area. <var class="product">Model 204</var> returns the value which is the actual length of the data that was moved into the receiving area. </td>
</tr>
</table>
Note: The data area length is optional if the language indicator parameter (LANG_IND) setting is 1 or 3 (PL/I, VS/Fortran, BAL) in the preceding IFPREP call. 

====Notes and tips====

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

====Completion codes (RETCODE) applicable====

The completion codes that apply to the IFRECV call are:
<table>
<tr class="head">
<td align="right"> 0</td>
<td>Successful</td>
</tr>

<tr>
<td align="right"> 1</td>
<td>Warning</td>
</tr>

<tr>
<td align="right"> 2</td>
<td>No data was received and the contents of the data area and data area length
arguments are unpredictable.</td>
</tr>

<tr>
<td align="right"> 4</td>
<td>Error. Refer to [[#CICS completion codes|CICS completion codes]].</td>
</tr>
</table>

===IFSEND===

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

====Syntax====

The format of the IFSEND call is:
IFSEND(RETCODE,RC_DETAIL,PROCESS_ID,DATA_AREA,DATA_LEN)


====Parameters====

Specify the parameters in the syntax order shown above.
<table>
<tr class="head">
<th>Parameters </th>
<th>Discussion</th>
</tr>

<tr>
<td>RETCODE</td>
<td>[O,i,r] The <var class="product">Model 204</var> return code is a required output parameter. The code is a binary integer value. [[#CICS completion codes|CICS completion codes]] displays all the CICS TPROCESS return codes. </td>
</tr>

<tr>
<td>RC_DETAIL</td>
<td>[O,i,r] The return code detail is a required output parameter. The code is a binary integer value. <var class="product">Model 204</var> returns a second level code which indicates the status of the TPROCESS conversation. </td>
</tr>

<tr>
<td>PROCESS_ID</td>
<td>[I,i,r] The process identifier is a required input parameter. Specify an integer variable, the value that is returned by <var class="product">Model 204</var> in the preceding IFPREP call. </td>
</tr>

<tr>
<td>DATA_AREA</td>
<td>[O,c,r] The data area is a required output parameter which specifies the address of the user's data area. Specify a character string variable. This area receives the data stream that is sent by the User Language request to the HLI program. </td>
</tr>

<tr>
<td>DATA_LEN</td>
<td>[I,i,r] The data length is a required input parameter if the language indicator parameter (LANG_IND) setting is 2 (COBOL, Fortran, BAL) in the preceding IFPREP call. Specify an integer value, the length of the receiving area. <var class="product">Model 204</var> returns the value which is the actual length of the data that was moved into the receiving area. </td>
</tr>
</table>
Note: The data area length is optional if the language indicator parameter (LANG_IND) setting is 1 or 3 (PL/I, VS/Fortran, BAL) in the preceding IFPREP call. 

====Notes and tips====

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

====Completion codes (RETCODE) applicable====

The completion codes that apply to the IFSEND call are:
<table>
<tr class="head">
<td align="right">0</td>
<td>Successful</td>
</tr>

<tr>
<td align="right">1</td>
<td>Warning</td>
</tr>

<tr>
<td align="right">2</td>
<td>Signal received. The data specified in the data area argument was not transmitted.</td>
</tr>

<tr>
<td align="right">4</td>
<td>Error. Refer to [[#CICS completion codes|CICS completion codes]].</td>
</tr>
</table>

===IFSGNL===

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

====Syntax====

The format of the IFSGNL call is:
IFSGNL(RETCODE,RC_DETAIL,PROCESS_ID,SGNL_VAL)


====Parameters====

Specify the parameters in the syntax order shown above. 
<table>
<tr class="head">
<th>Parameters </th>
<th>Discussion</th>
</tr>

<tr>
<td>RETCODE</td>
<td>[O,i,r] The <var class="product">Model 204</var> return code is a required output parameter. The code is a binary integer value. [[#CICS completion codes|CICS completion codes]] displays all the CICS TPROCESS return codes.</td>
</tr>

<tr>
<td>RC_DETAIL</td>
<td>[O,i,r] The return code detail is a required output parameter. The code is a binary integer value. <var class="product">Model 204</var> returns a second level code which indicates the status of the TPROCESS conversation. </td>
</tr>

<tr>
<td>PROCESS_ID</td>
<td>[I,i,r] The process identifier is a required input parameter. Specify an integer variable, the value that is returned by <var class="product">Model 204</var> in the preceding IFPREP call.</td>
</tr>

<tr>
<td>SGNL_VAL</td>
<td>[I,i,o] The signal value is an optional input parameter. Specify a fullword binary value in the range -2,147,483,648 through +2,147,483,647. If the signal value is not specified, it defaults to 0.</td>
</tr>
</table>

====Notes and tips====

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

===CICS completion codes===

[[#CICS completion codes|CICS completion codes]] describes the completion codes and corresponding completion detail values for the IFPREP, IFRECV, IFSEND, and IFSGNL calls. 
<table>
<caption>TPROCESS completion codes</caption>
<tr class="head">
<th>Code</th>
<th>Completion detail value</th>
<th>Description</th>
</tr>

<tr>
<td align="right">0</td>
<td align="right">0</td>
<td>For the current release, the value is always zero.</td>
</tr>

<tr>
<td align="right">1</td>
<td align="right">11</td>
<td>

If the call was IFSEND, the call is truncated before transmission.

If the call was IFRECV, the data is truncated during receipt.
</td>
</tr>

<tr>
<td align="right">2</td>
<td align="right">ANY</td>
<td>This argument is equal to the signal value specified by the User Language request. It can be an integer between -2,147,483,648 and 2,147,483,647.</td>
</tr>

<tr>
<td align="right">3</td>
<td> </td>
<td>(reserved for future use)</td>
</tr>

<tr>
<td align="right">4</td>
<td> </td>
<td>There is a severe error.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">10</td>
<td>CRAM/IUCV link closed.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">11</td>
<td>Remote process active upon detachment.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">12</td>
<td>No data received. Call IFSEND to transmit data.
The contents of the data area and the data area length are unpredictable.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">13</td>
<td>No data sent. Call IFRECV to receive data.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">100</td>
<td>User Language request issued a CLOSE PROCESS statement.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">102</td>
<td>Connection error.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">200</td>
<td>Not enough memory to allocate IFCB.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">201</td>
<td>IFPREP has not been called.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">202</td>
<td>Not enough arguments were passed.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">301</td>
<td>Syntax error encountered in CMS Host Language Interface subcommand. Subcommand ignored.</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">302</td>
<td>Error assigning a value to variable while processing an IFRECV command. Data discarded.</td>
</tr>
</table>

==CICS TPROCESS example==

In this example, the User Language request communicates with a CICS program using the SEND and RECEIVE statements. The request sends two numbers to the CICS program. The CICS program adds the numbers together and sends the sum back to the User Language request. 
DEFINE LINK LK4CICS WITH SCOPE=SYSTEM -
TRANSPORT=TERMINAL -
PROTOCOL=MASTER
DEFINE PROCESSGROUP PGP4CICS WITH SCOPE=SYSTEM -
LINK=LK4CICS -
TERMINAL=LOCAL
DEFINE PROCESS PS4CICS WITH SCOPE=SYSTEM -
DESTINATION=PGP4CICS -
PARTNER=PARTNER -
DATALEN=100 -
MODE=LINK
OPEN LINK LK4CICS

BEGIN
SCREEN SCR1
MAX PFKEY 12
TITLE 'CP PROCESS-TO-PROCESS EXAMPLE' AT 12 BRIGHT
SKIP 2 LINES
PROMPT 'INPUT TWO NUMBERS, TO BE TRANSMITTED -
TO THE CICS'
PROMPT 'PARTNER PROCESS WHICH WILL RETURN THE -
VALUE OF THE SUM'
SKIP 2 LINES
PROMPT 'INPUT FIRST VALUE :' AT 12 INPUT -
VAL1 LEN 4 NUMERIC
PROMPT 'INPUT SECOND VALUE :' AT 12 INPUT VAL2 -
LEN 4 NUMERIC
SKIP 2 LINES
PROMPT 'ENTER X TO STOP RUN:' AT 12 INPUT EOJ LEN 1
END SCREEN
*
IMAGE IMG1
VALUE1 IS ZONED LEN 4 UNSIGNED
VALUE2 IS ZONED LEN 4 UNSIGNED
FILLER IS STRING LEN 72
END IMAGE
*

IMAGE IMG2
VALUE1 IS ZONED LEN 5 UNSIGNED
FILLER IS STRING LEN 75
END IMAGE
*

PREPARE IMAGE IMG1
PREPARE IMAGE IMG2
*
OPEN PROCESS PS4CICS
IF $STATUS GT 1 THEN
PRINT 'OPEN PROCESS FAILED, $STATUSD =' AND $STATUSD AND $ERRMSG
JUMP TO STOP.RUN
END IF
*
MAIN.LOOP:

*
READ SCREEN SCR1
%IMG1:VALUE1 = %SCR1:VAL1
%IMG1:VALUE2 = %SCR1:VAL2
*
IF %SCR1:EOJ EQ 'X' THEN
JUMP TO STOP.RUN
END IF
*
SEND IMAGE IMG1 TO PS4CICS
IF $STATUS GT 1 THEN
PRINT 'SEND FAILED, $STATUSD =' AND -
$STATUSD AND $ERRMSG
JUMP TO STOP.RUN
END IF
*
RECEIVE IMAGE IMG2 FROM PS4CICS
IF $STATUS GT 1 THEN
PRINT 'RECEIVE FAILED, $STATUSD =' AND -
$STATUSD AND $ERRMSG
JUMP TO STOP.RUN
END IF
*
PRINT 'THE VALUE RETURNED IS' AND %IMG2:VALUE1
*
JUMP TO MAIN.LOOP
*
STOP.RUN:
*
CLOSE PROCESS PS4CICS
PRINT 'END OF SAMPLE CP PROGRAM'
END


===CICS partner===

The following sample CICS program could communicate with the above User Language request to perform the addition operation and send back the sum to the request.
*********************************************
* THIS IS AN EXAMPLE OF A CICS 'PARTNER PROCESS'
* PROGRAM.
* ITS PURPOSE IS TO PROVIDE A SKELETON, FROM WHICH A MORE
* COMPLEX PROGRAM CAN BE DEVELOPED.
* THE LOGIC OF THIS PROGRAM IS AS FOLLOWS:
*
* 1) RECEIVE A MESSAGE FROM THE USER LANGUAGE PARTNER.
* THIS MESSAGE CONTAINS 2 NUMBERS.
* 2) ADD THESE NUMBERS TOGETHER
* 3) SEND A MESSAGE TO THE USER LANGUAGE PARTNER THAT
* CONTAINS THE SUM.
* 4) CONTINUE THIS LOOP (STEP 1 THRU 3) UNTIL THE USER
* LANGUAGE PARTNER CLOSES THE CONVERSATION.
**********************************************
EJECT
IDENTIFICATION DIVISION.
PROGRAM-ID. PARTNER.

ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.

DATA DIVISION.
WORKING-STORAGE SECTION.

01 CONTROL-FLAGS.
05 EOJ-FLAG PIC X(01) VALUE 'N'.

01 CALL-PARAMETER-AREA.
05 COMPLETION-CODE PIC S9(05) VALUE +0 COMP.
05 COMPLETION-DETAIL PIC S9(05) VALUE +0 COMP.
05 LANGUAGE-INDICATOR PIC S9(05) VALUE +2 COMP.
05 PROCESS-IDENTIFIER PIC S9(05) VALUE +0 COMP.
05 DATA-LENGTH PIC S9(05) VALUE +0 COMP.

01 RECV-AREA-LENGTH PIC S9(05) VALUE +80 COMP.
01 RECV-AREA.
05 RECV-VALUE-1 PIC 9(04) VALUE 0.
05 RECV-VALUE-2 PIC 9(04) VALUE 0.
05 FILLER PIC X(72) VALUE SPACES.

01 SEND-AREA-LENGTH PIC S9(05) VALUE +80 COMP.
01 SEND-AREA.
05 SEND-VALUE PIC 9(05) VALUE 0.
05 FILLER PIC X(75) VALUE SPACES.

LINKAGE SECTION.

01 LINKAGE-POINTERS USAGE COMP.
05 FILLER PIC S9(08).

PROCEDURE DIVISION.

***************************************
* MAINLINE ROUTINE
****************************************

PERFORM 100-INITIALIZE THRU 100-EXIT.

** ** (TO MAKE PROGRAM LOOP UNTIL "X" IS ENTERED ON SCREEN) **
PERFORM 200-MAIN-LOOP THRU 200-EXIT
UNTIL EOJ-FLAG = 'Y'.

** ** PERFORM 200-MAIN-LOOP THRU 200-EXIT.

**

EXEC CICS RETURN
END-EXEC.

GOBACK.

*****************************************
* SUB-ROUTINES USED IN MAINLINE
*****************************************

100-INITIALIZE.

MOVE ' ' TO EOJ-FLAG.
EXEC CICS ENTER TRACEID(001) END-EXEC.
MOVE 2 TO LANGUAGE-INDICATOR.
EXEC CICS ENTER TRACEID(002) END-EXEC.
CALL 'IFPREP' USING COMPLETION-CODE
COMPLETION-DETAIL
PROCESS-IDENTIFIER
LANGUAGE-INDICATOR
DATA-LENGTH.

IF COMPLETION-CODE > 1
MOVE 'Y' TO EOJ-FLAG.

100-EXIT. EXIT.

200-MAIN-LOOP.

EXEC CICS ENTER TRACEID(003) END-EXEC.
CALL 'IFRECV' USING COMPLETION-CODE
COMPLETION-DETAIL
PROCESS-IDENTIFIER
RECV-AREA
RECV-AREA-LENGTH.

IF COMPLETION-CODE > 1
MOVE 'Y' TO EOJ-FLAG
GO TO 200-EXIT.

COMPUTE SEND-VALUE =
RECV-VALUE-1 + RECV-VALUE-2.

EXEC CICS ENTER TRACEID(004) END-EXEC.
CALL 'IFSEND' USING COMPLETION-CODE
COMPLETION-DETAIL
PROCESS-IDENTIFIER
SEND-AREA
SEND-AREA-LENGTH.

IF COMPLETION-CODE > 1
MOVE 'Y' TO EOJ-FLAG.

200-EXIT. EXIT.


==CMS TPROCESS communication==

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

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

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

===Requirements for using CMS TPROCESS===

<var class="product">Model 204</var> supports communication between a User Language request and one concurrent CMS partner process, subject to these restrictions: 
<ol>
<li>In the discussion that follows, it is assumed that the user is accessing <var class="product">Model 204</var> through IUCV and through the CMS full screen interface (IODEV=41).</li>

<li>The <var class="product">Model 204</var> environment, as the target of a subcommand, must be explicitly established with the ADDRESS command in REXX, or the &PRESUME or &SUBCOMMAND commands in EXEC2.</li>

<li>The CMS partner process must be written in System Product Interpreter language (REXX) or EXEC2. The partner process communicates through the standard CMS SUBCOM interface, which is supported by these languages.</li>

<li>CMS must be at z/VM/SP Release 3, or later.</li>

<li>The user interface module (M204USER), invoked by the M204 command, must be installed as either a saved segment or a Nucleus Extension. </li>
</ol>

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

See the description of the M204 EXEC in the <var class="book">[http://www.rocketsoftware.com/m204/products/model204/documentation/v7r4/M204-System-Mgr/view Rocket Model 204 System Manager's Guide]</var> for more information about invoking the user interface module. 

==CMS TPROCESS subcommands==

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

===Subcommand summary===
<table>
<caption>CMS TPROCESS subcommands</caption>
<tr class="head">
<th>Subcommand</th>
<th>Description</th>
</tr>

<tr>
<td>IFEXTRACT and IFSET</td>
<td>Allows the CMS EXEC to set session defaults and retrieve information regarding the TPROCESS conversation.</td>
</tr>

<tr>
<td>IFRECV</td>
<td>Receives data from the User Language request.</td>
</tr>

<tr>
<td>IFSENDX</td>
<td>Sends data to the User Language request.</td>
</tr>

<tr>
<td>IFSGNL</td>
<td>Signals the User Language request, interrupting the conversation.</td>
</tr>
</table>

===Return codes===

[[#Return codes|Return codes]] lists return codes defined for the subcommands. [[#CICS completion codes|CICS completion codes]] displays these codes and their corresponding completion detail values. 
<table>
<caption>Return codes CMS TPROCESS subcommands</caption>
<tr class="head">
<th>
Code</th>
<th>Completion detail value</th>
<th>
Description</th>
</tr>

<tr>
<td align="right">0 </td>
<td>Successful</td>
<td> </td>
</tr>

<tr>
<td align="right">1</td>
<td>Warning</td>
<td>Data transfer cannot have completed as expected. Refer to the completion detail variable, if one has been defined, for more information.</td>
</tr>

<tr>
<td align="right">2</td>
<td>Signal received</td>
<td>See the completion detail variable, if one has been defined, for the signal value. No data was sent/received. For IFRECV, the value of the target variable has not been changed.</td>
</tr>

<tr>
<td align="right">3</td>
<td> </td>
<td>(reserved for future use)</td>
</tr>

<tr>
<td align="right">4</td>
<td>Error</td>
<td>The subcommand did not complete successfully. See [[#CICS completion codes|CICS completion codes]] for the completion detail code.</td>
</tr>
</table>

===Individual subcommand descriptions===

The individual CMS TPROCESS subcommands are described in this section.

===IFEXTRACT===

The IFEXTRACT subcommand obtains current parameter values from the <var class="product">Model 204</var> conversation partner. 

====Syntax====

The format of the IFEXTRACT subcommand is:
IFEXTRACT parameter


where <var class="term">parameter</var> is a parameter relating to the TPROCESS conversation. For information about setting these parameters, see [[#IFSET|the IFSET subcommand]].
<table>
<tr class="head">
<th>Parameter </th>
<th>Specifies</th>
</tr>

<tr>
<td>STATUSDVAR </td>
<td>Name of the variable in which the user wants to receive completion detail codes and signal values. If this parameter is not set, completion detail codes and signal values are not provided to the user. </td>
</tr>

<tr>
<td>LANGINT </td>
<td>Interface used when setting EXEC variables.</td>
</tr>

<tr>
<td>DATALEN </td>
<td>Maximum data length in bytes that an IFSENDX or IFRECV operation can process. </td>
</tr>
</table>

====Notes and tips====

IFEXTRACT returns parameter information in either of the following forms:
<ul>
<li><var class="term">variable parametername.0 </var>specifies number of values returned (n)</li>

<li><var class="term">variables parametername.1-n</var> specifies parameter values

where parametername is STATUSDVAR, LANGINT, or DATALEN and the values returned are as shown in [[#IFEXTRACT|IFEXTRACT]].
<table>
<caption>Returned values for IFEXTRACT parameters</caption>
<tr class="head">
<th>Parameter</th>
<th>Returned value</th>
<th>Equal to:</th>
</tr>

<tr>
<td>STATUSDVAR</td>
<td>STATUSDVAR.0</td>
<td>1, if a STATUSDVAR has been set, 0 if not</td>
</tr>

<tr>
<td>STATUSDVAR</td>
<td>STATUSDVAR.1</td>
<td>Name of the current STATUSDVAR
variable, if one is set</td>
</tr>

<tr>
<td>LANGINT</td>
<td>variable LANGINT.0</td>
<td>1</td>
</tr>

<tr>
<td>LANGINT</td>
<td>variable LANGINT.1</td>
<td>Current value of LANGINT</td>
</tr>

<tr>
<td>DATALEN</td>
<td>DATALEN.0</td>
<td>1</td>
</tr>

<tr>
<td>DATALEN</td>
<td>DATALEN.1</td>
<td>Current value of DATALEN</td>
</tr>
</table>
</li>
</ul>

===IFRECV===

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

====Syntax====

The format of the IFRECV subcommand is:
IFRECV expression

Where:

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

====Examples====

In the REXX example that follows, the line enclosed by quotation marks is passed as a literal string to the <var class="product">Model 204</var> interface. The variable 'NAME' is set to the received value:
ADDRESS M204
'IFRECV NAME'
IF RC = 0 THEN
IF NAME = ABC ...


In this example, the expression 'item1 item2' is evaluated by the interpreter, and the string 'ABCDEFGH' is used as the target variable name:
ITEM2 = EFGH
ITEM1 = ABCD
'IFRECV' item1 item2
IF RC = 0 THEN
IF ABCDEFGH = 12345 ...


The target variable used in this example is &CAR:
IFRECV CAR
&IF &RC ¬= 0 &GOTO -ERROR
&IF &CAR = PINTO ...


Because the interpreter evaluates &CAR in the IFRECV command, the target variable used in this example is &MAKEMODEL: 
&CAR = &CONCAT OF MAKE MODEL
IFRECV &CAR
&IF &RC ¬= 0 &GOTO -ERROR
&IF &MAKEMODEL = PINTO


===IFSENDX===

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

====Syntax====

The format of the IFSENDX subcommand is:
IFSENDX [expression]


Where:

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

===IFSET===

The IFSET subcommand sets parameter values for the TPROCESS conversation. 

====Syntax====

The format of the IFSET subcommand is:
IFSET parameter value

Where:

<var class="term">parameter</var> is one of the parameters relating to the TPROCESS conversation. You can specify a value for either of these parameters:
<ul>
<li><var>STATUSDVAR</var>

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

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

<li><var>LANGINT</var>

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

====Setting LANGINT====

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

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

In the following example, the DIRECT setting causes the symbol <code>DATA.J</code> to receive each of the ten values specified, whereas the SYMBOLIC setting causes an array <code>DATA.1</code> through <code>DATA.10</code> to receive the values because <code>J</code> is evaluated by REXX when <var>LANGINT</var> is set to SYMBOLIC. 
DO J = 1 TO 10
'IFRECV DATA.J'
IF RC ¬=0 THEN LEAVE
END 

Refer to the <var class="book">IBM z/VM/SP System Product Interpreter Reference</var> for information about the distinction between the DIRECT and SYMBOLIC interfaces to REXX variables. 

====DATALEN cannot be set====

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

===IFSGNL===

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

====Syntax====

The format of the IFSGNL subcommand is:
IFSGNL [expression]

Where:

<var class="term">expression</var> is optional and, if specified, must resolve to an integer value in the range -2,147,483,648 through +2,147,483,647. If no expression is coded, the default value is 0. 

====Notes and tips====

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

==CMS TPROCESS example==

In this example, the SOUL request communicates with a CMS EXEC using the SEND and RECEIVE statements. The purpose of the example is to copy (or "upload") a CMS file into a <var class="product">Model 204</var> file.
*
* THE DEFINE COMMANDS USUALLY ARE IN THE USER ZERO STREAM.
* OTHERWISE, THE SYSTEM MANAGER IS NEEDED.
* THEY ARE SHOWN HERE FOR DOCUMENTATION PURPOSES.
* NOTICE THE REQUIRED OPEN LINK COMMAND.
* ONCE OPENED, THE LINK REMAINS OPEN UNTIL EXPLICITLY
* CLOSED BY AN EOJ OR BY THE FORCE OPTION OF THE CLOSE LINK
* COMMAND.
*
DEFINE LINK LINK11 WITH SCOPE=SYSTEM -
TRANSPORT=TERMINAL PROTOCOL=MASTER

DEFINE PROCESSGROUP PGRP11 WITH SCOPE=SYSTEM -
LINK=LINK11 TERMINAL=LOCAL

DEFINE PROCESS UPLOAD WITH SCOPE=SYSTEM DATALEN=255 -
MODE=EXEC DESTINATION=PGRP11 PARTNER=DBASE3

OPEN LINK LINK11
*
* UPLOAD RECORDS FROM A CMS FILE.
* RESTRICTION: THE MAXIMUM LENGTH OF ANY LINE IS 255.
*
BEGIN
%DATA STRING LEN 255
%FN STRING COMMON
%CNT FIXED COMMON
*
%CNT = 0
%FN = $READ('CMS FILE NAME TYPE MODE')
OPEN PROCESS UPLOAD

IF $STATUS NE 0 THEN
CALL EXIT ('ATTACHING TO REXX PROGRAM')
END IF

SEND %FN TO UPLOAD

IF $STATUS NE 0 THEN
CALL EXIT ('SENDING FILENAME TO REXX PROGRAM')
END IF
REPEAT
RECEIVE %DATA FROM UPLOAD
IF $STATUS NE 0 THEN
*
* END OF FILE IF SIGNAL 0 ISSUED:
*
IF $STATUS EQ 2 AND $STATUSD EQ 0 THEN
CALL EXIT('')
END IF
*
* OTHERWISE, THIS IS A TERMINATING ERROR:
*
CALL EXIT ('RECEIVING RECORD FROM REXX PROGRAM')
END IF
%CNT = %CNT + 1
STORE RECORD
ID = 'UPLOAD'
DATA = %DATA
END STORE
END REPEAT
*
* SUBROUTINE TO EXIT THE UPLOAD OPERATION, WITH OPTIONAL
* ERROR MESSAGE:
*
SUBROUTINE EXIT (%MSG STRING LEN 40)
%EM STRING LEN 80
%FN STRING COMMON
%CNT FIXED COMMON
*
* SAVE INDICATORS BEFORE CLOSING PROCESS:
*
%ST = $STATUS
%STD = $STATUSD
%EM = $ERRMSG
CLOSE PROCESS UPLOAD

PRINT %CNT AND 'RECORDS UPLOADED FROM CMS FILE' AND %FN

*
* IF THIS IS AN ERROR EXIT, PRINT ERROR INDICATORS:
*
IF %MSG NE <nowiki>''</nowiki> THEN
PRINT 'ERROR' AND %MSG
PRINT 'STATUS' AND %ST AND 'DETAIL' AND %STD
PRINT 'ERROR MESSAGE:' AND %EM
END IF
STOP
END


===CMS partner===

The following sample CMS EXEC could communicate with the above SOUL request to upload a file:
/* Upload file to SOUL */
'MAKEBUF'
buf = rc

/* Tell M204 the name of statusdvar, and get the file id: */
address M204 'IFSET STATUSDVAR statusdvar'
address M204 'IFRECV fileid'
if rc ¬= 0 then call exit 'receiving fileid,
from SOUL'

/* Stack the records from the file: */
qd = queued()
'EXECIO * DISKR' fileid'(FIFO FINIS'
if rc ¬= 0 then call exit 'reading CMS file' fileid

/* Send the records to User Language: */
do i = 1 to queued() - qd
parse pull line
address M204 'IFSENDX' line
if rc ¬= 0 then
call exit 'sending line' i 'of CMS file' fileid ',
to User Language'
end

/* Send signal indicating successful end of file: */
address M204 'IFSGNL 0'

exit

/* Exit with error message: */
exit:
parse arg msg
say 'Error' msg
say 'RC' rc 'detail' statusdvar
'DROPBUF' buf
exit


==Transfer Control facility==

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

===Requirements and considerations===

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

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

==CICS Transfer Control==

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

===System manager requirements===

To use the Transfer Control facility:
<ul>
<li>The <var>[[DEFINE LINK command|DEFINE LINK]]</var>, <var>[[DEFINE PROCESSGROUP command|DEFINE PROCESSGROUP]]</var>, <var>[[DEFINE PROCESS command|DEFINE PROCESS]]</var>, and <var>[[OPEN LINK command|OPEN LINK]]</var> commands must be issued.</li>

<li>The DEFINE LINK command must specify <code>PROTOCOL=TRANSFER</code>.</li>

<li>The DEFINE PROCESS command must specify <code>MODE=XCTL</code>.</li>

<li>The CICS partner process must be a CICS program defined to CICS.
</li>
</ul>

===TRANSFER statement===

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

====Syntax====

The format of the TRANSFER statement for CICS is: 
TRANSFER [CONTROL] TO PROCESS
{processname | %variable}
[PASSING {IMAGE imagename | 'string' | %variable}]

Where:
<ul>
<li><var class="term">processname</var> refers to a partner process defined in an already issued DEFINE PROCESS command. This name also can be provided as the value of a %variable.</li>

<li>The PASSING clause identifies the data to be passed to the CICS program (the partner process). This data can be specified as an image, where <var class="term">imagename</var> is an image previously defined in an image definition. The data also can be a quoted string or a %variable.
</li>
</ul>

====Execution====

When the TRANSFER statement is executed, <var class="product">Model 204</var> first commits the current transaction with a COMMIT RELEASE statement. (For a detailed description of the COMMIT RELEASE statement, refer to [[Record level locking and concurrency control#RELEASE option|RELEASE option]].) After the transaction is committed, the following actions are performed:
<ul>
<li>The user is disconnected from <var class="product">Model 204</var>.</li>

<li>The user is transferred to the specified partner process. </li>

<li>The following <var class="product">Model 204</var> message appears in the audit trail:</li>
*** M204.1899: TRANSFER STATEMENT COMPLETE, USER DISCONNECTED


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

===Receiving the transferred data===

To receive the data passed by the User Language request, the CICS program can use instructions with the following format:
EXEC CICS HANDLE CONDITION QIDERR(label1) LENGERR(label2)

EXEC CICS READQ TS QUEUE(queue_name) X
ITEM(item_number) X
INTO(buffer) LENGTH(buffer_length)


where <var class="term">queue_name</var> is an 8-byte TS queue name made up of the string RECV followed by the terminal ID. 

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

====Example====
PROCEDURE TRANSFER.TO.CICS
*
* TRANSFER CONTROL TO A CICS PROGRAM
* THE DEFINE COMMANDS USUALLY ARE IN THE USER ZERO STREAM.
* OTHERWISE, THE SYSTEM MANAGER IS NEEDED.
* THEY ARE SHOWN HERE FOR DOCUMENTATION PURPOSES.
* NOTICE THE REQUIRED OPEN LINK COMMAND.
* ONCE OPENED, THE LINK REMAINS OPEN UNTIL EXPLICITLY
* CLOSED BY AN EOJ OR BY THE FORCE OPTION OF THE CLOSE
* LINK COMMAND.
*
DEFINE LINK LINK1 WITH SCOPE=SYSTEM TRANSPORT=TERMINAL -
PROTOCOL=TRANSFER

DEFINE PROCESSGROUP GROUP1 WITH SCOPE=SYSTEM -
LINK=LINK1

DEFINE PROCESS CICSTRAN WITH SCOPE=SYSTEM DATALEN=40 -
MODE=XCTL DESTINATION=GROUP1 PARTNER=CICSPGM

OPEN LINK LINK1
*
*
BEGIN
%TEXT IS STRING LEN 20
.
.
.
ERROR.PROC: ON ERROR
%TEXT = $ERRMSG
IF %TEXT = 'M204.1899: TRANSFER ' THEN
PRINT 'THE TRANSFER TO CICS WAS -
SUCCESSFUL.'
ELSE
PRINT 'THE TRANSFER TO CICS HAS FAILED.'
PRINT 'THE ERROR ENCOUNTERED IS: ' -
WITH $ERRMSG
END IF
END ON
.
.
.
TRANSFER CONTROL TO PROCESS CICSTRAN PASSING %PARM.DATA
.
.
.
END PROCEDURE


==SNA Communications Server Transfer Control==

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

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

When finished in the destination Online, the user can be transferred back to the original <var class="product">Model 204</var> Online or to another application in the SNA Communications Server network. 

===Terminology===

In this section:
<ul>
<li>The <var class="product">Model 204</var> Online from which a user is transferred is also referred to as the initial or transferring side, or Online. </li>

<li>The application to which a user transfers is also referred to as the receiving or destination side, Online, or application.
</li>
</ul>

===System manager requirements===

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

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

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

Security concerns are discussed in [[#Security for Model 204-to-Model 204 transfers|Security for Model 204-to-Model 204 transfers]]. 

===TRANSFER statement format and execution===

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

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

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

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

====Syntax====

The format of the TRANSFER statement is:
TRANSFER [CONTROL] TO PROCESS
{processname | %variable}
[WITH] [USERID {%variable | 'string'}]
[PASSWORD {%variable | 'string'}]
[ACCOUNT {%variable | 'string'}]
[PASSING {IMAGE imagename | 'string' | %variable}]

Where:
<ul>
<li><var class="term">processname</var> is the name of a process defined in a DEFINE PROCESS command for the transferring side. This name also can be provided as the value of a %variable.</li>

<li>USERID specifies the user ID of the user that is being transferred.

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

If USERID is specified, the Transfer Control facility assumes that the transfer is to another <var class="product">Model 204</var> Online, and it automatically formats and encrypts a LOGON command string for the destination Online. For more information about this formatting, see [[#Login command line formatting|Login command line formatting]].

USERID can also be provided as the value of a %variable. 
</li>

<li>PASSWORD specifies the password to be included in the LOGON command string sent to the <var class="product">Model 204</var> destination Online.

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

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

Unlike the account and user ID, the current user password is not available in decrypted form to a <var class="product">Model 204</var> Online. If sending a password is appropriate, the User Language request must supply it. 
</li>

<li>ACCOUNT specifies the account value to be included in the LOGON command string sent to the <var class="product">Model 204</var> destination Online.

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

ACCOUNT can also be provided as the value of a %variable. 
</li>

<li>The PASSING clause identifies the data to be passed to the destination SNA Communications Server application.

PASSING data can be specified as an image, where <var class="term">imagename</var> is an image previously defined in an image definition. The data also can be a quoted string or a %variable. 

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

Be sure that only <var class="product">Model 204</var> commands are entered in the PASSING data when transferring to another <var class="product">Model 204</var> Online.
</li>
</ul>

====Execution====

When the request containing the TRANSFER statement is executed, the user is disconnected from <var class="product">Model 204</var> on the transferring side and transferred to the destination application. The following events are included:
<ul>
<li>Transparent to the user, <var class="product">Model 204</var> issues an OPEN PROCESS in preparation for the transfer. </li>

<li>The user stays connected to the initial <var class="product">Model 204</var> Online until that Online receives notification that a session is established with the destination SNA Communications Server application. Depending on the notification, the following actions are performed:
</li>
</ul>

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

If the time waiting on notification exceeds the time specified on the TIMEOUT option of the DEFINE PROCESS command, the user is disconnected from the initial <var class="product">Model 204</var> Online and returned to SNA Communications Server. 

If the notification is that the session is established with the destination SNA Communications Server application, the user is disconnected from the initial <var class="product">Model 204</var> Online and transferred to the specified destination. 
<ul>
<li>Before the disconnection preceding a transfer, <var class="product">Model 204</var> commits the current transaction with a COMMIT RELEASE statement. (For a detailed description of the COMMIT RELEASE statement, refer to [[Record level locking and concurrency control#RELEASE option|RELEASE option]].)

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

<li>The following <var class="product">Model 204</var> message appears in the audit trail:</li>
*** M204.1899: TRANSFER STATEMENT COMPLETE, USER DISCONNECTED


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

===Login command line formatting===

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

A transfer that enables login of a user without a password is called trusted. No password is formatted in the passed command line nor checked for at the receiving side: the receiving Online trusts that the transferring Online has verified the user's password and allows the user to log in without a password.
This feature is also used by the <var class="product">Model 204</var> product Horizon, and is described in detail in the
<var class="book">Rocket Model 204 Horizon: Intersystem Processing Guide</var>. 
Note: The exception to the previous feature is SNA Communications Server Transfer Control does not support Guest User that is used by Horizon.

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

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

====Components of transferred data====

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

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

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

====Components of formatted login string====

If the transfer is trusted, the encrypted login string contains this information: 
VTAM applid, LOGON userid, processgroupname

Where:
<ul>
<li>SNA Communications Server applid is the transferring side's SNA Communications Server applid (User 0 parameter VTAMNAME value). This value must be the same as the receiving side's DEFINE PROCESSGROUP command REMOTEID parameter. </li>

<li>LOGON is the <var class="product">Model 204</var> LOGON command.</li>

<li><var class="term">userid</var> is the user ID to be logged in at the destination Online. If UIDSOURCE=CURRENT, the transferring user's current user ID is used. If UIDSOURCE=OPEN, the user ID specified on the TRANSFER statement USERID parameter is used. </li>

<li><var class="term">processgroupname</var> is the name set in the receiving side's processgroup definition. This name must be the same as the value of the transferring side's DEFINE PROCESS command PARTNER parameter. </li>
</ul>

If the transfer is non-trusted, the encrypted string can contain this information: 
VTAM applid, LOGON userid, password

Where:
<ul>
<li>SNA Communications Server <var class="term">applid</var> is as defined above. However, this value is not checked if the transfer is non-trusted.</li>

<li>LOGON and <var class="term">userid</var> are as defined above.</li>

<li>password is the transferring user's. It is obtained from the TRANSFER statement PASSWORD parameter, if coded. If no PASSWORD is coded, the user is prompted for one at the destination Online.
</li>
</ul>

====Controlling login string formatting====

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

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

====Trusted transfers====

Trusted transfers are possible between <var class="product">Model 204</var> Onlines that have LOGIN=TRUST on both DEFINE PROCESSGROUPs. 
<ol>
<li>Pass an automatically formatted login string with no password at the time of transfer along with whatever PASSING data is entered.
<ul>
<li>Make sure LOGIN=TRUST is specified on both DEFINE PROCESSGROUPs; LOGIN=NOTRUST is the default.</li>

<li>Make sure the receiving side's DEFINE PROCESSGROUP command REMOTEID parameter is set to the SNA Communications Server applid of the transferring side. </li>

<li>Make sure the transferring side's DEFINE PROCESS command PARTNER parameter is set to the processgroup name of the receiving side. </li>

<li>Indicate automatic formatting. Set the transferring side's DEFINE PROCESS command UIDSOURCE parameter to a value other than the default, NONE. UIDSOURCE=NONE prevents automatic login formatting. </li>

<li>Indicate where to get the user ID. If UIDSOURCE=CURRENT, the transferring user's current user ID is used. If UIDSOURCE=OPEN, the user ID specified on the TRANSFER statement USERID parameter is used.</li>
</ul>

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

====Non-trusted transfer options====

Non-trusted transfers are between <var class="product">Model 204</var> Onlines that have LOGIN=NOTRUST set on either of the DEFINE PROCESSGROUP commands. Formatting options follow:
<ol>
<li>Pass an automatically formatted login string along with PASSING data.
<ul>
<li>Indicate automatic formatting. Set the transferring side's DEFINE PROCESS command UIDSOURCE parameter to a value other than the default, NONE. UIDSOURCE=NONE prevents automatic login formatting. </li>

<li>Indicate where to get the user ID. If UIDSOURCE=CURRENT, the transferring user's current user ID is used. If UIDSOURCE=OPEN, the user ID specified on the TRANSFER statement USERID parameter is used. </li>

<li>Indicate where to get the password. Provide for one either in the automatically formatted login string (code the TRANSFER statement PASSWORD parameter) or by entering it in response to a prompt at the receiving side. </li>
</ul></li>

<li>Have no automatic login string formatted. This is the default option.</li>
</ol>

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

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

Include any login information in the PASSING data.

====Coordinating TRANSFER and DEFINE PROCESS parameters====

The options selected in the DEFINE PROCESS and TRANSFER CONTROL statement determine whether the Transfer Control facility automatically formats a <var class="product">Model 204</var> login data string. 

[[#Login command line formatting|Login command line formatting]] shows the resulting determination for the DEFINE PROCESS and TRANSFER CONTROL combinations. The values in the table have the following meanings: 
<table class="thJustBold">
<tr>
<th>DPU</th>
<td>Depends if USERID is set or not </td>
</tr>

<tr>
<th>ERR</th>
<td>Cancel request and issue error message</td>
</tr>

<tr>
<th>N/A</th>
<td>Not applicable </td>
</tr>

<tr>
<th>NO</th>
<td>No automatic formatting; assume transfer is to a non-<var class="product">Model 204</var> SNA Communications Server
application</td>
</tr>

<tr>
<th>YES</th>
<td>Automatically format login data</td>
</tr>
</table>

===Security for Model 204-to-Model 204 transfers===

SNA Communications Server Transfer Control enables transfer from one <var class="product">Model 204</var> Online to another without the necessity of entering a password at the destination Online. To be sure that such a transfer is secure, the Transfer Control facility has security measures to control: 
<ul>
<li>The users who can access the destination <var class="product">Model 204</var> Online </li>

<li>The system from which a user can transfer </li>

<li>The format of the passed data
</li>
</ul>

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

====User access protection====

The Transfer Control facility uses <var class="product">Model 204</var> login and subsystem security to facilitate and secure the access of a transferred user to the receiving <var class="product">Model 204</var> system. 

Login security ordinarily ensures that a user has a valid user ID and, if included, a valid password. Transfer Control uses the <var class="term">trusted partner</var> feature, which enables login of a transferred user without a password. 

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

For more information about login privileges, see the login security description in
[[DEFINE PROCESSGROUP command: Transfer Control]]
and see [[Security#Subsystem_security|Subsystem_security]]. 
Note: Only ACF2 is supported for Trusted Login; Security Server (formerly RACF) and Top Secret are not. Also, Guest User is not supported for SNA Communications Server Transfer Control. 

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

====System-level protection====

DEFINE command parameter settings at both <var class="product">Model 204</var> systems participating in a trusted transfer must be coordinated to enable an automatic login upon transfer to take place:
<ul>
<li>DEFINE PROCESSGROUP

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

<li>DEFINE PROCESS

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

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

====Command line protection====

Both trusted and non-trusted transfers between <var class="product">Model 204</var> Onlines can include an accompanying automatically formatted LOGIN command string. Whether this automatic formatting occurs depends on the parameter options set on the TRANSFER statement and on the transferring side's DEFINE PROCESS command. For more information about this automatic formatting, see [[#Login command line formatting|Login command line formatting]]. 

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

===$REMOTE for transferring back===

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

====Syntax====

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

====Operation====

In the discussion that follows, the "initial side" is the <var class="product">Model 204</var> Online from which a user is transferred. The "receiving side" is the <var class="product">Model 204</var> Online to which the user is transferred.

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

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

<li>TRANSFER statement

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

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

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

====Example====

In the following example, a user has been transferred into a <var class="product">Model 204</var> Online with SNA Communications Server applid M204B, from a <var class="product">Model 204</var> Online with SNA Communications Server applid M204A. Using the following DEFINE commands and User Language request, the user is transferred back to the initial <var class="product">Model 204</var> Online, M204A, logged in with the current user ID and trusted password, and placed into an APSY subsystem called INQUIRY. 
*
* Network Definitions for M204B, the
* destination Online:

DEFINE LINK M204BL WITH SCOPE=SYSTEM -
PROTOCOL=TRANSFER -
TRANSPORT=TERMINAL

DEFINE PROCESSGROUP M204BPG WITH SCOPE=SYSTEM -
LINK=M204BL -
REMOTEID=M204A -
LOGIN=TRUST

DEFINE PROCESS M204A WITH SCOPE=SYSTEM -
PARTNER=M204APG -
DESTINATION=M204BPG -
DATALEN=100 -
MODE=PASS -
UIDSOURCE=CURRENT

*
*
* Opening of the link:

OPEN LINK M204BL
*


The User Language statements for transferring back to M204A follow:
BEGIN
.
.
.
%PROCSNAME = $REMOTE
%DATA = 'INQUIRY'
.
.
.
TRANSFER CONTROL TO PROCESS %PROCSNAME -
PASSING %DATA
.
.
.
END

When a transfer fails

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

===Error handling===

Error conditions during SNA Communications Server transfers are listed below followed by their remedies.
<ul>
<li>The session is not established when attempting transfer to a SNA Communications Server application, and the user is left in native SNA Communications Server.

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

<li>The TIMEOUT parameter is a safeguard against a terminal hang while establishing the session with the destination SNA Communications Server application.
</li>

<li>An incorrect password or user ID is passed to the destination Online with the transfer, and the user is left at command level in the destination Online.

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

<li>After the user is logged in at the destination <var class="product">Model 204</var> Online, an error occurs while the rest of the command string is being processed; the user is left at command level in the destination Online.

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

A User Language request can use the SNA Communications Server applid of the initial Online to transfer the user back to that Online, as described on [[#$REMOTE for transferring back|$REMOTE for transferring back]]. 
</li>
</ul>

==SNA Communications Server Transfer Control examples==

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

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

The transfer is to a SNA Communications Server application other than <var class="product">Model 204</var>. The user is logged out of <var class="product">Model 204</var> and transferred into the SNA Communications Server application ANYAPPL. For the side initiating the transfer: 
* Network definitions

DEFINE LINK TRANF1 WITH SCOPE=SYSTEM -
PROTOCOL=TRANSFER -
TRANSPORT=TERMINAL

DEFINE PROCESSGROUP TRANF1PG WITH SCOPE=SYSTEM -
LINK=TRANF1 -
REMOTEID=ANYAPPL

DEFINE PROCESS TRANF1PR WITH SCOPE=SYSTEM -
DESTINATION=TRANF1PG -
PARTNER=ANYAPPL -
DATALEN=100 -
MODE=PASS

* Link opening

OPEN LINK TRANF1

* User Language

BEGIN
.
.
%DATA='TRANSFERRED FROM A MODEL204 ONLINE'
TRANSFER CONTROL TO PROCESS TRANF1PR PASSING %DATA
.
.
.
END


====Comments====

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

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

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

DEFINE LINK TRANF1 WITH SCOPE=SYSTEM -
PROTOCOL=TRANSFER -
TRANSPORT=TERMINAL

DEFINE PROCESSGROUP TRANF1PG WITH SCOPE=SYSTEM -
LINK=TRANF1 -
REMOTEID=M204B

DEFINE PROCESS TRANF1PR WITH SCOPE=SYSTEM -
DESTINATION=TRANF1PG -
PARTNER=M204B -
DATALEN=100 -
MODE=PASS
* Link opening

OPEN LINK TRANF1

* User Language

BEGIN
.
.
%DATA='LOGON USERID;PASSWORD;OPEN PROCFILE; -
I PROC'
.
.
TRANSFER CONTROL TO PROCESS TRANF1PR PASSING -
%DATA
.
.
END


====Comments====

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

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

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

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

DEFINE LINK TRANF1 WITH SCOPE=SYSTEM -
PROTOCOL=TRANSFER -
TRANSPORT=TERMINAL

DEFINE PROCESSGROUP TRANF1PG WITH SCOPE=SYSTEM -
LINK=TRANF1 -
REMOTEID=M204B

DEFINE PROCESS TRANF1PR WITH SCOPE=SYSTEM -
DESTINATION=TRANF1PG -
PARTNER=M204B -
DATALEN=100 -
MODE=PASS -
UIDSOURCE=CURRENT

* Link opening

OPEN LINK TRANF1

* User Language

BEGIN
.
.
%PSWD=$READ('ENTER PASSWORD')
.
.
%DATA='OPEN MYFILE;I MYPROC'
.
.
TRANSFER CONTROL TO PROCESS TRANF1PR WITH -
PASSWORD %PSWD PASSING %DATA
.
.
END


====Comments====

The LOGON command line has the format: 
'LOGON currentuserid;password;OPEN MYFILE;I MYPROC'


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

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

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

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

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

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

The user transfers from a <var class="product">Model 204</var> Online to another <var class="product">Model 204</var> Online. The system managers have set both <var class="product">Model 204</var> Onlines to LOGIN=TRUST. The user is transferred without a password. For M204A, the side initiating the transfer: 
* Network definitions

DEFINE LINK M204AL WITH SCOPE=SYSTEM -
PROTOCOL=TRANSFER -
TRANSPORT=TERMINAL

DEFINE PROCESSGROUP M204APG WITH SCOPE=SYSTEM -
LINK=M204AL -
REMOTEID=M204B -
LOGIN=TRUST

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

* Link opening

OPEN LINK M204AL


For M204B, the Online to which the user is transferred:
* Network definitions

DEFINE LINK M204BL WITH SCOPE=SYSTEM -
PROTOCOL=TRANSFER -
TRANSPORT=TERMINAL

DEFINE PROCESSGROUP M204BPG WITH SCOPE=SYSTEM -
LINK=M204BL -
REMOTEID=M204A -
LOGIN=TRUST

DEFINE PROCESS M204BPR WITH SCOPE=SYSTEM -
PARTNER=M204APG -
DESTINATION=M204BPG -
DATALEN=100 -
MODE=PASS -
UIDSOURCE=CURRENT

* Link opening

OPEN LINK M204BL

* User Language

BEGIN
.
.
%DATA='OPEN FILE;I PROC'
.
.
TRANSFER CONTROL TO PROCESS M204APR PASSING %DATA
.
.
END


====Comments====

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

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

The user is logged into M204B without a password for two reasons:
<ul>
<li>M204A knows the trusted processgroup name of M204B (PARTNER=M204BPG).</li>

<li>M204B's processgroup M204BPG is set with REMOTEID equal to M204A's SNA Communications Server applid and LOGIN=TRUST.
</li>
</ul>

Since the transfer to M204B is to a trusted <var class="product">Model 204</var> Online, the LINK and PROCESSGROUP definitions for that Online are necessary. The PROCESS definition for that Online is optional unless a transfer out of that Online is anticipated.

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

===Example 5: From trusted to non-trusted Model 204===

The user transfers from a trusted <var class="product">Model 204</var> Online to a non-trusted <var class="product">Model 204</var> Online. The user is prompted for a password in the destined Online, after which the rest of the login data string is acted upon. For M204A, the side initiating the transfer: 
* Network definitions

DEFINE LINK M204AL WITH SCOPE=SYSTEM -
PROTOCOL=TRANSFER -
TRANSPORT=TERMINAL

DEFINE PROCESSGROUP M204APG WITH SCOPE=SYSTEM -
LINK=M204AL -
REMOTEID=M204B -
LOGIN=TRUST

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

* Link opening

OPEN LINK M204AL


For M204B, the Online to which the user is transferred:
* Network definitions

DEFINE LINK M204BL WITH SCOPE=SYSTEM -
PROTOCOL=TRANSFER -
TRANSPORT=TERMINAL

DEFINE PROCESSGROUP M204BPG WITH SCOPE=SYSTEM -
LINK=M204BL -
REMOTEID=M204A -
LOGIN=NOTRUST

* Link opening

OPEN LINK M204BL

* User Language

BEGIN
.
.
%UID=$READ('ENTER USERID')
.
.
%DATA='OPEN FILE;I PROC'
.
.
TRANSFER CONTROL TO PROCESS M024APR WITH USERID -
%UID PASSING %DATA
.
.
END


====Comments====

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

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

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

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

==Horizon==

This section provides a brief overview of the optional distributed application facility, Horizon, and the User Language statements that support it.
The <var class="book">Rocket Model 204 Horizon: Intersystem Processing Guide</var>
provides detailed information on using Horizon. This information includes syntax and usage description for the User Language statements and <var class="product">Model 204</var> commands, as well as information relating to the installation and use of a Horizon network.

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

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

===Horizon verbs are Model 204 commands and User Language statements===

The LU 6.2 conversation rules are enforced by software that consists of a group of instructions, or verbs, that control the maintenance of the network and the interactions between conversation partners. The <var class="product">Model 204</var> LU 6.2 interface, Horizon, is a collection of <var class="product">Model 204</var> commands and User Language statements:
<ul>
<li>The <var class="product">Model 204</var> commands define and control a network that includes the host <var class="product">Model 204</var> program.</li>

<li>The User Language statements correspond to LU 6.2 conversation verb definitions and govern conversations between the host <var class="product">Model 204</var> program and other partner <var class="product">Model 204</var> or non-<var class="product">Model 204</var> programs. </li>
</ul>

Horizon uses variations of several of the User Language statements and <var class="product">Model 204</var> commands that are used with the TPROCESS facility (discussed on [[#User Language TPROCESS communication|User Language TPROCESS communication]]). 

LU 6.2 security considerations slightly affect some SUBSYSMGMT screens
(see the
<var class="book">[http://www.rocketsoftware.com/m204/products/model204/documentation/v7r4/M204-System-Mgr/view Rocket Model 204 System Manager's Guide]]</var>)
and the <var class="book">Rocket Model 204 Security Interfaces Manual</var>. 

===User Language interface===

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

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

====OPEN PROCESS statement====

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

There are two distinct uses of the OPEN PROCESS statement:
<ul>
<li>The client process uses OPEN PROCESS to allocate an outbound conversation; that is, to invoke a server process. Allocation involves creating control blocks, getting control of a session for the conversation, and requesting the initiation of the server process at the remote site with optional initialization parameters.</li>

<li>The server process uses OPEN PROCESS to identify an inbound conversation. An inbound OPEN PROCESS statement (that is,
OPEN PROCESS with the ACCEPT operand) can be issued only by a server process. Its purpose is to get any initialization parameters specified in the initiation of the conversation by the client process. </li>
</ul>

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

====CONFIRM statement====

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

====CONFIRMED statement====

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

====CLOSE PROCESS statement====

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

====FLUSH PROCESS statement====

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

====INVITE statement====

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

====QUERY PROCESS statement====

The QUERY PROCESS statement returns information about a conversation. The information returned depends on the parameters specified; the types of information include: 
<ul>
<li>Current conversation state of the conversation</li>

<li>Name of the process group associated with the conversation</li>

<li>Name of the LU at which the remote process is located</li>

<li>Level of synchronization processing used for the conversation (that is, whether confirmation processing is allowed)</li>

<li>Mode name for the session that the conversation is using</li>
</ul>

====RECEIVE statement====

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

====SIGNAL PROCESS statement====

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

====SEND statement====

The SEND statement transmits data to the remote process. 

====SEND ERROR statement====

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

====TEST RECEIPT statement====

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

====WAIT FOR RECEIPT statement====

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

==BATCH2 facility==

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

The BATCH2 utility program reads a user-specified input data stream and transmits this data to the <var class="product">Model 204</var> Online. The resulting output generated by the Online is written to a user-specified output data stream. 

You can set a job-step return code in BATCH2 jobs. In addition to the abnormal termination error codes, 300 and 600, BATCH2 now returns a user's return code to the job step or exec. 
<table>
<tr class="head">
<th>If BATCH2... </th>
<th>Return code value is...</th>
</tr>

<tr>
<td>Completes normally </td>
<td>

Highest return code received by the user of the BATCH2 thread. 

Unlike in a single user job, this value is independent of the highest return code value for the entire Online job. 

When invoking BATCH2, the job-step or exec specifies the type of return code to return: a batch or Online value.
</td>
</tr>

<tr>
<td nowrap>Terminates abnormally </td>
<td>Same completion codes as in previous releases, 300 or 600. These are return codes for the BATCH2 job itself and are not user values.</td>
</tr>
</table>

====Usage notes====
<ul>
<li>The return code is specific to each user. If the User Language stream in the BATCH2 CCAIN file logs on more than one user, the value returned is for the last user logged on; it is not the highest return code received by any other user of the thread.</li>

<li>If a user runs as a connected but not logged on user (that is, no user was logged on in the CCAIN stream), then BATCH2 returns no user return code; the return code is 0.</li>

<li>BATCH2 logs the user out of <var class="product">Model 204</var> when it reaches the end of the CCAIN stream. If the LOGOUT command is explicitly entered in the CCAIN stream, then no user is logged on when BATCH2 terminates and issues its final LOGOUT. In this case the return code is not available to BATCH2 and the return code is 0. Therefore, to obtain the BATCH2 return code, do not enter the LOGOUT command in the CCAIN stream. Also, if message M204.0353 is set to NOTERM with the MSGCTL command, return codes will not be available unless CUSTOM=6 is set.</li>

<li>$Jobcode can now be called by Online as well as batch users. This means that calls to $Jobcode can now be included in the CCAIN stream. See [[$Jobcode#$Jobcode|$Jobcode]].</li>
</ul>

===Support required for BATCH2===
<ul>
<li>The z/OS or z/VSE BATCH2 user must access <var class="product">Model 204</var> with an IODEV=29 thread; a CMS user must use an IODEV=39 thread. </li>

<li>The M204IFAM EXEC must be available on the CMS machine that is running the BATCH2 utility. </li>

<li>For z/OS and z/VSE, CRAM must be installed.</li>
</ul>

===Specifying runtime parameters===

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

====Channel name parameter====

The channel name determines the specific <var class="product">Model 204</var> Online with which BATCH2 establishes a connection. 

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

====Output Message Control (OMC) parameter====

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

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


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

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

====OMC options====

Under z/OS or CMS, you can specify the OMC parameter value, in either decimal (ddd) or hexadecimal (hh) form, as any combination of the options in [[#Specifying runtime parameters|Specifying runtime parameters]]. Values can be summed. Equivalent bit settings for z/VSE are shown in [[#z/VSE JCL using BATCH2|z/VSE JCL using BATCH2]].
<table>
<caption>OMC parameter options</caption>
<tr class="head">
<th>Decimal (ddd)</th>
<th>Hexadecimal (hh)</th>
<th>Discards...</th>
</tr>

<tr>
<td align="right">128</td>
<td align="right">X'80'</td>
<td>Class E messages (error messages)</td>
</tr>

<tr>
<td align="right">64</td>
<td align="right">X'40'</td>
<td>New page indicator (page eject)</td>
</tr>

<tr>
<td align="right">32</td>
<td align="right">X'20'</td>
<td>This job, if the user is restarted</td>
</tr>

<tr>
<td align="right">16</td>
<td align="right">X'10'</td>
<td>Nondisplay input prompt messages</td>
</tr>

<tr>
<td align="right">8</td>
<td align="right">X'08'</td>
<td>$READ prompt messages</td>
</tr>

<tr>
<td align="right">4</td>
<td align="right">X'04'</td>
<td>Class I messages (informational messages)</td>
</tr>
</table>

The default value for the OMC parameter is zero, which results in these actions:
<ul>
<li>All messages are written to the CCAOUT data stream.</li>

<li>The new page requests are honored with a page eject.</li>

<li>The user restarted condition is ignored. </li>
</ul>

====User return code (URCTYPE) parameter====

The URCTYPE parameter specifies the type of return code that BATCH2 returns to the job-step or exec that invoked the utility. The parameter is a single character:
<table>
<tr class="head">
<th>Value </th>
<th> Returns</th>
</tr>

<tr>
<td>N (default) </td>
<td>Zero (0) and is equivalent to omitting the parameter </td>
</tr>

<tr>
<td>O </td>
<td>Online value</td>
</tr>

<tr>
<td>B </td>
<td>Batch value</td>
</tr>
</table>

===Input and output data streams===

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

====Specifying input stream characteristics====

CCAIN defines the input data stream to be transmitted to the <var class="product">Model 204</var> ONLINE. BATCH2 reads this data stream and transmits each record to the ONLINE. 

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

====Specifying output stream characteristics====

CCAOUT defines where the output data stream, the output generated for this user from the <var class="product">Model 204</var> Online, is written. BATCH2 receives the output from the Online and writes each record to the output data stream. 

Because BATCH2 emulates a line-by-line terminal, the values of the User 0 parameters <var>[[OUTMRL parameter|OUTMRL]]</var> and <var>[[OUTCCC parameter|OUTCCC]]</var> for this thread determine, respectively, the maximum length of the output line and the continuation character position.

====Using *DEVICE command in BATCH2 jobs====

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

If an input line begins with *DEVICE, followed by a number, a comma, and another number, the first number is used to change the value used for OUTMRL and the second is used to change OUTLPP. 
Note: The values of OUTMRL and OUTLPP (as returned by the VIEW command) are not actually updated, however, until the RESET command is issued.

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

====Syntax====

The format of the *DEVICE command is:
*DEVICE n1,n2


where <var class="term">n1</var> specifies characters per line, and <var class="term">n2</var> specifies lines per page. 

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


You do<var> not</var> need to be logged in to issue this command. 

===z/OS JCL using BATCH2===

This example shows sample JCL for a job that uses the BATCH2 facility running under z/OS. 
// JOB
//RUN EXEC PGM=BATCH2,
// PARM='TESTM204,OMC=64,URCTYPE=B'
//STEPLIB DD DSN=LOCAL.M204.LOAD,DISP=SHR
//CCAOUT DD SYSOUT=C
//CCAIN DD *
LOGIN user ID
password
OPEN file
.
.
.
CLOSE ALL
LOGOUT
//


====Syntax====

The format of the PARM option on the EXEC statement is:
PARM='[channel][,[OMC={X''hh'' | ddd}]
[,URCTYPE={N | O | B}]]'

Where:
<ul>
<li><var class="term">channel</var> is the Online region channel name. If channel is not specified, the name defaults to M204PROD. </li>

<li>OMC is the keyword which specifies the Output Message Control parameter. You can specify the OMC value in either hh or ddd form. If you do not specify a value, OMC defaults to 0. </li>

<li><var class="term">hh</var> is a hex value from 00 to FF.</li>

<li><var class="term">ddd</var> is a decimal value from 0 to 255.</li>

<li>URCTYPE is the keyword that specifies the type of return code.</li>
</ul>

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

====PARM option examples====
<ul>
<li>In this example, the PARM= option specifies a channel name of TESTM204 and a hex value of 'F0' (the default) for the OMC parameter.
// PARM='TESTM204,OMC=X''F0'''
</li>

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

===z/VSE JCL using BATCH2===

The following example-syntax shows JCL for a job that uses the BATCH2 utility running under z/VSE. 
// JOB BATCH2
// DLBL M204LIB,'M204.PROD.LIBRARY'
// EXTENT ,SYSnnn, balance of extent information
// LIBDEF PHASE.SEARCH=M204LIB.V4R2
// DLBL CCAOUT,'M204.BATCH2.CCAOUT'
// EXTENT SYSnnn, balance of extent information
// UPSI bbbbbbbb
// OPTION SYSPARM='channel'
// EXEC BATCH2,SIZE=AUTO, PARM='channel,urctype'
LOGIN user ID
password
OPEN file
.
.
.
CLOSE ALL
LOGOUT
/*
/&

Where:
<ul>
<li><var class="term">bbbbbbbb</var> in the UPSI statement in the preceding example is the Output Message Control (OMC) parameter in bits. If you do not specify a value, OMC defaults to all zeroes. In z/VSE, you can specify the OMC parameter as a combination of the option bits shown in [[#z/VSE JCL using BATCH2|z/VSE JCL using BATCH2]]:
<table>
<caption>z/VSE OMC parameter options</caption>
<tr class="head">
<th>Setting</th>
<th>Description</th>
</tr>

<tr>
<td align="right">10000000</td>
<td>Discard class E messages (error messages)</td>
</tr>

<tr>
<td align="right">01000000</td>
<td>Ignore new page indicator (page eject)</td>
</tr>

<tr>
<td align="right">00100000</td>
<td>If the user is restarted, terminate this job</td>
</tr>

<tr>
<td align="right">00010000</td>
<td>Discard nondisplay input prompt messages</td>
</tr>

<tr>
<td align="right">00001000</td>
<td>Discard $READ prompt messages</td>
</tr>

<tr>
<td align="right">00000100</td>
<td>Discard class I messages (informational messages)</td>
</tr>
</table>
</li>

<li><var class="term">channel</var> in the OPTION SYSPARM statement in the preceding example is the Online partition channel name. If channel is not specified, the name defaults to M204PROD. See [[#Specifying runtime parameters|Specifying runtime parameters]] for a description of channel name. </li>

<li>urctype specifies the type of return code, N, O, or B, to return the job step. See [[#Specifying runtime parameters|Specifying runtime parameters]] for return code values and meaning.</li>
</ul>

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


===CMS job using BATCH2===

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

FILEDEF CCAIN DISK BATCH2 CCAIN A
FILEDEF CCAOUT DISK BATCH2 CCAOUT A

M204BAT2 TESTM204 64 X'0' 'B'


====Syntax====

The command to execute the BATCH2 module shown in the example above is: 
M204BAT2 [channel][X'hh' | ddd]['N' | 'O' | 'B']

Where:
<ul>
<li><var class="term">channel</var> is the Online region line mode channel name set by the VMIOCHNL CCAIN parameter. If channel is not specified, the name defaults to M204VMIO. See [[#Specifying runtime parameters|Specifying runtime parameters]] for a description of channel name. </li>

<li><var class="term">hh</var> is a hex value from 00 to FF and ddd is a decimal value from 0 to 255. You can specify the OMC value in either hexadecimal (hh) or decimal (ddd) form. For a description of valid values, see [[#Specifying runtime parameters|Specifying runtime parameters]]. If no value is specified, the OMC parameter defaults to 0. </li>

<li>'N', 'O', or 'B' specifies the return value of the URCTYPE parameter. See [[#Specifying runtime parameters|Specifying runtime parameters]] for return code values and meanings.</li>
</ul>

====M204BAT2 statement examples====
<ul>
<li>In this example, the M204BAT2 statement specifies a channel name of TESTM204 and a hex value of 0 (the default) for the OMC parameter. Invoke M204BAT2 with the URCTYPE parameter in quotes:
M204BAT2 TESTM204 X'0' 'B'
</li>

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

====Using M204IFAM EXEC====

During initialization, the BATCH2 utility invokes a procedure called M204IFAM EXEC to obtain the name of the virtual machine running the <var class="product">Model 204</var> ONLINE and to obtain the needed IUCV communication method.
Note: The M204IFAM EXEC must be available on the CMS machine that is running the BATCH2 utility. 

An example of an M204IFAM EXEC is:

====Syntax====
&STACK LIFO userid IUCV

Where:
<ul>
<li><var class="term">userid</var> is the name of the virtual machine that is running the
<var class="product">Model 204</var> Online.</li>

<li>IUCV indicates the IUCV communication method.</li>
</ul>

====REXX EXEC for BATCH2====

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

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


===BATCH2 completion codes===

Upon termination, the BATCH2 facility returns a completion code. [[#BATCH2 completion codes|BATCH2 completion codes]] lists possible values:
<table>
<caption>BATCH2 completion codes</caption>
<tr class="head">
<th>Setting</th>
<th>Description</th>
</tr>

<tr>
<td align="right">0</td>
<td>Successful completion</td>
</tr>

<tr>
<td align="right">300</td>
<td>

Abnormal termination. Refer to CCAOUT for an error message.

If a completion code of 300 is returned, an error message appears in the
CCAOUT data stream. Some possible errors are:

Invalid channel name parameter value.

Invalid OMC parameter value.

CCAIN data stream could not be opened.
</td>
</tr>

<tr>
<td align="right">600</td>
<td>The CCAOUT data stream could not be opened.</td>
</tr>
</table>

==Thread signaling and synchronization facilities==

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

User Language has signaling and synchronization capabilities. A thread can: 
<ul>
<li>Send a signal that an event associated with the signal is finished</li>
<li>Wait for the signal to arrive and examine the contents of a signal</li>
</ul>

===Implementing thread signaling and synchronization in User Language===

The signal is implemented using an Event Control Block (ECB), a permanent data structure in memory that indicates the event state and user supplied data associated with the event. The ECB is shared by all threads participating in the synchronization process. 
<ul>
<li>To send a signal to a thread, a User Language application uses the $POST function, which marks the event as posted (or completed) and causes the waiting thread to wake up and resume processing. Furthermore, you can supply a numeric post code that is stored in the ECB, which may be examined by the waiting thread or threads. </li>

<li>To wait for a signal, a User Language application uses the $WAIT function that puts a thread in a wait state until the event is posted by another thread and the signal arrives. </li>
</ul>

====ECB-related functions====

Using the $POST and $WAIT functions, you can synchronize the execution of two threads. A User Language application may associate a string of text with an ECB using the $ECBDSET function; the text may be read by other threads using $ECBDGET function.

The following $functions, are available for implementing signaling and synchronization between threads:
<table>
<caption>$Functions for signaling and synchronization</caption>
<tr class="head">
<th>$Function </th>
<th>Purpose </th>
<th>For details see...</th>
</tr>

<tr>
<td>[[$ECBDGET]]</td>
<td>Retrieve string data associated with an ECB. </td>
<td>[[$ECBDGET#$ECBDGET|$ECBDGET]]</td>
</tr>

<tr>
<td>[[$ECBDSET]]</td>
<td>Associate a string of data with an ECB.</td>
<td>[[$ECBDSET#$ECBDSET|$ECBDSET]]</td>
</tr>

<tr>
<td>[[$ECBTEST]]</td>
<td>Test an ECB to see whether it is posted or not. </td>
<td>[[$ECBTEST#$ECBTEST|$ECBTEST]]</td>
</tr>

<tr>
<td>[[$POST]]</td>
<td>Indicate that an event has occurred. The thread waiting on an ECB can resume processing.</td>
<td>[[$POST#$POST|$POST]]</td>
</tr>

<tr>
<td>[[$UNPOST]]</td>
<td>Indicate that an event did not occur or recur. </td>
<td>[[$UNPOST#$UNPOST|$UNPOST]]</td>
</tr>

<tr>
<td>[[$WAIT]]</td>
<td>Suspend a user until an event happens and the ECB is posted.</td>
<td>[[$WAIT#$WAIT|$WAIT]]</td>
</tr>
</table>

You can also use these functions to implement a third-party software backup plan for <var class="product">Model 204</var>; see the
<var class="book">[http://www.rocketsoftware.com/m204/products/model204/documentation/v7r4/M204-System-Mgr/view Rocket Model 204 System Manager's Guide</var>
for a chapter on recovery features.

====Assigning and using an ECB number====

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

===Programming thread synchronization in User Language===

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

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

====Posting and unposting ECBs====

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

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

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

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

====Thread synchronization programming details====

The number of ECBs available to an Online is determined by the <var[[NECBS parameter|NECBS]]</var> parameter set in CCAIN. The parameter cannot be reset.

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

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

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

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

====Examples of programming thread synchronization====

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

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

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


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

========* CHECK %POSTCODE AND CONTINUE PROCESSING
END


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

==TCP/IP Sockets Interface for Model 204==

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

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

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

===Linking FUNU for ASCII to EBCDIC conversion===

Because it is very common to perform ASCII to EBCDIC conversion and back with a TCP/IP interface, Rocket Software recommends that you link the FUNU module during your <var class="product">Model 204</var> installation process or relink it later when you decide to use the TCP/IP Sockets Interface for <var class="product">Model 204</var>. This ensures access to the $ASCII and $EBCDIC functions, which are used for EBCDIC and ASCII conversion to send and receive messages. 
<ul>
<li>For z/VSE, link the FUNU.A member</li>

<li>For z/VM, link the FUNU module</li>

<li>For z/OS, edit the SOCKETS parameter in INSPARMS to SOCKETS=Y and provide a decryption key during the installation process. </li>
</ul>

===Understanding sockets===

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

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

[[#Understanding sockets|Understanding sockets]] illustrates a typical sequence of socket requests in which a server handles data from a single client, and the client then ends the connection.
<table>
<caption>Common sequence of calls</caption>
<tr class="head">
<th colspan="2">Client calls</th>
<th colspan="2">Server calls</th>
</tr>

<tr>
<td>Specify local-->
TCP/IP address</td>
<td>
INIT
</td>
<td>
INIT
</td>
<td> </td>
</tr>

<tr>
<td> </td>
<td>
SOCKET
</td>
<td>
SOCKET
BIND
LISTEN
</td>
<td>Get a socket to
<-- receive connections; specify port</td>
</tr>

<tr>
<td> </td>
<td>

</td>
<td>

</td>
<td> </td>
</tr>

<tr>
<td>Specify remote-->
address and port</td>
<td>
CONNECT-->
</td>
<td>
SELECT
ACCEPT
</td>
<td> </td>
</tr>

<tr>
<td> </td>
<td>

</td>
<td>
SETSOCKOPT
</td>
<td> </td>
</tr>

<tr>
<td>Data traffic</td>
<td>
WRITE-->
</td>
<td>
SELECT
READ
</td>
<td> </td>
</tr>

<tr>
<td> </td>
<td>
SELECT
READ
</td>
<td>
<--WRITE
</td>
<td> </td>
</tr>

<tr>
<td> </td>
<td>
SHUTDOWN
CLOSE-->
</td>
<td>

</td>
<td> </td>
</tr>

<tr>
<td> </td>
<td>
TERM
</td>
<td>
TERM
</td>
<td> </td>
</tr>
</table>

===Using the TCP/IP Sockets Interface for Model 204===

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

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

==TCP/IP for z/VSE==

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

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

===Using the TCPNAME parameter for z/VSE===

When the <var class="product">Model 204</var> Online starts, it needs to know which of the TCP/IP stacks to talk to. The stack name is passed using the TCPNAME parameter. The format is: 
TCPNAME=00, TCPNAME=01, ...TCPNAME=nn


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

This value is used when the first TCP/IP link is opened, and if there is an error setting the ID the following error message is displayed:
M204.2710: ERROR x SETTING TCP/IP SYSID nn


where
<ul>
<li>x is the return code from the TCP interface</li>

<li>nn is the value passed in TCPNAME</li>
</ul>

===Using TCP/IP-related commands===

Horizon on TCP/IP, the TCP/IP Sockets Interface for <var class="product">Model 204</var>, and SQL/RCL are available to z/VSE sites. The syntax and usage for the following <var class="product">Model 204</var> commands that support Horizon for TCP/IP communication are described in the linked individual command descriptions:
<ul>
<li>[[DEFINE LINK: Horizon for TCP/IP]]

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

<li>[[DEFINE PROCESS: Horizon for TCP/IP and VTAM]]</li>

<li>[[DEFINE PROCESSGROUP: Horizon for TCP/IP]]</li>
</ul>

==$SOCKET function==

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

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

====Syntax====

The following is syntax for the $SOCKET function
%returncode=$SOCKET('socket-call',argument1, argument2,...)


Where:
<ul>
<li><var class="term">socket-call</var> is one of the calls described in this section.</li>

<li><var class="term">argument1, argument2</var>,...are specified in the definition of each call.</li>
</ul>

====Example====

The following $SOCKET function illustrates a valid ACCEPT call:
%rc=$socket('ACCEPT',%lsocket,'%rport',%raddr)


===ACCEPT call===

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

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


Where:
<ul>
<li><var class="term">passive-socket-number</var> specifies by integer the listening socket. It is usually the first socket obtained by a server. </li>

<li><var class="term">port-variable-name</var> specifies a numeric fixed variable, which holds an output value as an integer. Enclose this argument in single quotation marks.</li>

<li><var class="term">address-output</var> specifies the dotted decimal address of the client making the connection request. <var class="term">address-output</var> is a 15-byte string argument in the format <var class="term">nnn.nnn.nnn.nnn</var>.

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

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.</li>
</ul>

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


===BIND call===

The BIND call provides the socket number and port number.

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


Where:
<ul>
<li><var class="term">socket</var> specifies, as an integer, the socket number.</li>

<li><var class="term">port</var> specifies the server port number as an integer. <var class="term">port</var> corresponds to the SERVPORT argument in a <var class="product">Model 204</var> DEFINE LINK command.</li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.</li>
</ul>

====Usage====

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

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

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


===CANCEL call===

The CANCEL call ends an asynchronous request.

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


Where:
<ul>
<li><var class="term">socket</var> specifies the socket used by the call being cancelled, or -1 to match any call. </li>

<li><var class="term">callname</var> specifies the call being cancelled, as a literal enclosed in single quotation marks. This is usually <code>'SELECT'</code> to cancel a SELECT call, <code>'READ'</code> to cancel a READ call, or <code>'<tt>*</tt>'</code> to match any call.</li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.</li>
</ul>

====Usage notes====

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

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

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

('CANCEL',5,'*')


===CLOSE call===

The CLOSE call stops the use of a socket.

====Syntax====
('CLOSE', socket[,interface])


Where:
<ul>
<li><var class="term">socket</var>, an integer, specifies the socket number.</li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.</li>
</ul>

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


====Usage notes====

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

===CONNECT call===

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

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


Where:
<ul>
<li><var class="term">socket</var>, an integer, specifies the socket number returned from the SOCKET call. </li>

<li><var class="term">port</var> specifies the server port number as an integer. This port corresponds to the <var>SERVPORT</var> argument in a <var class="product">Model 204</var> <var>DEFINE LINK</var> command.</li>

<li><var class="term">address</var> specifies a dotted decimal internet address as a 15-byte string in the format <var class="term">nnn.nnn.nnn.nnn</var>.

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

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.</li>
</ul>

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


===INIT call===

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

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


Where:
<ul>
<li><var class="term">interface</var> specifies an up-to 8-character name for the local end of the TCP/IP connection.</li>

<li><var class="term">address</var> specifies a dotted decimal internet address as a 15-byte string in the format <var class="term">nnn.nnn.nnn.nnn</var>.

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

<li><var class="term">port</var> specifies the local port number as an integer. This port corresponds to the SERVPORT argument in a <var class="product">Model 204</var> DEFINE LINK command.</li>

<li><var class="term">max-connections</var> specifies the maximum number of connections, as in a <var class="product">Model 204</var> DEFINE LINK command. The value of <var class="term">max-connections</var> is an integer from 1 to 31. [[Contacting Rocket Software Technical Support|Technical Support]] recommends that you specify at least 3.</li>

<li><var class="term">max-requests</var> specifies the maximum number of outstanding requests. Technical Support recommends that you set the value of <var class="term">max-requests</var> to at least four up to a maximum of 31.</li>
</ul>

====Usage notes====

The number of sockets created for the interface is returned.

The INIT call corresponds to a <var class="product">Model 204</var> DEFINE and OPEN LINK command. INIT must be the first call.

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

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


===LISTEN call===

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

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


Where:
<ul>
<li><var class="term">socket</var>, an integer, specifies the socket number that was returned from the SOCKET call.</li>

<li><var class="term">backlog</var>, an integer, specifies the maximum number of simultaneous connection requests. Make <var class="term">backlog</var> not less than the expected maximum number of simultaneous connection requests from a client. </li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.</li>
</ul>

====Usage note====

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

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


===READ call===

The READ call receives data.

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

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

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


Where:
<ul>
<li><var class="term">socket</var>, an integer, specifies the socket number. </li>

<li><var class="term">buffer</var> specifies the output location for data on the read operation. The value is represented by a string percent variable or an image name. Enclose the value in quotation marks: for example, <code>'%buff'</code> and <code>'MYIMAGE'</code> respectively.

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

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

<li><var class="term">maximum-length</var> specifies the maximum length of data as an integer.</li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.</li>
</ul>

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


===REGISTER call===

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

====Syntax====
('REGISTER', interface)


Where <var class="term">interface</var> specifies an up-to-8-character name for the TCP/IP environment, which identifies the host port.

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


====Usage notes====

You must include a REGISTER call immediately after the INIT call when:
<ul>
<li>You want to continue using the interface after the thread closes its last socket.</li>

<li>A thread other than the one that created the interface wants to use the interface.</li>
</ul>

===SELECT call===

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

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


Where:
<ul>
<li><var class="term">highest-socket</var> specifies the highest socket number in the FDS arguments, plus one, as an integer. For example, if the FDS arguments select sockets 3, 2, and 0, specify 4, which is the highest socket plus 1. </li>

<li><var class="term">readFDS-variable-name</var> specifies to TCP/IP which sockets to wait on for input. Enclose this integer argument in quotation marks, because this is a fixed 4-byte full word variable used to hold a value output.

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

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

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

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

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

<li><var class="term">timeout</var> specifies a value in seconds, or a negative integer for no timeout.
<table>
<tr class="head">
<th>Value in seconds</th>
<th>Meaning</th>
</tr>

<tr>
<td>-1 </td>
<td>No time-out: waits for an event.</td>
</tr>

<tr>
<td> 0 </td>
<td>Returns immediately, if no socket is selected.</td>
</tr>

<tr>
<td>Greater than 0 </td>
<td>The length of the time-out in seconds.</td>
</tr>
</table></li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.</li>
</ul>

====Usage====

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

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

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

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


====Usage====

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

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

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

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

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

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

===SHUTDOWN call===

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

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


Where:
<ul>
<li><var class="term">socket</var>, an integer, specifies the socket number. </li>

<li><var class="term">shutdown-value</var> specifies the type of traffic to make inactive, represented as an integer.
<table>
<tr class="head">
<th>Value </th>
<th>Meaning</th>
</tr>

<tr>
<td>0 </td>
<td>Receive</td>
</tr>

<tr>
<td>1 </td>
<td>Send</td>
</tr>

<tr>
<td>2 </td>
<td>Both send and receive</td>
</tr>
</table></li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.</li>
</ul>

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


====Usage notes====

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

===SOCKET call===

The SOCKET call allocates a socket.

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


Where:
<ul>
<li><var class="term">domain</var> specifies the integer 2, which is required. On z/OS systems, specify 19 if you are using IPv6 (AF_INET6) addressing.</li>

<li><var class="term">type</var> specifies the integer 1, which is required.</li>

<li><var class="term">protocol</var> specifies the integer 0, which is required.</li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.
</li>
</ul>

====Usage notes====

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

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


===TERM call===

The TERM call attempts to close any open sockets, and deletes the interface; it corresponds to a <var class="product">Model 204</var> CLOSE LINK command.

====Syntax====
('TERM', interface)


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

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


====Usage notes====

A TERM call does an implicit CLOSE call for all open sockets, accompanied by the following message for each open socket:
M204.2288: TCP/IP CLEANUP IS CLOSING SOCKET socket-number FOR USER userid


===WRITE call===

The WRITE call sends data.

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


Where:
<ul>
<li><var class="term">socket</var>, an integer, specifies the socket number. </li>

<li><var class="term">buffer</var> specifies the data location, which can be a string percent variable or an image name. Enclose the value in quotation marks: for example, <code>'%buff'</code> and <code>'MYIMAGE'</code> respectively.</li>

<li><var class="term">length</var> specifies the length of data to be sent, in bytes. If this is less than the data in the variable or image, the data is truncated. If data is truncated and buffer is an image name, $STATUSD is set to -989, but this is a warning, and the data is transmitted correctly. </li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.</li>
</ul>

====Usage====

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

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


==$SOCKETX function==

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


Where:
<ul>
<li><var class="term">socket-call</var> is the GETHOST, GETSOCKOPT, SETSOCKOPT, or GETINFO call. GETINFO is supported on z/OS systems only.</li>

<li><var class="term">socket</var> is an integer that identifies the socket from an earlier ACCEPT or LISTEN call.</li>

<li><var class="term">option-name</var> is an integer that identifies the option. </li>
<table>
<tr class="head">
<th>Option-name integer </th>
<th>IBM option</th>
</tr>

<tr>
<td align="right">4 </td>
<td>SO_REUSEADDR</td>
</tr>

<tr>
<td align="right">8 </td>
<td>SO_KEEPALIVE</td>
</tr>

<tr>
<td align="right">32 </td>
<td>SO_BROADCAST</td>
</tr>

<tr>
<td align="right">256 </td>
<td>SO_OOBINLINE</td>
</tr>

<tr>
<td align="right">4097 </td>
<td>SO_SNDBUF</td>
</tr>
<tr>
<td align="right">4103 </td>
<td>SO_ERROR</td>
</tr>

<tr>
<td align="right">4104 </td>
<td>SO_TYPE</td>
</tr>
</table></li>
</ul>

====Example====

The following $SOCKETX function illustrates a valid GETSOCKOPT call:
%rc=$socketx('GETSOCKOPT',%socket,4097)


====Usage notes====

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

===GETHOST call===

The GETHOST call translates a host name to a network address (or addresses in the format of <var class="term">nnn.nnn.nnn.nnn</var>).

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


Where:
<ul>
<li><var class="term">hostname</var> specifies a 25-byte string to be translated to a dotted decimal address in the format <var class="term">nnn.nnn.nnn.nnn</var>.</li>

<li><var class="term">address-array</var>, which is enclosed in single-quotation marks, specifies an image containing an array of 15-byte strings for output. The GETHOST call will populate the address array with the retrieved dotted-decimal network address(es). </li>
</ul>

====Usage notes====
<ul>
<li>It is useful for a client to translate a server to a dotted-decimal address before issuing the CONNECT call. </li>

<li>The GETHOST call, which corresponds to the IBM GETHOSTBYNAME call, can be issued even if no interface has been created. </li>

<li>To translate the domain name on z/OS systems, you need to supply a DD card for the SYSTCPD data set, as in this example:
//SYSTCPD DD DSN=TCPIP.PROFILE(TCPDATA), DISP=SHR
</li>

<li>If you want to make use of IPv6 addressing, use GETINFO instead of GETHOST.</li>

<li>The GETHOST call is not supported on z/VM systems.</li>
</ul>

===GETSOCKOPT call===

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

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


Where:
<ul>
<li><var class="term">socket</var> is an integer that identifies the socket.</li>

<li><var class="term">option-name</var> is an integer that identifies the option.
<table>
<tr class="head">
<th>Integer </th>
<th>Option</th>
</tr>

<tr>
<td align="right">4 </td>
<td>SO_REUSEADDR</td>
</tr>

<tr>
<td align="right">8 </td>
<td>SO_KEEPALIVE</td>
</tr>

<tr>
<td align="right">32 </td>
<td>SO_BROADCAST</td>
</tr>

<tr>
<td align="right">256 </td>
<td>SO_OOBINLINE</td>
</tr>

<tr>
<td align="right">4097 </td>
<td>SO_SNDBUF</td>
</tr>

<tr>
<td align="right">4103 </td>
<td>SO_ERROR</td>
</tr>

<tr>
<td align="right">4104 </td>
<td>SO_TYPE</td>
</tr>
</table></li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.
</li>
</ul>

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


===SETSOCKOPT call===

The SETSOCKOPT call resets a socket option.

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


Where:
<ul>
<li><var class="term">socket</var> is an integer that identifies the socket.</li>

<li><var class="term">option-name</var> is an integer that identifies the option.
<table>
<tr class="head">
<th>Integer </th>
<th>Option</th>
</tr>

<tr>
<td align="right">4 </td>
<td>SO_REUSEADDR</td>
</tr>

<tr>
<td align="right">8 </td>
<td>SO_KEEPALIVE</td>
</tr>

<tr>
<td align="right">32 </td>
<td>SO_BROADCAST</td>
</tr>

<tr>
<td align="right">256 </td>
<td>SO_OOBINLINE</td>
</tr>

<tr>
<td align="right">4097 </td>
<td>SO_SNDBUF</td>
</tr>

<tr>
<td align="right">4103 </td>
<td>SO_ERROR</td>
</tr>

<tr>
<td align="right">4104 </td>
<td>SO_TYPE</td>
</tr>
</table></li>

<li><var class="term">option-value</var> specifies an integer. Consult the IBM documentation for the option values.</li>

<li><var class="term">interface</var> specifies the host port the call applies to. If an interface is not specified, the default is the first or only interface.
</li>
</ul>

====Example====

The following $SOCKETX function illustrates a SOCKOPT call to set on the KEEPALIVE option:
%rc=$socketx('SETSOCKOPT',8,1,%pathname)


===GETINFO call===

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

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


Where the flag and family fullwords, described in the <var class="book">Application Programming Interface Reference</var> manual, have the following values:
* FLAG WORD= (FULLWORD) FLAG WORD FOR GETADDRINFO CALL
* VALID VALUES (ADDITIVE) ARE
* AI_PASSIVE : 1 - get value suitable for listening
* AI_CANONNAMEOK : 2
* AI_NUMERICHOST : 4
* AI_NUMERICSERV : 8
* AI_V4MAPPED : 16 - include V4-mapped IPV6 addresses
* AI_ALL : 32 - get all possible addresses
* AI_ADDRCONFIG : 64
family fullword: fixed value or literal
* USED TO LIMIT THE ADDRESSES RETURNED
* VALID VALUES ARE
* AI_UNSPEC : 0 - get both IPV4 and IPV6
* AI_INET : 2 - get IPV4 only
* AI_INET6 : 19 - get IPV6 only


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

The output structure, which can be either variable or image, is:
ADDRESS1 STRING LEN 45 first address
FAMILY1 STRING LEN 1 4, 6, or space
ADDRESS2 STRING LEN 45 second address
FAMILY2 STRING LEN 1 4, 6, or space


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

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


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

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

==Error codes, examples, and limitations==

===Error codes for calls===

The error codes listed in [[#Error codes for calls|Error codes for calls]] were written specifically for TCP/IP Sockets Interface for <var class="product">Model 204</var>. Additional error codes you might encounter are described in IBM documentation for TCP/IP for z/OS: API Reference.

The following error codes are valid when the return code is -1, except for -991, which can occur after a successful READ call, where the return code is the number of bytes transferred to the variable.
<table>
<caption>Error codes returned by $STATUSD</caption>
<tr class="head">
<th>Values</th>
<th>Meaning</th>
</tr>

<tr>
<td align="right">-999 </td>
<td>Invalid argument.</td>
</tr>

<tr>
<td align="right">-998 </td>
<td>Call attempted, other than the INIT call, when the user is not registered with a functions interface.</td>
</tr>

<tr>
<td align="right">-997 </td>
<td>Failure attempting to allocate storage.</td>
</tr>

<tr>
<td align="right">-996 </td>
<td>This is a failure writing data into an output variable or image.</td>
</tr>

<tr>
<td align="right">-995 </td>
<td>The link is an incorrect type (for INIT, REGISTER, and TERM calls)</td>
</tr>

<tr>
<td align="right">-994 </td>
<td>The socket has not been released. In the case of a CLOSE call, the socket is of the wrong type — possibly a Horizon socket.</td>
</tr>

<tr>
<td align="right">-993 </td>
<td>There has been a physical error on the interface.</td>
</tr>

<tr>
<td align="right">-992 </td>
<td>The pathname is unknown (for REGISTER and TERM calls only).</td>
</tr>

<tr>
<td align="right">-991 </td>
<td>On a READ call, the string is shorter than the length parameter. The data received is truncated.</td>
</tr>

<tr>
<td align="right">-990</td>
<td>Socket not found.</td>
</tr>

<tr>
<td align="right">-989</td>
<td>On a WRITE call this is a warning code that shows that the image being sent was truncated.</td>
</tr>

<tr>
<td align="right">-988</td>
<td>Error on GETHOSTBYNAME call.</td>
</tr>

<tr>
<td align="right">-987</td>
<td>Error deleting the temporary interface after GETHOST call.</td>
</tr>

<tr>
<td align="right">-986</td>
<td>The CANCEL call found no matching call to cancel; no action was taken.</td>
</tr>

<tr>
<td align="right">-985</td>
<td>The socket number obtained on a SOCKET or ACCEPT was above the limit of 31, so it has been closed. It may be that 32 sockets are already in use. Or, if many sockets are opened and closed quickly, perhaps not enough time — one minute — has elapsed to reuse a free socket. You can close an open socket, or you can wait to reuse a free socket. </td>
</tr>

<tr>
<td align="right">-984</td>
<td>Universal Buffer not there.</td>
</tr>

<tr>
<td align="right">-983</td>
<td>Universal Buffer length error.</td>
</tr>

<tr>
<td align="right">-982</td>
<td>Universal Buffer allocation error.</td>
</tr>
</table>

==Example procedure - Server==

This code is included on the installation distribution medium. See the individual operating system installation guide for its location. The following code is called SOCKSMPS, located as follows:
<table>
<tr class="head">
<th>Operating system </th>
<th>Located</th>
</tr>

<tr>
<td>z/OS </td>
<td>JCLLIB data set</td>
</tr>

<tr>
<td>z/VM </td>
<td>193 C</td>
</tr>

<tr>
<td>z/VSE </td>
<td>J610 sublib</td>
</tr>
</table>
BEGIN
* This is an example of the server side of the sockets
* interface
DECLARE %PATHNAME STRING LEN 8
DECLARE %SOCKET FIXED
DECLARE %LSOCKET FIXED
DECLARE %HIGHSOCK FIXED
DECLARE %NEWSOCK FIXED
DECLARE %TSOCKET FIXED
DECLARE %PORT FIXED
DECLARE %RPORT FIXED
DECLARE %ADDR STRING LEN 15
DECLARE %RADDR STRING LEN 15
* NNN.NNN.NNN.NNN (dotted decimal internet address) is
* 15 characters long (maximum)
DECLARE %RC FIXED
DECLARE %SOMAX FIXED
DECLARE %READFDS FIXED
DECLARE %EXFDS FIXED
DECLARE %WRITEFDS FIXED
DECLARE %FRED STRING LEN 12
DECLARE %FN STRING LEN 10
%PATHNAME = 'TCPS'
* %PATHNAME is 8 characters - the link name
* %LSOCKET is the listening socket, %SOCKET for data
%PORT = 7633
%SOMAX = 8
%FRED = 'DATA OUT'
%ADDR = '193.208.28.129'
%RADDR = '193.208.28.129'
%RC = 0
%READFDS = 0
%EXFDS = %READFDS
%WRITEFDS = %READFDS
* %HIGHSOCK is used in SELECT calls for the highest number
* of sockets in an FDS
%HIGHSOCK = 0
* In the following call, 6 is the maximum number of
* connections and 7 is the maximum number of requests.
%RC = $SOCKET('INIT',%PATHNAME,%ADDR,%PORT,6,7)
%RC = $SOCKET('REGISTER',%PATHNAME)
* 2,1,0 are the domain, type, and protocol
%RC = $SOCKET('SOCKET',2,1,0)
%LSOCKET = %RC
%NEWSOCK = %LSOCKET
* call ADDSOCK to add the new socket to the FDS and
* update %HIGHSOCK
CALL ADDSOCK
%RC = $SOCKET('BIND',%LSOCKET,%PORT)
%RC = $SOCKET('LISTEN',%LSOCKET,10)
* Wait for a connection
%RC = $SOCKET('SELECT',%HIGHSOCK, -
'%READFDS','%WRITEFDS','%EXFDS',0)
* -1 is error
IF %RC < 0 THEN
JUMP TO SELECT.ERROR
END IF
AUDIT 'AFTER SELECT READ FDS IS ' AND %READFDS
* >1 shows that sockets have been selected
IF %RC > 0 THEN
* But is's bad news if it's an exception FDS
IF %EXFDS > 0 THEN
AUDIT 'EXCEPTION FDS NON-ZERO ' AND %EXFDS
JUMP TO SELECT.ERROR
ELSE
JUMP TO SELECT.ACCEPT
END IF
END IF
* If rc=0, there has been a time-out, which should not happen
* if the timeout argument is -1.
JUMP TO COMMON.END

*
SELECT.ACCEPT:
* The listen has resulted in a connection request - accept it
* Note that quotation marks enclose the port argument in the
* call - we are passing the name of the variable, not its
* value, because the port number will be placed in the
* variable by the function.
%RC = $SOCKET('ACCEPT',%LSOCKET,'%RPORT',%RADDR)
IF %RC GT 0 THEN
AUDIT 'REMOTE ADDRESS IS ' AND %RADDR
AUDIT 'REMOTE PORT IS ' AND %RPORT
AUDIT 'NEW SOCKET IS ' AND %RC
%SOCKET = %RC
ELSE
JUMP TO COMMON.END
END IF
*
%NEWSOCK = %LSOCKET
CALL DELSOCK
* Use DELSOCK to delete the listening socket from the FDS
%NEWSOCK = %SOCKET
* We now need to select on the data socket instead of the
* listening socket (Socket 1)
* Call ADDSOCK to add the new socket to the FDS and
* update %HIGHSOCK
CALL ADDSOCK
*
* 8 is SO_KEEPALIVE, which we set ON (0 is OFF, 1 is ON)
%RC = $SOCKET('SETSOCKOPT',%SOCKET,8,1)
* Wait for data
SELECT2:
%RC = $SOCKET('SELECT',%HIGHSOCK, -
'%READFDS','%WRITEFDS','%EXFDS',0)
* -1 is error
IF %RC < 0 THEN
JUMP TO SELECT.ERROR
END IF
AUDIT 'AFTER SELECT READ FDS IS ' AND %READFDS
* >1 shows that sockets were selected
IF %RC > 0 THEN
* But it's bad news if it's an exception FDS
IF %EXFDS > 0 THEN
AUDIT 'EXCEPTION FDS NON-ZERO ' AND %EXFDS
JUMP TO SELECT.ERROR
ELSE
JUMP TO SELECT.READ
END IF
END IF
* rc=0 (time-out)
JUMP TO COMMON.END
*
SELECT.READ:
* Note that on the READ, the buffer variable name is enclosed
* in quotation marks.
%RC = $SOCKET('READ',%SOCKET,'%FRED',12)
IF %RC < 0 THEN
AUDIT 'READ ERROR'
JUMP TO COMMON.END
END IF
IF %RC = 0 THEN
* If number of bytes = 0, this is remote socket close
JUMP TO COMMON.END
END IF
* Read again until we detect a close
JUMP TO SELECT2
* %RC = $SOCKET('WRITE',%SOCKET,%FRED,7)
JUMP TO COMMON.END
SELECT.ERROR:
AUDIT 'SELECT ERROR'
COMMON.END:
* Deactivate and close the data socket
IF %SOCKET GE 0 THEN
%RC = $SOCKET('SHUTDOWN',%SOCKET,2)
%RC = $SOCKET('CLOSE',%SOCKET)
END IF
* Deactivate and close the listening socket
IF %LSOCKET GE 0 THEN
%RC = $SOCKET('SHUTDOWN',%LSOCKET,2)
%RC = $SOCKET('CLOSE',%LSOCKET)
END IF
*
%RC = $SOCKET('TERM',%PATHNAME)
ADDSOCK: SUBROUTINE
* Adds NEWSOCK to the FDS bitmap
%READFDS = %READFDS + $RXPI(2, %NEWSOCK)
%WRITEFDS = 0
%EXFDS = %READFDS
%TSOCKET = %NEWSOCK + 1
IF %TSOCKET GT %HIGHSOCK THEN
%HIGHSOCK = %TSOCKET
END IF
*
END SUBROUTINE ADDSOCK
*
DELSOCK: SUBROUTINE
* Deletes NEWSOCK from the FDS bitmap
%READFDS = %READFDS - $RXPI(2, %NEWSOCK)
%WRITEFDS = 0
%EXFDS = %READFDS
%TSOCKET = %NEWSOCK + 1
IF %TSOCKET = %HIGHSOCK THEN
%HIGHSOCK = %HIGHSOCK - 1
END IF
END SUBROUTINE DELSOCK
END


==Example procedure - Client==

This code is included on the installation distribution medium. See the individual operating system installation guide for its location. The following code is called SOCKSMPC, located as follows:
<table>
<tr class="head">
<th>Operating system </th>
<th>Located</th>
</tr>

<tr>
<td>z/OS </td>
<td>JCLLIB data set</td>
</tr>

<tr>
<td>z/VM </td>
<td>193 C</td>
</tr>

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


==Limitations to TCP/IP Sockets Interface for Model 204==

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

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

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

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

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

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

</div> 

[[Category:SOUL]]

SOUL $functions

2014-07-31T19:01:10Z

Mlarocca: /* Summary of standard functions */

==Overview==

Some operations are inefficient or impossible to code in a high-level programming language like User Language. To overcome this difficulty, User Language provides a variety of functions, which are assembly language subroutines you can call from within a User Language request.

The name of each User Language function begins with a dollar sign ($). For this reason, they are often referred to as $functions (dollar functions).

==Types of functions==

===Functions provided by User Language===

The functions provided by User Language are divided into two sets. One set is supplied as a standard feature and includes functions for data editing, data validation, and other purposes. The other set of functions (mathematical functions) is an optional feature of <var class="product">Model 204</var> and contains mathematical and scientific subroutines. 

In order to save machine resources, your site might have chosen to omit some of the standard functions as well as some or all of the mathematical functions. If a request calls a function that is not yet installed, compile-time errors result. 

===User-written functions===

In addition to the functions provided by User Language, some customer sites write their own functions based on their particular needs.

Before using any user-written functions, make sure that your site's FUNU module has been reassembled with the macro library supplied with the current release. Also, please be sure to carefully test your user-written functions before your system goes into production. 


Note:
It is recommended that all user-written functions use the STMG/LMG Assembly Language instructions to save and restore any registers that are modified.


Customers are individually responsible for any functions they write. Rocket Software takes no responsibility for user-written functions or their documentation.

==Using functions==

You can use functions in several ways, including, as a term in:
<ul>
<li>An expression in a variable assignment statement, for example:</li>
</ul>
%X=$EDIT(2573,'99999')

<ul>
<li>The specifications in a PRINT statement</li>
</ul>

A PRINT statement can include a function call anywhere a field name can be used. For example:
PRINT $EDIT(2573,'99999')

<ul>
<li>An expression in a conditional statement, for example:</li>
</ul>
IF $EDIT(2573,'99999') EQ 02573 THEN...

<ul>
<li>An expression which serves as the argument to another function, for example:</li>
</ul>
%L=$LEN($EDIT(2573,'99999'))


The direct use of function calls in some statements, such as FIND, results in compilation errors. 

====Comparing successful and unsuccessful $function code====

If your request is coded as follows:
BEGIN
$EDIT(2573,'99999')
END


The following error is your result:
*** 1 M204.0229: INVALID STATEMENT $EDIT(2573,'99999')


However, if you code your request as follows, it works properly:
BEGIN
PRINT $EDIT(2573,'99999')
* Or *
* %X=$EDIT(2573,'99999') *
END


===Function return values===

Each function returns a single value to the calling request. For example, this function sets %A equal to the user's login account name:
%a = $account


This function causes the length of the current value of the FULLNAME field to be compared to 10:
IF $LEN(FULLNAME) GT 10 THEN
.
.
.


===Function arguments===

Some functions require one or more arguments which allow you to pass information to the subroutine. Some functions take no arguments. Arguments must be enclosed in parentheses and separated by commas. For example:
IF $READ('CONTINUE?') EQ 'YES' THEN
.
.
.
%X = $mod(COUNT IN CT, %BASE)


====Rules for function arguments====

Function arguments follow the normal rules for arithmetic expressions. Arguments can include other function calls and can perform any type of computation. See the section [[Using variables and values in computation#Expressions|Expressions]] for detailed information on expression syntax.

====Argument evaluation and conversion====

<var class="product">Model 204</var> evaluates each argument to a function as either a string or a number. When this data type conflicts with the data type required by the function, the following rules apply:
<ul>
<li>If an argument is expected to be numeric but is a string, <var class="product">Model 204</var> converts the string to a number according to the conversion rules described in the assignment statement discussion in [[Using variables and values in computation#Relationship between %variable assignment and declaration|Relationship between %variable assignment and declaration]] and [[Using variables and values in computation#Conversion|Conversion]]. </li>
</li>
<li>If an argument is expected to be a string but is numeric, <var class="product">Model 204</var> converts the number to a string. </li>
</li>
<li>If the original number contains decimal places, they are lost during the conversion.</li>
</li>
</ul>

==Sending email messages via User Language==

The User Language <var>$SNDMAIL</var> function simplifies sending an email message to issuing a single function call. You can easily send an email message using User Language without writing a procedure and without having an extensive knowledge of sockets or SMTP protocol.

====Internet Protocol (IP) addressing====

On z/OS systems only, Model 204 supports both IPv6 and IPv4 addressing.

====Limitations of the $SNDMAIL function under z/VM and z/VSE====

<var>$SNDMAIL</var> is supported with the following exceptions:
<ul>
<li>The <var>[[SMTPCADD parameter|SMTPCADD]]</var> and <var>[[SMTPSADD parameter|SMTPSADD]]</var> addresses must be supplied in internet protocol (IP) address protocol, not as domain names. You must supply IPv4 (dotted-decimal) internet addresses for the <var>SMTPCADD</var> and <var>SMTPSADD</var> parameters.</li>

<li>Likewise, if the client and server names are specified using the SMAILD image rather than using the CCAIN parameters <var>SMTPCADD</var> and <var>SMTPSADD</var>, the SERVERDDNAME and CLIENTDDNAME values must be supplied rather than the SERVERNAME and CLIENTNAME values. </li>

<li><var class="product">Model 204</var> does not support IPv6 addressing on z/VM or z/VSE systems.</li>
</ul>

===Enabling $SNDMAIL===

The first requirement for enabling the use of $SNDMAIL is to set the following four required CCAIN parameters:
<table>
<tr class="head">
<th>Parameter</th>
<th>SMTP purpose</th>
</tr>

<tr>
<td>SMTPCADD</td>
<td>SMTP client address. The client is the <var class="product">Model 204</var> address space.

On z/OS systems:

Set this parameter to one of the following: 
<ul>
<li>Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.</li>

<li>Dotted decimal address, such as 182.148.55.206.</li>

<li>IPV6 address, with up to 8 halfwords separated by colons, such as <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>

On z/VM or z/VSE systems:

Set this parameter to the dotted decimal address, such as <code>182.148.55.206</code>.
</td>
</tr>

<tr>
<td>SMTPCPRT</td>
<td>SMTP client port. The default value is 7700.</td>
</tr>

<tr>
<td>SMTPSADD</td>
<td>SMTP server address.

On z/OS systems:

Set this parameter to one of the following: 
<ul>
<li>Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM.</li>

<li>Dotted decimal address, such as 182.148.55.206.</li>
<li>IPV6 address, with up to 8 halfwords separated by colons, such as <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>.</li>
</ul>

On z/VM or z/VSE systems:

Set this parameter to the dotted decimal address, such as <code>182.148.55.206</code>.
</td>
</tr>

<tr>
<td>SMTPSPRT</td>
<td>SMTP server port. The default value is 25, which is standard for most SMTP servers.</td>
</tr>
</table>


Your system manager can dynamically reset these parameters while the run is up. If you use the domain name for either <var>SMTPCADD</var> or <var>SMTPSADD</var>, you must have the following DD allocated to the Online:
//SYSTCPD DD DSN=TCPIP.PROFILE(TCPDATA),DISP=SHR


This is the TCP/IP profile data set required to support the resolution of IP domain names. 

On some SMTP servers, a valid email address is required for the <var class="term">%from</var> argument in the <var>$SNDMAIL</var> function. Most SMTP activity requires a valid SMTP server.

====$SNDMAIL and BATCH204====

<var>$SNDMAIL</var> is supported in BATCH204 if you relink BATCH204 with the following objects after V7R4 installation:
<ul>
<li>TC62 (or TC62DOS on z/VSE systems)</li>

<li>TCIU</li>

<li>TCSE</li>

<li>LU62</li>

<li>FUNR (or FUNRDOS on z/VSE systems)</li>
</ul>

After relinking you need to ensure that the following SMTP parameters are set in the ONLINE and BATCH204 CCAIN:
<ul>
<li>SMTPCADD</li>

<li>SMTPSADD</li>

<li>SMTPCPRT</li>

<li>SMTPSPRT</li>
</ul>

===$SNDMAIL===

The <var>$SNDMAIL</var> function sends an email message using the values you enter for the <var>$SNDMAIL</var> arguments. <var>$SNDMAIL</var> lets you send an email message with an optional attachment.

====Syntax====

The syntax for the <var>$SNDMAIL</var> function is:
$SNDMAIL(%SUBJ,%RCPT,%BODY,%FROM,%TO,%CC,%BCC,'EMAILD',%ATTACH,'C')


Where:
<ul>
<li>%SUBJ, which is optional, specifies a %variable or literal that contains the topic line.</li>

<li>%RCPT, which is optional, specifies a %variable or an image that contains the destination addresses, separated by commas.

If %RCPT is omitted, the destination addresses are taken from the %TO, %CC and %BCC arguments. 

If %RCPT is an image, the image name must be enclosed within quotation marks, for example 'DEPT-ADDR'.
</li>

<li>%BODY specifies a %variable or an image that contains the text of the message. If %BODY is an image, the image name must be enclosed in quotation marks, for example 'MSG-TXT'.</li>

<li>%FROM specifies a %variable that contains the FROM header field of up to 255 bytes. Although %FROM is optional, you should supply it, otherwise messages could fail when speaking to another SMTP server. If %FROM is omitted, the logged-on user ID is used. The email server may append the domain name to the given %FROM value.</li>

<li>%TO, %CC, and %BC, which are optional, specify a %variable that contains the TO, CC, and BCC header fields, respectively, of up to 255 bytes each.

Address must be enclosed in carets (<>), for example: M204-help <M204support@rocketsoftware.com>.
</li>

<li>'EMAILD', which is optional, specifies image data. The parameter provides the ability to override the values specified in CCAIN for SMTPSPRT, SMTPCPRT, SMTPSADD, and SMTPCADD. If 'EMAILD' is present, it must be in the following format, with the items in the following order:
* EMAILD - IMAGE WITH SMTP PARAMETERS
IMAGE EMAILD
SERVERPORT IS BINARY LEN 4 ;*SMTPSPRT
CLIENTPORT IS BINARY LEN 4 ;*SMTPCPRT
SERVERNAME IS STRING LEN 255 ;*SMTPSADD
CLIENTNAME IS STRING LEN 255 ;*SMTPCADD
SERVERDD IS STRING LEN 15 ;*Server dotted decimal address IPv4 format (optional)
CLIENTDD IS STRING LEN 15 ;*Client dotted decimal address IPv4 format (optional)
SERVERIPV6 IS STRING LEN 45 ;*Server dotted decimal address IPv6 format (optional)
CLIENTIPV6 IS STRING LEN 45 ;*Client dotted decimal address IPv6 format (optional)
END IMAGE


The SERVERIPV6 and CLIENTIPV6 fields are provided for the IPv6 colon-separated network addresses. These two fields are optional, to provide backward compatibility.
</li>

<li>%ATTACH, which is optional, specifies a %variable or literal with the name of an attachment that will be appended to the message. The attachment is assumed to be in the Universal Buffer at offset 0 (also called position 1). The length of the attachment is defined by the $Buffer_Used value. If the %ATTACH parameter is omitted, there is no attachment.

The function encodes the attachment using Base64 encoding, and may also translate it depending on the 10th argument.</li>

<li>'C', which is optional and is available as of Model 204 version 7.5, specifies that the object in the buffer will be translated to ASCII before being attached to the email. Alternatively, you can set this parameter to a percent variable with the value 'C'. For example, translation to ASCII could be useful if the $SNDMAIL attachment is a CLOB (CHARACTER-LARGE-OBJECT) such as a text document. If this argument is not specified with the value 'C' or 'c', the attachment is sent as binary, that is, without translation.

In this example, the CLOB.TXT attachment will be translated to ASCII before being attached to the email:
%RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,'CLOB.TXT','C')

</li>
</ul>

===Setting CCAIN parameters for $SNDMAIL===

You can set the following CCAIN parameters as default values for $SNDMAIL.
<ul>
<li>SMTPCADD is the default SMTP client address, the TCP/IP domain for the operating system, for the $SNDMAIL function. You can specify SMTPCADD as:
<ul>
<li>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format. </li>

<li>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</li>

<li>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as:
<code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>

You can override SMTPCADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.</li>

<li>SMTPCPRT is the default SMTP client port for the $SNDMAIL function. The value can be any value in the user range — normally above 4095 and up to 32767.

You can override SMTPCPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.
</li>

<li>SMTPSADD is the default SMTP server address for the $SNDMAIL function. You can specify SMTPSADD as:
<ul>
<li>(z/OS, z/VM, or z/VSE) Internet Protocol (IP) address, IPv4 format.</li>

<li>(z/OS) Domain name of up to 255 bytes. If the first character of the address is an alphabetic character (A to Z), it is automatically evaluated as a domain name.</li>

<li>(z/OS) IPV6 address, with up to 8 halfwords separated by colons, such as: <code>C0:12:46:F0:00:00:00:01</code>, which can also be written as <code>C0:12:46:F0::01</code>. In other words, the double colon shows that there are missing halfwords of binary zeros.</li>
</ul>

You can override SMTPSADD for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function call.
</li>

<li>SMTPSPRT is the default SMTP server port for the $SNDMAIL function. SMTPSPRT is normally set to the standard SMTP value of 25. You can override SMTPSPRT for a specific call by entering a different value in the EMAILD argument of the $SNDMAIL function.</li>
</ul>

===Examples of running $SNDMAIL===

====Example 1====
%FROM = 'me@mydomain.com'
%TO = 'My Friend <you@yourdomain.com>'
%BNAME = 'mypicture.jpg'

MODIFY BUFFER CLEAR

IN LOBSVR FOR 1 RECORD WHERE SVRKEY = %SVRKEY
%ISIZE = $LOBLEN(SVRLOB)
PRINT 'SIZE OF ' WITH %SVRKEY WITH ' IS ' WITH %ISIZE
BUFFER, 1, %ISIZE = SVRLOB, 1, %ISIZE
END FOR

PRINT 'BUFFER USED IS ' WITH $buffer_used
%SUBJECT = 'THIS SENDS A JPG FROM LOBSVR - ' WITH %SVRKEY
%BODY = 'THIS BODY CONTAINS ' WITH %SVRKEY
%RC = $SNDMAIL(%SUBJECT,,%BODY,%FROM,%TO,,,,%BNAME)


In the previous example, a binary object (BLOB) is retrieved from the database and placed at position 1 in the buffer. The $SNDMAIL function sends this as a Base64-encoded attachment.
Note: The second parameter (the RCPTTO addresses) is omitted. The function creates this using the %TO parameter.

====Example 2====
%TO ='JANE <YOU@YOURCORP.COM>'
%BODY='See you at 9:30 AM tomorrow in the conference room'
%RC =$SNDMAIL(,,%BODY,,%TO)


====Example 3====

The EMAILD argument is used to override the default domain names and ports.
IMAGE EMAILD
SERVERPORT IS BINARY LEN 4 ;*SMTPSPRT
CLIENTPORT IS BINARY LEN 4 ;*SMTPCPRT
SERVERNAME IS STRING LEN 255 ;*SMTPSADD
CLIENTNAME IS STRING LEN 255 ;*SMTPCADD
END IMAGE

PREPARE IMAGE EMAILD
%EMAILD:SERVERNAME = 'MAIL.SERVER.COM'
%EMAILD:CLIENTNAME = 'MYMVSSYSTEM'
%EMAILD:SERVERPORT = 25
%EMAILD:CLIENTPORT = 5601
%FROM = 'ME@MYCORP.COM'
%TO = 'JANE <YOU@YOURCORP.COM>'
* RCPTTO is defined as an image here, allowing the string of
* addressees to be more than 255 bytes long.
IMAGE RCPTTO
EMRCPT1 IS STRING LEN 255
END IMAGE

PREPARE IMAGE RCPTTO
%RCPTTO:EMRCPT1 = 'YOU@YOURCORP.COM'
IMAGE BODY
BODY1 IS STRING LEN 240
BODY2 IS STRING LEN 240
END IMAGE

PREPARE IMAGE BODY
%S = 'EXAMPLE 1' /? SUBJECT LINE ?/
%BODY:BODY1 = 'THIS IS BODY1 WHICH IS PART OF AN IMAGE'
%BODY:BODY2 = 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG'
%RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')


====Example 4====

This example illustrates using EMAILD in an IPV6 environment. The lines that differ from Example 3 are shown in bold.
IMAGE EMAILD
SERVERPORT IS BINARY LEN 4 ;*SMTPSPRT
CLIENTPORT IS BINARY LEN 4 ;*SMTPCPRT
SERVERNAME IS STRING LEN 255 ;*SMTPSADD
CLIENTNAME IS STRING LEN 255 ;*SMTPCADD
SERVERDD IS STRING LEN 15 ;*Server dotted decimal address IPv4 format (optional)
CLIENTDD IS STRING LEN 15 ;*Client dotted decimal address IPv4 format (optional)
SERVERIPV6 IS STRING LEN 45 ;*Server dotted decimal address IPv6 format (optional)
CLIENTIPV6 IS STRING LEN 45 ;*Client dotted decimal address IPv6 format (optional)
END IMAGE

PREPARE IMAGE EMAILD
%EMAILD:SERVERPORT = 25
%EMAILD:CLIENTPORT = 5601
%EMAILD:SERVERNAME = 'MAIL.SERVER.COM'
%EMAILD:CLIENTIPV6 = 'C0:12:46:F0::01'

%FROM = 'ME@MYCORP.COM'
%TO = 'JANE <YOU@YOURCORP.COM>'
* RCPTTO is defined as an image here, allowing the string of
* addressees to be more than 255 bytes long.
IMAGE RCPTTO
EMRCPT1 IS STRING LEN 255
END IMAGE

PREPARE IMAGE RCPTTO
%RCPTTO:EMRCPT1 = 'YOU@YOURCORP.COM'
IMAGE BODY
BODY1 IS STRING LEN 240
BODY2 IS STRING LEN 240
END IMAGE

PREPARE IMAGE BODY
%S = 'EXAMPLE 1' /? SUBJECT LINE ?/
%BODY:BODY1 = 'THIS IS BODY1 WHICH IS PART OF AN IMAGE'
%BODY:BODY2 = 'SO THE BODY TEXT CAN BE MORE THAN 255 BYTES LONG'
%RC = $SNDMAIL(%S,'RCPTTO','BODY',%FROM,%TO,,,'EMAILD')


===ASCII translation===

All text, except an optional binary attachment, is translated from EBCDIC to ASCII before sending.

===Line ends===

Text that is part of the header and body can include EBCDIC CRLF strings (X'0D25') that are translated to ASCII along with the rest of the text.

===Reserved names===

The $SNDMAIL function uses Interface names CCAEM000 through CCAEM999. The user does not specify these names — the link name is generated by the function.

===Socket limits===

Up to 31 sockets are available on each link. If no more sockets are available on a particular link (CCAEM000, for example), the next link is tried. Thus, a maximum of 31,000 simultaneous email threads is theoretically possible.

===Size of email message===

The FROM, TO, CC, BCC, RCPTTO addresses, and body length, excluding the optional binary attachment, must total less than 27454 bytes.

===Return code===

The $SNDMAIL function returns a fixed full word binary return code. See [[#Handling error condition return codes|Handling error condition return codes]] for possible values.

===RCPTTO parameter===

If the $SNDMAIL EMAILD argument is omitted, the RCPTTO addresses are constructed from the addresses contained in the %TO, %CC, and %BCC arguments.

The sum of the lengths of the RCPTTO address string, (If supplied) and the body text cannot exceed 30,700.

===Using quotation marks===

You must enclose the names of images within quotation marks, for example: 'BODY'. However, do not enclose the percent variable values within quotation marks, for example: %SUBJECT, not '%SUBJECT'.

===Server and client names in the EMAILD parameters===

In the EMAILD image, on a z/OS system, you can specify either or both the server and client names as domain names, for example: <var>SMTPSERVER.YOURDOMAIN.COM</var> or as an Internet Protocol (IP) address. If you specify the domain name, a TCP/IP call looks up the IP address. 
<ul>
<li>If one field is present, all fields must be present, even if the optional fields are left blank. </li>
</li>
<li>If a name or port field is absent, it is taken from the CCAIN parameters SMTPSADD, SMTPCADD, SMTPSPRT, and SMTPCPRT. </li>
</li>
</ul>

The two port parameters have defaults: the SMTPSPRT default is 25; the SMTPCPRT default is 7700.

The two address parameters, SMTPSADD and SMTPCADD, can be specified either as domain names of up to 255 bytes or as IP addresses. If the address begins with an alphabetic character (A to Z), it is automatically evaluated as a domain name. 

The four CCAIN default parameters SMTPSADD, SMTPCADD, SMTPSPRT, and SMTPCPRT can be examined using VIEW and changed using RESET.

===References===

For more information about the standards used in this function, please refer to these Internet Request for Comments documents:
<ul>
<li>RFC822, Standard for the format of ARPA Internet Text Messages</li>
</li>
<li>RFC2821, Simple Mail Transfer Protocol</li>
</li>
<li>RFC3548, The Base16, Base32, and Base64 Data Encoding</li>
</li>
</ul>

===Error codes for $SNDMAIL===

The $SNDMAIL function issues a return code. An error in $SNDMAIL gives a return code of -1, and it is $StatusD that contains the error code. 

The negative error codes starting with -999 are listed in [[#Handling error condition return codes|Handling error condition return codes]]. 

It is also possible that $SNDMAIL will return a positive error code, which comes from TCP/IP and is documented in the IBM TCP/IP documentation, TCP/IP V3.2 for MVS: API Reference, Appendix D. For example, an error code of 60 means that the connection attempt timed out. $SOCKET calls give the same errors.

However, in the case of a non-zero (error) return code, the following message is issued to the user:
M204.2799: $SNDMAIL ERROR errortext


When an attempt is made to set or reset the SMTPCADD or SMTPSADD parameters and the address translation fails, <var class="product">Model 204</var> issues the following messages:
RESET SMTPCADD CCAGGGG

*** M204.2834: ADDRESS LOOKUP FAILED FOR CCAGGGG
*** 1 M204.1123: PARAMETER SMTPCADD NOT RESET


===Handling error condition return codes===

[[#Handling error condition return codes|Handling error condition return codes]] lists the possible $SOCKET return codes.

<table>
<caption>$Socket return codes</caption>
<tr class="head">
<th>SMTP
Error text </th>
<th>Numeric
value </th>
<th>
Meaning</th>
</tr>
<tr>
<td>ERBADARG </td>
<td>-999 </td>
<td>BAD ARGUMENT</td>
</tr>
<tr>
<td>ERNOTOPN </td>
<td>-998 </td>
<td>NOT OPEN</td>
</tr>
<tr>
<td>ERNOSTOR </td>
<td>-997 </td>
<td>NO STORAGE</td>
</tr>
<tr>
<td>ERIMAGER </td>
<td>-996 </td>
<td>IMAGE FAILURE</td>
</tr>
<tr>
<td>ERBADLNK </td>
<td>-995 </td>
<td>BAD LINK</td>
</tr>
<tr>
<td>ERNOTREL </td>
<td>-994 </td>
<td>SOCD NOT RELEASED</td>
</tr>
<tr>
<td>ERPHYERR </td>
<td>-993 </td>
<td>LINK DEAD</td>
</tr>
<tr>
<td>ERNOLINK </td>
<td>-992 </td>
<td>LINK UNKNOWN</td>
</tr>
<tr>
<td>ERTRUNC </td>
<td>-991 </td>
<td>VARIABLE TRUNCATION (READ CALL)</td>
</tr>
<tr>
<td>ERNOSOCK </td>
<td>-990 </td>
<td>SOCKET NOT FOUND</td>
</tr>
<tr>
<td>ERTRUNC2 </td>
<td>-989 </td>
<td>TRUNCATION ERROR ON IMAGE</td>
</tr>
<tr>
<td>EROPSYS </td>
<td>-988 </td>
<td>FUNCTION UNSUPPORTED ON THIS OPSYS</td>
</tr>
<tr>
<td>  </td>
<td>-987 </td>
<td>Not used</td>
</tr>
<tr>
<td>ERNOSRCD </td>
<td>-986 </td>
<td>NO SRCD</td>
</tr>
<tr>
<td>ERFDSLIM </td>
<td>-985 </td>
<td>TOO MANY SOCKETS</td>
</tr>
<tr>
<td>ERBADUBN </td>
<td>-984 </td>
<td>UNIVERSAL BUFFER NOT THERE</td>
</tr>
<tr>
<td>ERBADUBL </td>
<td>-983 </td>
<td>UNIVERSAL BUFFER LENGTH ERROR</td>
</tr>
<tr>
<td>ERBADUBA </td>
<td>-982 </td>
<td>UNIVERSAL BUFFER ALLOCATION ERROR</td>
</tr>
<tr>
<td>EREMREAD </td>
<td>-981 </td>
<td>ERROR WITH EMAIL SERVER READ</td>
</tr>
<tr>
<td>EREMWRIT </td>
<td>-980 </td>
<td>ERROR WITH EMAIL SERVER WRITE</td>
</tr>
<tr>
<td>ERGHBERR </td>
<td>-979 </td>
<td>SKIP=0 ERROR ON GETHOST CALL</td>
</tr>
<tr>
<td>ERGHERR1 </td>
<td>-978 </td>
<td>T1 LT 0 ERROR ON GETHOST CALL</td>
</tr>
<tr>
<td>ERGHERR2 </td>
<td>-977 </td>
<td>NO ADDRESSES RETURNED</td>
</tr>
</table>



When an error message (with code 5xx) is returned from the SMTP server, the following error message is displayed:
M204.2796: 'SMTP %C'



where %C is the error message returned by SMTP.


For the other error codes above, the following error message is returned, in addition to $StatusD being set.
M204.2799: '$SNDMAIL ERROR %C'


where %C is listed in the following table:
<table>
<caption>Error text message possibilities for M204.2799</caption>
<tr class="head">
<th>%C in message 2799 </th>
<th>$StatusD code(s)</th>
</tr>
<tr>
<td>IN PARAMETER </td>
<td>999</td>
</tr>
<tr>
<td>- SOCKET NOT FOUND </td>
<td>990</td>
</tr>
<tr>
<td>- FUNCTION NOT SUPPORTED ON THIS SYSTEM </td>
<td>998</td>
</tr>
<tr>
<td>- NO SRCD </td>
<td>986</td>
</tr>
<tr>
<td>- TOO MANY SOCKETS </td>
<td>985</td>
</tr>
<tr>
<td>WITH UNIVERSAL BUFFER </td>
<td>984, 983, 982</td>
</tr>
<tr>
<td>Reading from SMTP server </td>
<td>981</td>
</tr>
<tr>
<td>Writing to SMTP server </td>
<td>980</td>
</tr>
<tr>
<td>Using GETHOSTBYNAME lookup </td>
<td>979, 978, 977</td>
</tr>
<tr>
<td>GETTING STORAGE </td>
<td>997</td>
</tr>
<tr>
<td>IN IMAGE PROCESSING </td>
<td>996</td>
</tr>
<tr>
<td>WITH TCP LINK </td>
<td>995, 998, 993, 992</td>
</tr>
<tr>
<td>- SOCD NOT RELEASED </td>
<td>994</td>
</tr>
<tr>
<td>READING DATA - TRUNCATION </td>
<td>991</td>
</tr>
</table>

==Summary of standard functions==


The following table lists the standard <var class="product">SOUL</var> functions in alphabetical order. 



See also:
<ul>
<li>[[SOUL $functions#Using_functions|Using functions]] reviews coding in <var class="product">SOUL</var> with $functions.
<li>[[List of $functions]] contains the many additional $functions available as of version 7.5 of <var class="product">Model 204</var>.
</ul>
<table>
<tr class="head">
<th>Function</th>
<th>Returns...</th>
</tr>
<tr>
<td>[[$Account]]</td>
<td>Account under which the user is logged in.</td>
</tr>
<tr>
<td>[[$Acct]]</td>
<td>User ID under which the user is logged in.</td>
</tr>
<tr>
<td>[[$Alpha]]</td>
<td>Whether a string is composed of only the letters A through Z.</td>
</tr>
<tr>
<td>[[$AlphNum]]</td>
<td>Whether a string is composed of only the letters A through Z and digits 0 through 9.</td>
</tr>
<tr>
<td>[[$ArrSize]]</td>
<td>Number of elements in a particular dimension of an array.</td>
</tr>
<tr>
<td>[[$Ascii]]</td>
<td>Input string, converted from EBCDIC to ASCII.</td>
</tr>
<tr>
<td>[[$Binary]]</td>
<td>A number converted into fixed-point binary.</td>
</tr>
<tr>
<td>[[$BldProc]]</td>
<td>Enables a request to build a temporary procedure.</td>
</tr>
<tr>
<td>[[$Buffer_Position]]</td>
<td>Current Universal Buffer position.</td>
</tr>
<tr>
<td>[[$Buffer_Size]]</td>
<td>Size of user's Universal Buffer.</td>
</tr>
<tr>
<td>[[$Buffer_Used]]</td>
<td>Amount of data currently in Universal Buffer</td>
</tr>
<tr>
<td>[[$CenqCt]]</td>
<td>Number of unused entries within the resource enqueuing table.</td>
</tr>
<tr>
<td>[[$ChkMod]]</td>
<td>Whether the terminal operator entered data in any full-screen input field.</td>
</tr>
<tr>
<td>[[$ChkTag]]</td>
<td>Whether any erroneous full-screen input has been entered by the end user.</td>
</tr>
<tr>
<td>[[$ChkPat]]</td>
<td>Syntax of a pattern.</td>
</tr>
<tr>
<td>[[$Code]]</td>
<td>Encoding facility.</td>
</tr>
<tr>
<td>[[$Curfile]]</td>
<td>Name of the file from which the current record has been selected.</td>
</tr>
<tr>
<td>[[$Currec]]</td>
<td>Integer equal to the internal number of the current record.</td>
</tr>
<tr>
<td>[[$C2X]]</td>
<td>A translation of each byte within a character string to its two-byte
hexadecimal representation.</td>
</tr>
<tr>
<td>[[$Date]]</td>
<td>Current date in yy-mm-dd format.</td>
</tr>
<tr>
<td>[[$DateChg]]</td>
<td>Specified number of days, added to or subtracted from a given date.</td>
</tr>
<tr>
<td>[[$DateChk]]</td>
<td>Whether a given date is valid.</td>
</tr>
<tr>
<td>[[$DateCnv]]</td>
<td>Date converted to a format specified by the user.</td>
</tr>
<tr>
<td>[[$DateDif]]</td>
<td>Difference in days between two dates.</td>
</tr>
<tr>
<td>[[$DateP]]</td>
<td>Current date in "dd mon yy" format.</td>
</tr>
<tr>
<td>[[$DayI]]</td>
<td>Number reflecting current day of the week.</td>
</tr>
<tr>
<td>[[$Deblank]]</td>
<td>Substring of a string, with leading and trailing blanks removed.</td>
</tr>
<tr>
<td>[[$Decode]]</td>
<td>Decoding facility.</td>
</tr>
<tr>
<td>[[$Dscr]]</td>
<td>Decoding facility.</td>
</tr>
<tr>
<td>[[$Dsn]]</td>
<td>Data set name when you specify a file's DD name and the ordinal number.</td>
</tr>
<tr>
<td>[[$DsnNum]]</td>
<td>Total number of data sets defined for a file when you specify the file's DD name.</td>
</tr>
<tr>
<td>[[$EcfStat]]</td>
<td>Returns the detailed completion code from the previous EXTERNAL statement.</td>
</tr>
<tr>
<td>[[$Edit]]</td>
<td>Edited numeric and alphanumeric text</td>
</tr>
<tr>
<td>[[$Eformat]]</td>
<td>Exponent notations from converted numeric values</td>
</tr>
<tr>
<td>[[$Encrypt]]</td>
<td>A one-way encryption of a character string.</td>
</tr>
<tr>
<td>[[$Enter]]</td>
<td>Efficient terminal dialogue with users of data entry applications.</td>
</tr>
<tr>
<td>[[$Errmsg]]</td>
<td>Prefix and text of the last counting error or request cancellation message received.</td>
</tr>
<tr>
<td>[[$FDef]]</td>
<td>String that describes the attributes of a field in a <var class="product">Model 204</var> file.</td>
</tr>
<tr>
<td>[[$FieldgroupId]]</td>
<td>The ID of the current field group. (Available as of Model 204 version 7.5.)</td>
</tr>
<tr>
<td>[[$FieldgroupOccurrence]]</td>
<td>The current occurrence number of the field group. (Available as of Model 204 version 7.5.)</td>
</tr>
<tr>
<td>[[$FldLen]]</td>
<td>Length of a field.</td>
</tr>
<tr>
<td>[[$Float]]</td>
<td>Floating-point to a 4-byte string without conversion (4-byte floating point number to a 4-byte string).</td>
</tr>
<tr>
<td>[[$FloatD]]</td>
<td>Floating-point to a 4-byte string without conversion (8-byte floating point number to an 8-byte string). </td>
</tr>
<tr>
<td>[[$FlsAcc]]</td>
<td>User's access rights to a particular field.</td>
</tr>
<tr>
<td>[[$FlsChk]]</td>
<td>Whether a given set of field level security accesses is valid for a field.</td>
</tr>
<tr>
<td>[[$Fsterr]]</td>
<td>Variable-length string containing the prefix and the first counting error message or request cancellation message received by the user since the last time the count was reset to zero.</td>
</tr>
<tr>
<td>[[$Getg]]</td>
<td>Information stored by a $SETG function.</td>
</tr>
<tr>
<td>[[$GetL]]</td>
<td>Line number of the current line on the page on the user's terminal or on the output data set specified by a USE command.</td>
</tr>
<tr>
<td>[[$GetP]]</td>
<td>Page number currently on the user's terminal or on the output data set specified by a USE command.</td>
</tr>
<tr>
<td>[[$GrmLoc]]</td>
<td>Location of a missing member.</td>
</tr>
<tr>
<td>[[$GrmName]]</td>
<td>File name of a missing member.</td>
</tr>
<tr>
<td>[[$GrnLeft]]</td>
<td>Number of optional files that may fail before MAXFAIL is exceeded.</td>
</tr>
<tr>
<td>[[$GrnMiss]]</td>
<td>Number of missing members.</td>
</tr>
<tr>
<td>[[$HPage]]</td>
<td>String of special characters whose length is equal to the value specified as the $HPage argument.</td>
</tr>
<tr>
<td>[[$Hsh]]</td>
<td>A hash value from a converted string value. A hash value is a distinct numeric representation of a given string value.</td>
</tr>
<tr>
<td>[[$Incrg]]</td>
<td>Performs simple arithmetic on global variables.</td>
</tr>
<tr>
<td>[[$Index]]</td>
<td>After comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $SCAN.</td>
</tr>
<tr>
<td>[[$Itsopen]]</td>
<td>Whether or not a file is open.</td>
</tr>
<tr>
<td>[[$Itsremote]]</td>
<td>Whether the current file or group is remote or scattered.</td>
</tr>
<tr>
<td>[[$Jobcode]]</td>
<td>Allows a request that is part of one step of a <var class="product">Model 204</var> batch run to communicate with a subsequent step.</td>
</tr>
<tr>
<td>[[$LangSpc]]</td>
<td>String containing the binary value of a character in a specified language.</td>
</tr>
<tr>
<td>[[$LangSrt]]</td>
<td>A binary string translated to sort according to the NLSORT macro for the specified language.</td>
</tr>
<tr>
<td>[[$LangUst]]</td>
<td>Previously $LangSrt'ed string translated back to its original form.</td>
</tr>
<tr>
<td>[[$Len]]</td>
<td>Length of a value in a field.</td>
</tr>
<tr>
<td>[[$Lowcase]]</td>
<td>A lower case string translated from an uppercase or mixed case string</td>
</tr>
<tr>
<td>[[$LstFld]]</td>
<td>Field names in a file, along with their field descriptions, into an image.</td>
</tr>
<tr>
<td>[[$LstProc]]</td>
<td>Information that is stored for a procedure.</td>
</tr>
<tr>
<td>[[$MisGrup]]</td>
<td>Group name if the error occurred in group context, null if in file context.</td>
</tr>
<tr>
<td>[[$MisName]]</td>
<td>File name of a missing member or file.</td>
</tr>
<tr>
<td>[[$MisNum]]</td>
<td>Number of files that failed in a group.</td>
</tr>
<tr>
<td>[[$MisLoc]]</td>
<td>Location of a missing member or file.</td>
</tr>
<tr>
<td>[[$MisStmt]]</td>
<td>Statement that caused the ON unit to be entered.</td>
</tr>
<tr>
<td>[[$Mod]]</td>
<td>Remainder that results when one argument is divided by the another argument.</td>
</tr>
<tr>
<td>[[$Occurs]]</td>
<td>Whether a field has the OCCURS attribute.</td>
</tr>
<tr>
<td>[[$Oneof]]</td>
<td>Table lookup that can replace a series of IF conditions.</td>
</tr>
<tr>
<td>[[$Pack]]</td>
<td>Packed decimal representation of a string.</td>
</tr>
<tr>
<td>[[$Pad]]</td>
<td>Designated character padded to the left.</td>
</tr>
<tr>
<td>[[$PadR]]</td>
<td>Designated character padded to the right</td>
</tr>
<tr>
<td>[[$RdProc]]</td>
<td>Lines of a User Language procedure, retrieved in sequential order, that is stored in a <var class="product">Model 204</var> file.</td>
</tr>
<tr>
<td>[[$Read]]</td>
<td>An echo of the data a user enters as a request is evaluated</td>
</tr>
<tr>
<td>[[$ReadInv]]</td>
<td>Performs the same function as $READ, except that input from the terminal is not echoed.</td>
</tr>
<tr>
<td>[[$ReadLc]]</td>
<td>An echo of the data a user enters as a request is evaluated, except that case translation is deactivated, regardless of the current *UPPER or *LOWER setting.</td>
</tr>
<tr>
<td>[[$Remote]]</td>
<td>VTAMNAME value of the originating <var class="product">Model 204</var> region when using SNA Communications Server (formerly VTAM) TRANSFER to transfer between <var class="product">Model 204</var> regions.</td>
</tr>
<tr>
<td>[[$Reverse]]</td>
<td>Reversed order of a string.</td>
</tr>
<tr>
<td>[[$RlcFile]]</td>
<td>Name of the file in which the last record locking conflict occurred.</td>
</tr>
<tr>
<td>[[$RlcRec]]</td>
<td>Internal record number for which the last record locking conflict occurred.</td>
</tr>
<tr>
<td>[[$RlcUid]]</td>
<td>ID of the user who caused an ON FIND CONFICT or ON RECORD LOCKING CONFLICT. If the conflicting user is on a remote node, $RLCUID also returns the name of the node.</td>
</tr>
<tr>
<td>[[$RlcUsr]]</td>
<td>User number of the user with which the request conflicted when the last record locking conflict occurred.</td>
</tr>
<tr>
<td>[[$Round]]</td>
<td>Number, rounded to a specified number of decimal places.</td>
</tr>
<tr>
<td>[[$Scan]]</td>
<td>After comparing two strings, a number equal to the first position within the first string at which the second string appears; the same function as $INDEX.</td>
</tr>
<tr>
<td>[[$Sclass]]</td>
<td>Current user's subsystem user class.</td>
</tr>
<tr>
<td>[[$Setg]]</td>
<td>A created or changed entry in the global variable section of GTBL.</td>
</tr>
<tr>
<td>[[$SetL]]</td>
<td>Sets the current line counter for the output device currently in effect.</td>
</tr>
<tr>
<td>[[$SetP]]</td>
<td>Sets the current page number for the output device currently in effect.</td>
</tr>
<tr>
<td>[[$Slstats]]</td>
<td>Resets the recording of since-last statistics anywhere within a request.</td>
</tr>
<tr>
<td>[[$Sndx]]</td>
<td>SOUNDEX code of an argument.</td>
</tr>
<tr>
<td>[[$Square]]</td>
<td>A number multiplied by itself.</td>
</tr>
<tr>
<td>[[$Stat]]</td>
<td>Current value of any user statistic.</td>
</tr>
<tr>
<td>[[$Status]]</td>
<td>The success or failure of the last executed external I/O or program communication statement.</td>
</tr>
<tr>
<td>[[$StatusD]]</td>
<td>More detailed description of a condition returned by $STATUS.</td>
</tr>
<tr>
<td>[[$Strip]]</td>
<td>A number with suppressed leading zeros.</td>
</tr>
<tr>
<td>[[$Substr]]</td>
<td>Substring of a string.</td>
</tr>
<tr>
<td>[[$Subsys]]</td>
<td>Status of an APSY subsystem.</td>
</tr>
<tr>
<td>[[$Time]]</td>
<td>Current time in hh:mm:ss format.</td>
</tr>
<tr>
<td>[[$Unbin]]</td>
<td>Value converted from binary to string representation.</td>
</tr>
<tr>
<td>[[$Unblank]]</td>
<td>Contents of an argument, removing leading and trailing blanks, and compressing multiple embedded blanks to one blank character.</td>
</tr>
<tr>
<td>[[$Unfloat]]</td>
<td>Character string that represents a numeric counted string of 4 or 8 bytes, which contains a floating point.</td>
</tr>
<tr>
<td>[[$Unpack]]</td>
<td>Unpacked decimal data </td>
</tr>
<tr>
<td>[[$UnqRec]]</td>
<td>

In the case of a uniqueness violation, returns the file-relative record number of the record that already contains the field name = value pair

If no uniqueness violation occurred. returns -1.
</td>
</tr>
<tr>
<td>[[$Upcase]]</td>
<td>An uppercase string converted from a lower or mixed case string.</td>
</tr>
<tr>
<td>[[$Update]]</td>
<td>Name of the group update file or the current file.</td>
</tr>
<tr>
<td>[[$UpdFld]]</td>
<td>Name of the field for which a field level constraint violation has occurred, or a blank if no violation occurred.</td>
</tr>
<tr>
<td>[[$UpdFile]]</td>
<td>Name of the file in which a field level constraint violation has occurred, or a blank if no violation occurred.</td>
</tr>
<tr>
<td>[[$UpdLoc]]</td>
<td>Location name (node name) of the current update unit (Parallel Query Option/204 only).</td>
</tr>
<tr>
<td>[[$UpdOval]]</td>
<td>Value of the original field occurrence causing a constraint violation, when invoked from an ON FCC unit following the detection of an AT-MOST-ONE field-level constraint conflict. </td>
</tr>
<tr>
<td>[[$UpdRec]]</td>
<td>File-relative record number of the record whose update caused a field level constraint violation, or -1 if no violation occurred.</td>
</tr>
<tr>
<td>[[$UpdStat]]</td>
<td>Numeric value denoting the type of field level constraint violation that has occurred, or 0 if no violation occurred.</td>
</tr>
<tr>
<td>[[$UpdStmt]]</td>
<td>Type of User Language updating statement causing a field level constraint violation, or a blank if no violation occurred.</td>
</tr>
<tr>
<td>[[$UpdVal]]</td>
<td>Field value causing a field level constraint violation, or a blank if no violation occurred.</td>
</tr>
<tr>
<td>[[$User]]</td>
<td>User's user number.</td>
</tr>
<tr>
<td>[[$Userid]]</td>
<td>User ID under which the user is logged in.</td>
</tr>
<tr>
<td>[[$UsrPriv]]</td>
<td>Whether a user ID has been granted specific <var class="product">Model 204</var> privileges.</td>
</tr>
<tr>
<td>[[$Verify]]</td>
<td>Whether every character in one string is present in a second string.</td>
</tr>
<tr>
<td>[[$View]]</td>
<td>Value of a parameter.</td>
</tr>
<tr>
<td>[[$Vnum]]</td>
<td>Whether a given argument is in a valid format for a SORT BY VALUE NUMERICAL statement or for any type of mathematical operation.</td>
</tr>
<tr>
<td>[[$Word]]</td>
<td>P word in a specified string, delimited by a blank or optionally specified character.</td>
</tr>
<tr>
<td>[[$Words]]</td>
<td>Number of words in a specified string, delimited by a blank or optionally specified character.</td>
</tr>
<tr>
<td>[[$X2C]]</td>
<td>One-byte EBCDIC characters translated from a string of 2-byte hexadecimal character.</td>
</tr>
</table>

[[Category:SOUL]]

$WORDS

2014-07-31T18:57:32Z

Mlarocca: Mlarocca moved page $WORDS to $Words: Lower case change

#REDIRECT [[$Words]]

$Words

2014-07-31T18:57:31Z

Mlarocca: Mlarocca moved page $WORDS to $Words: Lower case change

The $WORDS function returns the number of words in a specified string, delimited by a blank or optionally specified character.
Syntax
The format of the $WORDS function is:
$WORDS('inputstring', <var>[</var>'delimiter'<var>]</var>)

where:
<ul>
<li>inputstring is the input from which the specified word is to be extracted. inputstring can be a quoted literal or a %variable.</li>
</li>
<li>delimiter is an optional character to be used as a delimiter in parsing the input string into words. If delimiter is not specified, it defaults to a blank space. </li>
</li>
</ul>
Usage
Null values between delimiters are not considered words. For example,
$WORDS('ABC==D=XXX','=')

returns a count of three words, not four.
Example
The following function returns 4, the number of words in the string when a blank delimits a word:
$WORDS ('NOW IS THE TIME')

[[Category:SOUL $functions]]

$WORD

2014-07-31T18:57:04Z

Mlarocca: Mlarocca moved page $WORD to $Word: Lower case change

#REDIRECT [[$Word]]

$Word

2014-07-31T18:57:04Z

Mlarocca: Mlarocca moved page $WORD to $Word: Lower case change

The $WORD function searches a string from the left for a complete word and returns the nth word in a specified string, delimited by a blank or optionally specified character.
Syntax
The format of the $WORD function is:
$WORD('inputstring',['delimiter'],<var>[</var>n<var>]</var>)

where:
<ul>
<li>inputstring is the input from which the specified word is to be extracted. inputstring can be a quoted literal or a %variable.</li>
</li>
<li>delimiter is an optional quoted character or string to be used as a delimiter in parsing the input string into words. If delimiter is not specified, it defaults to a blank space. If delimiter consists of more than one character, <var class="product">Model 204</var> uses the first character in the string as the delimiter.</li>
</li>
<li>n is the ordinal number of the word to be extracted. $WORD returns a null string under any of the following conditions:</li>
</li>
</ul>
n is not specified
n is less than 1 (0 or negative)
n is greater than the number of words in inputstring
The commas which separate the three arguments are required, even if delimiter is not specified.
Usage
Null values between delimiters are not considered words. For example, 
$WORD('=ABCD==D=XXX','=',2)

returns D as the second word, not a null value.
Examples
The following function returns the third word in the string, "THE", when a single space delimits a word:
$WORD ('NOW IS THE TIME',,3)

The following function returns the second word in the string, "S THE T", where a word is composed of the characters that precede a delimiting I:
$WORD ('NOW IS THE TIME','I',2)

[[Category:SOUL $functions]]

$VNUM

2014-07-31T18:55:45Z

Mlarocca: Mlarocca moved page $VNUM to $Vnum: Lower case change

#REDIRECT [[$Vnum]]

$Vnum

2014-07-31T18:55:45Z

Mlarocca: Mlarocca moved page $VNUM to $Vnum: Lower case change

The $VNUM function returns a 1 if the given argument is in a valid format for a SORT BY VALUE NUMERICAL statement or for any type of mathematical operation. To be valid, the argument must be a quoted rational number with optional sign. Leading or trailing blanks, or blanks between the sign and the number, are ignored. If the contents of the argument do not have the required form, 0 is returned. Numeric values with more than 63 significant digits are not in the correct form; a 0 is returned. 
Syntax
$VNUM(numeric-string-value{,'SORT' | 'SORTKEY' | 'FLOAT' | 'BINARY'})

Where:
<ul>
<li>SORTKEY returns 1 if the numeric value is valid as a numeric string sortkey. See [[Sorting#NUMERICAL option|NUMERICAL option]]. A numeric string sortkey value that is not acceptable to $VNUM as a SORTKEY value is sorted in character order even if the SORT statement specifies numeric order.</li>
The following compression rules apply to SORTKEY:
</li>
</ul>
Leading plus (+) or minus (-) sign is compressed.
Leading blanks before and after the (optional) leading +/- sign are compressed.
Leading zeros after the (optional) leading +/- sign and blanks are compressed.
1-63 integer digits before the (optional) decimal point are allowed.
Values greater than -1 and less than 1 require leading "0.nnn".
Optional decimal point and fractional value are allowed.
Trailing blanks are compressed.
1-253-byte total length is allowed.
<ul>
<li>'FLOAT' returns 1 if the numeric value is valid as an E-format floating point numeric string. </li>
</li>
<li>'BINARY' returns 1 if the numeric value is valid as a compressible binary value (to be stored in a BINARY NON-CODED field). See [[Data maintenance#Storing values in BINARY fields|Storing values in BINARY fields]]. Otherwise returns a 0.</li>
The following compression rules apply to BINARY:
</li>
</ul>
1-9 decimal integer values are allowed.
No leading zeros are compressed.
Leading plus (+) sign is compressed.
Leading minus (-) sign is allowed.
Example 1
$VNUM(' + 256.73 ') equals 1
$VNUM('14') equals 1
$VNUM('-17.17') equals 1
$VNUM('.1794763') equals 1

Example 2
$VNUM(' -256.73 AB') equals 0
$VNUM('256.73-') equals 0
$VNUM(' TWELVE') equals 0

Example 3
This example averages premium amounts. The amounts are included in the average only if they meet the $VNUM specifications.
BEGIN
%CT IS FLOAT
GET.RECS: FIND ALL RECORDS
END FIND
FOR EACH RECORD IN GET.RECS
IF $VNUM(TOTAL PREMIUM) THEN
%TOT = %TOT + TOTAL PREMIUM
%CT = %CT + 1
END IF
END FOR
%AVERAGE = %TOT/%CT
PRINT 'THE AVERAGE PREMIUM IS ' -
WITH '$' WITH %AVERAGE
END

[[Category:SOUL $functions]]

Files, groups, and reference context

2014-07-31T18:54:50Z

Mlarocca:

<div class="toclimit-3">
==Overview==

A <var class="product">Model 204</var> file consists of a collection of records and their associated index pointers. See [[Introduction to User Language#Files|Files]] for a discussion of the composition of a <var class="product">Model 204</var> file. A file group is a collection of <var class="product">Model 204</var> files that <var class="product">Model 204</var> treats as a logical single file. A group can be permanent, temporary, or ad hoc. 

A file or group must be opened before it can be processed by <var class="product">Model 204</var>. Several files or groups can be opened by a terminal user during a single <var class="product">Model 204</var> session. 

You can refer to any open files or groups within a single request and can cross-reference any records contained in these files or groups.
(Cross-referencing is discussed in [[Record loops#Cross-referencing|Cross-referencing]] and also in [[#Cross-referencing|Cross-referencing]].)

The file and group commands discussed in this topic are described in detail in
[[List of Model 204 parameters]] and [[List of Model 204 commands]].

===Parallel Query Option/204===
Parallel Query Option/204 (PQO) is a <var class="product">Model 204</var> distributed processing facility that allows the sharing of data between two or more copies of <var class="product">Model 204</var>.

In addition to the information provided in this manual, Parallel Query Option/204 is described in detail in the <var class="book">Rocket Parallel Query Option/204 User's Guide</var>. 

===Remote files===
Parallel Query Option/204 provides to <var class="product">SOUL</var> applications the potential for accessing data stored in remote files. A single <var class="product">SOUL</var> request can read and/or update multiple remote files.

===Scattered groups===

Parallel Query Option/204 also supports file groups consisting of files residing on different nodes. A group that contains one or more remote files is a scattered group. A scattered group is a local entity — you cannot create a group for a remote node, and you cannot refer to a group defined on a remote node.

As for all <var class="product">Model 204</var> groups, you define a scattered group with the <var class="product">SOUL</var> IN clause or the CREATE GROUP command. The authority required to define a scattered group is no different from that required for a non-scattered <var class="product">Model 204</var> group. 

Ad hoc, temporary, and permanent groups can be scattered groups. With no additional requirements, ad hoc groups allow remote file synonyms and remote file specifications. With some additional parameter requirements, temporary and permanent groups allow remote file synonyms and remote file specifications.

Scattered group members are optional or mandatory. If a mandatory member is unavailable, the group cannot open. You specify whether members are optional or mandatory in the group definition. Availability, a file status that concerns scattered groups, refers to whether a group member can be opened and, if not, whether the group can be opened. These terms are discussed in more detail in the <var class="book">Rocket Parallel Query Option/204 User's Guide</var>. 

===DML limitations===

Not all <var class="product">Model 204</var> commands, statements and retrieval conditions can be used with Parallel Query Option/204. [[#Using Model 204 file and group commands|Using Model 204 file and group commands]] lists the file and group specification commands that you can use with remote files and groups. [[DML statements in Parallel Query Option/204#DML statements in Parallel Query Option/204|DML statements in Parallel Query Option/204]] contains listings of supported and non-supported <var class="product">SOUL</var> statements and retrieval conditions.

==Using Model 204 file and group commands==

[[#Using Model 204 file and group commands|Using Model 204 file and group commands]] lists file and group commands, their corresponding meanings, and what type of user can issue the command. This list comprises the only commands that support remote file specification.

<table>
<caption>Commands for files and groups</caption>
<tr class="head">
<th>Command</th>
<th>Meaning</th>
<th>Type of user</th>
</tr>

<tr>
<td>CLOSE (file or group)</td>
<td>Closes a group.</td>
<td>Any user</td>
</tr>

<tr>
<td>CREATE PERM GROUP</td>
<td>Creates a permanent group.</td>
<td>System manager</td>
</tr>

<tr>
<td>CREATE TEMP GROUP</td>
<td>Creates a temporary group.</td>
<td>Any user</td>
</tr>

<tr>
<td>DEFAULT</td>
<td>Specifies a new default, which can be either a <var class="product">Model 204</var> file or group</td>
<td>Any user</td>
</tr>

<tr>
<td>DEFINE FILE</td>
<td>Creates a file synonym, defined locally, for the actual name of a local or remote file and its location.</td>
<td>System manager or User 0</td>
</tr>

<tr>
<td>DELETE PERM GROUP</td>
<td>Deletes a permanent group.</td>
<td>System manager</td>
</tr>

<tr>
<td>DELETE TEMP GROUP</td>
<td>Deletes a temporary group.</td>
<td>Any user</td>
</tr>

<tr>
<td>DISABLE SUBSYSTEM</td>
<td>Marks a service subsystem file or group as disabled, making it unavailable to users who try to access it through the subsystem.</td>
<td>System manager</td>
</tr>

<tr>
<td>DISPLAY
(field, group, or record)</td>
<td>Displays information about one or more objects.</td>
<td>Any user</td>
</tr>

<tr>
<td>ENABLE SUBSYSTEM</td>
<td>Enables a disabled subsystem remote file or group.</td>
<td>System manager</td>
</tr>

<tr>
<td nowrap>MONITOR SUBSYSTEM</td>
<td>Displays information about Parallel Query Option/204 service subsystem files and groups.</td>
<td>Any user</td>
</tr>

<tr>
<td>OPEN[C] FILE</td>
<td>Opens a file. Multiple files can be open simultaneously during a <var class="product">Model 204</var> session. OPEN changes the existing default. OPENC does not.</td>
<td>Any user</td>
</tr>

<tr>
<td>OPEN[C] GROUP</td>
<td>Opens a group. Multiple groups can be open simultaneously during a <var class="product">Model 204</var> session. OPEN changes the existing default. OPENC does not.</td>
<td>Any user</td>
</tr>

<tr>
<td>START (file or group)</td>
<td>Reverses the effect of the STOP command.</td>
<td>System manager</td>
</tr>

<tr>
<td>STATUS</td>
<td>Displays recovery information about remote <var class="product">Model 204</var> files that were opened during an online run.</td>
<td>Any user</td>
</tr>

<tr>
<td>STOP (file or group)</td>
<td>Prevents a remote file or permanent scattered group from being opened. The STOPped file or group cannot be opened until it is STARTed. STOP and START cannot be used with temporary groups.</td>
<td>System manager</td>
</tr>

<tr>
<td>VIEW</td>
<td>Displays the current settings of <var class="product">Model 204</var> parameters.</td>
<td>Any user</td>
</tr>
</table>


Also supported in PQO are the BUMP, LOGWHO, and MONITOR commands, as well as network control and definition commands and subsystem control commands.

The OPEN[C] FILE, OPEN[C] GROUP, CLOSE, DEFAULT, and DELETE GROUP commands are discussed in this topic. For more information on the other commands in [[#Using Model 204 file and group commands|Using Model 204 file and group commands]], see:
<ul>
<li>[[List of Model 204 parameters]] and [[List of Model 204 commands]]</li>
<li><var class="book">Rocket Parallel Query Option/204 User's Guide</var></li>
</ul>

==File groups==

This section describes the composition and advantages of using <var class="product">Model 204</var> file groups, then discusses how you create, access, and manipulate file groups.

===Composition of a Model 204 group===

A file group is a collection of <var class="product">Model 204</var> files that <var class="product">Model 204</var> treats logically as a single file. File groups do not contain data and pointers, but rather a list of files, each of which contains its own data and pointers. When a group is defined, <var class="product">Model 204</var> creates an entry in an internal table. This entry contains the names of the files that make up the group.

Commands and statements that refer to a group actually cause operations to be performed on each member file. An individual file can be a member of several different groups and a group can contain up to 256 <var class="product">Model 204</var> files. 

File groups are particularly helpful in working with cyclic data and in organizing independent but similar files. File groups also provide an alias facility. 

===Using a group to work with cyclic data===

Suppose that the file group WEEK consists of the files SUNDAY, MONDAY, TUESDAY, WEDNSDAY (maximum eight letters), THURSDAY, FRIDAY, and SATURDAY. While the union of these seven files is available under the name WEEK, each daily file continues to be accessible as an individual file. The data is not duplicated; an internal table relates WEEK to its member files. WEEK can be defined to include member files that do not yet exist, but it cannot be opened until all member files have been created.

Suppose you want the group WEEK to always contain data from the most recent seven-day period. The conventional approach to this problem is to perform an expensive daily update, adding the newest day's data to a file and deleting the oldest day's data. However, the group facility provides a more efficient and convenient alternative. 

Each time a new daily file is created, the older daily file (of the same name) is taken off line and archived. If the files must be preserved in chronological order, the definition of the group is modified to reflect the seven most recent daily files. This approach does not require data deletion, file reorganization, or program changes. The archived daily files can be saved permanently in their <var class="product">Model 204</var> format and can be restored easily to operating status. 

===Using groups to work with independent but similar data===

Data concerning individual states or similar subdivisions is often kept in separate files. However, users sometimes require reports by various regional groupings or by an entire country. 

With file groups, one user can select a report to be run against a single file, for example, OHIO, while another user can generate a report from the regional collection, for example, OHIO, INDIANA, and ILLINOIS. A third user's report might take into account all 50 states (a group can contain as many as 256 files). 

All three of these reports can be generated by the same <var class="product">SOUL</var> request, using a different group definition or by specifying an alternative OPEN command. 

===Using groups as file aliases===

A group can consist of only one file, and can have the same name as an existing file. These two facts allow a group name to act as an alias for a <var class="product">Model 204</var> file. This allows for the possibility of users addressing a single file by many different names. 

Suppose several application programs have been written to operate on a file named FILEA. This file is subsequently merged with FILEB, and the new combined file named FILEC. None of the field names in the combined file have been changed, so application programs could continue to run with the new file. However, those programs open the file named FILEA, not the combined file named FILEC.

The file group feature provides a technique that enables application programs to access the correct file without undergoing a program change. The system manager can define a permanent file group named FILEA that is made up only of the file named FILEC. The application programs need not be changed. When they run, they automatically access the FILEA group.

A similar strategy can be helpful when testing programs with test files that have different names from those that are used during production. 

===Types of groups===

There are three types of groups:
<ul>
<li>Permanent groups are created by the system manager with CREATE. The group name and member list are stored permanently in a <var class="product">Model 204</var> file until explicitly deleted by the system manager. </li>

Any user can open a permanent group, unless the group requires a password, in which case the user must know the password. See the discussion about group passwords in [[#File and group passwords|File and group passwords]].
</li>
<li>Temporary groups are created by an individual user with the CREATE command and can be referenced only by that user. </li>

Temporary group names exist only during the current login session and are deleted automatically when you log out, unless you delete them during the session.
</li>
<li>Ad hoc groups have no name and are created within a <var class="product">SOUL</var> request by prefacing a statement with the clause: </li>
IN file1 [,file2 ...]


Ad hoc groups exist only for the current request. They allow record retrieval from many files at once without defining a group in advance. As in any IN clause, all of the files in an ad hoc group must be opened before the group is mentioned. Ad hoc groups are discussed in more detail in [[#Ad hoc groups|Ad hoc groups]]. 
</li>
</ul>

===Creating groups===

The CREATE command is used to create both permanent and temporary file groups. Only the system manager can create a permanent group. 

Any user can create a temporary group by entering:
CREATE [TEMP] GROUP groupname FROM filename [,filename ...]
[PARAMETER parameter list]
.
.
.
END


At least one file name is required. The following parameters can be included in the list. They are discussed in the description of the CREATE command, in [[List of Model 204 parameters]] and [[List of Model 204 commands]]. 
<ul>
<li>UPDTFILE — Defines the group's update file.</li>
</li>
<li>PROCFILE — Defines the group's procedure file.</li>
</li>
<li>BLDGFT — Creates a group's field table. </li>
</li>
</ul>

Specifying PROCFILE = * creates a group in which any files can contain procedures. 

===Deleting groups===

The DELETE command is used to delete both permanent and temporary groups (only the system manager can delete a permanent group): 
DELETE [PERM | TEMP] [GROUP] name


You must close a group before you can delete it. 

====Examples====

The following example shows the creation of a temporary group.
CREATE GROUP REGION FROM DELAWARE, MARYLAND, -
VIRGINIA
PARAMETER PROCFILE = VIRGINIA, BLDGFT = NO
END


The following example creates a permanent group with multiple procedure files: 
CREATE PERM GROUP REGION FROM DELAWARE, MARYLAND, -
VIRGINIA
PARAMETER PROCFILE = *, BLDGFT = NO
END


==Opening and closing Model 204 files and groups==

===Two ways to open files and groups===

OPEN/OPENC can be used as either a command or statement to open <var class="product">Model 204</var> files and groups. 
<ul>
<li>For a discussion of OPEN/OPENC as a statement, including error handling, see [[#OPEN or OPENC statement|OPEN or OPENC statement]]. </li>
</li>
<li>For a discussion of OPEN/OPENC as a command, see the [[List of Model 204 commands]].</li>
</li>
</ul>

====Using OPEN/OPENC as a command====

When used as a command, OPEN/OPENC opens a file or group and allows retrievals or other references to fields or data records for the file or group in the same request. It also allows updates to a file to be deferred. As a command, OPEN/OPENC can be used within a procedure but must be outside of the request (outside the BEGIN and END statements). 

====Using OPEN[C] as a statement====

When used as a statement, OPEN/OPENC opens a file or group but does not allow retrievals or other references to fields or data records for the file or group in the same request. It does not allow updates to a file to be deferred. As a statement, OPEN/OPENC must appear within the request (between the BEGIN and END statements). 

===Opening multiple files or groups===

You can open two or more <var class="product">Model 204</var> files or groups concurrently. When multiple files and/or groups are open, you can let <var class="product">Model 204</var> operate on the default file or group, or direct <var class="product">Model 204</var> to operate on a specific file or group. Within a single request, you can refer to any open files or groups and can cross-reference records contained in them. Each of these remains open until you issue a <var>[[CLOSE command|CLOSE]]</var> command or the <var>[[$Close]]</var> function for it, or issue the <code>CLOSE ALL</code> command. 

===Opening a remote file===

You open a remote file by issuing the OPEN FILE command using either the AT location clause or a file synonym. You can also use an OPEN GROUP command if the file is a member of a scattered group.

====File context====

You can open a file in single file context or in permanent group context. A file open as a member of a temporary group is considered open in single file context. You can open in a different context an already open file. Therefore, a remote file can be open in any or all of the following contexts at the same time: 
<ul>
<li>Single file </li>
</li>
<li>Permanent group </li>
</li>
<li>Multiple permanent group </li>
</li>
</ul>

====File locking behavior====

The locking behavior of the OPEN FILE command for a remote file is identical to that for a local file with regard to: 
<ul>
<li>Shared direct access storage devices (DASD)</li>
</li>
<li>System level resources</li>
</li>
<li>Application subsystems </li>
</li>
</ul>

See the
[http://m204wiki.rocketsoftware.com/images/8/80/M204_V7R4_System_Manager.pdf Rocket Model 204 System Manager's Guide] for information about the Lock Files/Groups application subsystem definition option.

====Field definition is restricted====

When the OPEN FILE command is successfully executed and a remote file is opened, the status of the file is open. The remote file's Table A is stored on the client system for as long as the file remains open.

While a remote file is open to any remote user, the fields cannot be redefined, deleted, or renamed on the server. Server online users receive a message that the file is in use. New fields, however, can be defined. 
Opening deferred update data sets

A file that is not in deferred update mode can be opened remotely. 

A file that is in deferred update mode can be opened remotely only when the file is a member of a service application subsystem. If a remote deferred update data set is specified in the OPEN FILE command, the open is rejected. 

===Opening a scattered group===

You open a remote file that is a member of a scattered group by issuing the OPEN GROUP command. OPEN GROUP for scattered temporary and permanent groups has the same syntax as for non-scattered groups. Password requirements and privileges for member files are also the same for scattered and non-scattered groups. 

In scattered group context, OPEN GROUP causes <var class="product">Model 204</var> to allocate conversations with each of the nodes that contain members of the scattered group (if such conversations do not already exist).

If scattered groups are defined to allow update privileges, all member files are opened with the indicated privileges when the group is successfully opened. For each remote file opened in group context, <var class="product">Model 204</var> displays a confirmation message with the file's name (non-synonym) and location, stating whether updates are allowed. 

===Opening non-Model 204 files===

Non-<var class="product">Model 204</var> files can be opened within a request by using the form of the OPEN statement described in [[Images#OPEN statement|OPEN statement]].

===File and group passwords===

Whether you must enter a password when you open a files or permanent group depends on which of the following access types was assigned to it:
<ul>
<li>Public</li>
</li>
<li>Semipublic</li>
</li>
<li>Private </li>
<table>
<tr class="head">
<th>If file or permanent
group is... </th>
<th>
Model 204...</th>
</tr>
<tr>
<td>Public </td>
<td>Opens it without asking for a file password when the OPEN command is issued. </td>
</tr>
<tr>
<td>Semipublic or private </td>
<td>

Asks you to enter a password during the OPEN operation. For:

Private file or permanent group, you must enter a password in order to open it. 

Semipublic files and permanent groups, the password is optional.
</td>
</tr>
</table>
</li>
</ul>

Passwords are specified differently for temporary file groups. Opening a temporary group is functionally equivalent to opening a series of files. As each file is opened, you are prompted for the file password, if one is required. The temporary group is opened only after all the files have been opened.

===File and group privileges===

The file manager determines the privileges associated with each password associated with a file or permanent group. The assigned privileges determine which operations you can perform on the data and procedures stored in the file or group. 

The file manager also determines the default privileges that are granted for public and semipublic files and permanent groups. The system manager must enter all file passwords and privileges into the system. 

The privileges for a temporary group are the most restrictive combination of member file privileges. This combination is defined through a logical AND of the privileges of the individual files in the group.

For an explanation of how the granting of privileges depends on the reference context of a command or a statement, see [[#Privileges according to reference context|Privileges according to reference context]].
For file security details, see [[:Category:Model 204 files|Model 204 files]] [[that link is nonsense here|??]]. 

===Displaying file and group information===

You can display information about one or more open files or groups with the <var>[[DISPLAY command|DISPLAY]]</var> command:
DISPLAY [FILE | [PERM | TEMP] GROUP]

[(option [, option ...])]

{ALL | name [, name ...]}


If you enter:
DISPLAY FILE ALL


<var class="product">Model 204</var> displays the file name and file parameters for all files that you currently have open. If the DISPLAY command is issued by a file manager, the display includes file data set names. You can also use DISPLAY to display selected or abbreviated file parameters for files, by specifying them as display options. 

If you enter:
DISPLAY GROUP ALL


<var class="product">Model 204</var> displays the group name, status (permanent or temporary), member files, and group parameters for all permanent groups and for your temporary groups. You can request that the command display only a list of group names and their status.

===Closing files and groups===

During a single <var class="product">Model 204</var> session, you can open several files and/or groups. These remain open until you issue a CLOSE command, as follows:
CLOSE [ALL | [FILE | [PERM | TEMP] GROUP] name [AT location]]


Closing a permanent group closes each file in the group that was opened by a group OPEN. But it does not close files that were opened as individual files or as members of other groups. Closing a temporary group does not close the files in the group. 

You can also close a file or group (with some restrictions) within a <var class="product">SOUL</var> request using the <var>[[$Close]]</var> function.

===OPEN statement and OPENC statement===

The OPEN and OPENC statements are useful for opening a file and allowing the request to take actions based on the current status of the file.
Only file parameters are available to the request that issues the OPEN or OPENC statement.
For example, the current status of the file can be determined by using the <var>[[$View|$View]]</var> function to return
the value of the <var>[[FISTAT parameter|FISTAT]]</var> to the request. 

File data is not available until the current request has ended evaluation; then a subsequent request may access the data in the file that was previously opened with the OPEN or OPENC statement. Since the file name is not known to the request at compile time, the request issuing the OPEN or OPENC statement cannot be compiled to access data in that file.

The OPEN or OPENC statement is supported in remote context. The use of synonyms is fully supported.

====Syntax====

The format of the OPEN or OPENC statement is:
OPEN[C] [FILE | [PERM | TEMP] GROUP]

{name [AT {location | %variable | =}] | %variable}

[PASSWORD {value | %variable}]

Where:
<ul>
<li>The C option specifies that the previous default file or group is preserved when the current file or group is opened. Default files and groups are discussed later in this page. </li>
</li>
<li>The FILE keyword specifies that the file to be opened is a <var class="product">Model 204</var> file. </li>
</li>
<li>The PERM keyword specifies that the group to be opened is a <var class="product">Model 204</var> permanent group. </li>
</li>
<li>The TEMP keyword specifies that the group to be opened is a <var class="product">Model 204</var> temporary group. </li>
</li>
<li>The GROUP keyword specifies that the file to be opened is a <var class="product">Model 204</var> group. </li>
</li>
<li>filename is the name of the <var class="product">Model 204</var> file or group to be opened. The filename can be provided in a %variable.</li>
</li>
<li>The AT keyword specifies that the file to be opened is a remote file. Only individual files (or group members) can be specified using the AT keyword. An entire group cannot be treated as a remote object. Thus none of the keywords PERM, TEMP, or GROUP can be used with AT.</li>

A remote file can also be opened using a file synonym (without the AT clause) or by opening a scattered group of which the file is a member.
</li>

<li>location is the name of the remote node where the file is located. The location can be provided in a %variable.</li>

The equal sign (=) directs <var class="product">Model 204</var> to open a local file. Since it is possible for two files at different nodes to have identical file names, the equals sign gives you the ability to explicitly call for the local file instead of the remote file with the same name.
</li>

<li>The PASSWORD clause specifies a valid password for the file or group to be opened. </li>
</li>
</ul>

====Usage notes====

If the GROUP keyword is specified without a PERM or TEMP keyword, <var class="product">Model 204</var> searches for the name first among temporary groups, then among permanent groups. If no keyword is specified, <var class="product">Model 204</var> searches for the name among temporary groups first, then permanent groups, and finally <var class="product">Model 204</var> files.

Beginning with <var class="product">Model 204</var> V3R2.1, the following message is produced for a <var class="product">SOUL</var> OPEN statement in the form OPEN %variable, if the OPEN fails:
***M204.1521:%variable DOES NOT EXIST OR REQUESTED ACCESS NOT AUTHORIZED


Beginning in V4R1.1, message 1521 is also produced for a failed OPEN statement in the form OPEN name. Now both forms of the OPEN statement produce the same message.

Message 1521 is a counting error and when encountered during APSY processing invokes the APSY error procedure. Message 1743 that was previously invoked when an OPEN %variable or OPEN name statement failed is not a counting error and does not invoke the APSY error procedure.

===Error handling===

Error conditions encountered during the processing of the OPEN or OPENC statement generate <var class="product">Model 204</var> error messages that are not displayed on the terminal. The request should check for errors after the execution of each OPEN or OPENC statement by using the $Status function. The text of the most recently issued error message can then be retrieved by the $ERRMSG function. 

The values that can be returned by the $Status function for the OPEN or OPENC statement are listed in the following table: 
<table>
<tr class="head">
<th>Value</th>
<th>Meaning</th>
</tr>
<tr>
<td align="right">0</td>
<td>The operation was successful. A return code of 0 also clears the message buffer; therefore, the $ERRMSG function, if called returns a null string.</td>
</tr>
<tr>
<td align="right">2</td>
<td>A serious error occurred. The error can be retrieved by using the $ERRMSG function to receive the last counting or cancellation message produced by <var class="product">Model 204</var>. </td>
</tr>
</table>

If OPEN GROUP is issued as a <var class="product">SOUL</var> statement (from within a request), the result of the open operation is indicated with one of three $Status values:
<table>
<tr class="head">
<th>[[$Status]]</th>
<th>Description</th>
</tr>
<tr>
<td align="right">0</td>
<td>All members of the group were successfully opened.</td>
</tr>
<tr>
<td align="right">1 </td>
<td>One or more optional members could not be opened.</td>
</tr>
<tr>
<td align="right">2</td>
<td>A mandatory member could not be opened, MAXFAIL members could not be opened, or all members are missing. </td>
</tr>
</table>

====Example====
BEGIN
.
.
.
OPEN PERM GROUP REGISTERED.AUTOS

IF $Status NE 0 THEN
PRINT 'OPEN ERROR ON AUTO FILE'
PRINT $ERRMSG
STOP
ELSE
.
.
.


For more information about $Status, see the Rocket <var class="product">Model 204</var> Horizon: Intersystem Processing Guide. 

If the DDNAME of the file to be opened is greater than eight characters, the command is rejected and the following message is issued:

M204.1903: %C EXCEEDS 8 CHARACTERS IN LENGTH

===Error conditions relating to remote files===

Using the AT keyword with the PERM, TEMP, or GROUP keywords (or with the OPEN DATASET, OPEN EXTERNAL, or OPEN [EXTERNAL] TERMINAL statements) causes the following error message:
M204.1497: REMOTE SPECIFICATION CONFLICTS WITH OPEN TYPE


If, when attempting to open a remote file, <var class="product">Model 204</var> cannot establish a conversation with the remote node, the following error message displays:
M204.1984: COMMUNICATION ERROR ON REMOTE NODE
PROCESSING FILE filename AT location


If a %variable is used to indicate the location of a remote file, and its value is found to be null, the value of the $STATUS function is set to 2 and the following error message is generated:
M204.2003: LOCATION MISSING FOR REMOTE FILE


===Error conditions relating to scattered groups===
<ul>
<li>If a mandatory member of a scattered group cannot be opened, the OPEN operation fails for the entire group. </li>
</li>
<li>If an optional member of the group cannot be opened, an error message is issued stating that the file is unavailable. The OPEN operation continues as if the file were not included in the group definition. Storage is still allocated in various internal data structures, however.</li>
</li>
<li>If the CREATE GROUP command MAXFAIL parameter value is exceeded, the group open fails and any successfully opened files are closed. An error message is issued stating that more than MAXFAIL optional files cannot be opened. </li>
</li>
</ul>

If all a scattered group's files are optional and unavailable, a group open fails, even if MAXFAIL is not exceeded. An error message is issued stating that the open failed because all group members are missing. 

===Closing a remote file===

You can close a remote file by issuing the CLOSE command using the AT location clause or a file synonym, using CLOSE ALL, or, if the remote file is the default file, using CLOSE by itself. If the file is a member of a permanent scattered group, you can close the files in the group with CLOSE GROUP. 

When a CLOSE command for a remote file is successful, the file is closed on the server node on which the file resides. <var class="product">Model 204</var> displays a message confirming the close to the user on the client node. The message identifies the file name and location. 

If the file being closed is your last open file on the server node, the conversation with the server is terminated.

A loss of communications with a remote node during or just prior to your attempt to close a remote file results in the following:
<ul>
<li>The file is closed on your local node, and you receive a communications error message. The service thread is restarted, which closes the file on the server. </li>
</li>
<li>If the file is a member of a scattered group and you issue CLOSE GROUP, the file is closed on your local node, and <var class="product">Model 204</var> attempts to close as usual the rest of the files in the group. </li>
</li>
<li>If the file was disabled for you prior to the CLOSE, the file is closed only on your local node.</li>
</li>
</ul>

===Using DEFAULT and DELETE GROUP===

The <var class="product">Model 204</var> DEFAULT command, which establishes the current default file or group, applies to remote file synonyms, remote file specifications, and scattered groups. 

The <var class="product">Model 204</var> DELETE GROUP command, which deletes an existing permanent or temporary group, applies to scattered groups. 

==Reference context==

The reference context of a statement or command is the file or group in which the statement or command is to operate. If the reference context is a file, the context also involves the way in which the file was opened. The file or group on which a command or a <var class="product">SOUL</var> statement operates is known as the current file or group.

When many files and groups are open, you must establish a single file or group context for commands and <var class="product">SOUL</var> statements. You can specify a file or group or can allow the system to operate on the default file or group.

This section discusses how you specify the file or group reference context, how the reference context affects the privileges that accompany an OPEN of a file or group and the results of a CLOSE command, and procedure file and update file references. 

For additional information about features relating to setting the reference context, refer to:
<ul>
<li>[[#IN clause|IN clause]]</li>
<li>[[#IN GROUP MEMBER clause|IN GROUP MEMBER clause]]</li>
<li>[[#$CURFILE and $UPDATE functions|$CURFILE and $UPDATE functions]]</li>
</ul>

===Establishing the default file or group===

Unless the user refers to a specific file or group in a command or a <var class="product">SOUL</var> statement, <var class="product">Model 204</var> operates on the default. Only one default can be in effect at any one time. The default can be either a file or a group.

You can establish the default in one of the following ways: 
<ul>
<li>The <var class="product">Model 204</var> file or group opened in the most recent OPEN command becomes the default. If OPENC is issued instead of OPEN, a new default is not established and the previous default is preserved. </li>
</li>
<li>The <var class="product">Model 204</var> file or group opened in the most recent OPEN statement becomes the default. However, the default file context is updated only after the request containing the OPEN statement has been evaluated. Therefore, the new default is in place only for subsequent requests.</li>
</li>
<li>Using the DEFAULT command, you can specify either a file or a group. </li>
</li>
<li>An IN clause within the BEGIN or MORE command that initiates a request sets a default that remains in effect for only that request. </li>
</li>
</ul>

===Explicitly specifying the reference context===

You can specify the file or group context of a <var class="product">SOUL</var> statement in these ways:
<ul>
<li>Explicitly referring to a FIND or SORT statement or to a list</li>
</li>
<li>Using the IN clause </li>
</li>
<li>Placing a statement within a record loop </li>
</li>
</ul>

Statements that do not fall into one of these categories operate on the default file or group established for the request. This can be established either by default or by an IN clause on the BEGIN or MORE command. 

===File and group OPENs and CLOSEs===

A file can be an individual file, a member of a permanent group, a member of a temporary group, or any combination of these. When a file is referenced in a command or in a <var class="product">SOUL</var> statement, <var class="product">Model 204</var> determines whether the file also is a member of an open group. The privileges available for a file can change along with its group membership.

If an OPEN command has been issued for a file or for a temporary group that contains the file, the privileges for that file are the same as those previously established for that file, regardless of whether the file also is a member of a permanent group. However, if a permanent group is opened, but no individual OPEN has been specified for a particular file in that group, the privileges available for that file, when an IN file reference is specified, are the same as those associated with the permanent group. The discussion on privileges and reference context on the next page lists all of the possible file/group combinations. 

When a file or group is closed with the CLOSE command, <var class="product">Model 204</var> determines which OPENs have been issued for the file or group, as follows:
<table>
<tr class="head">
<th>A CLOSE for... </th>
<th>Closes...</th>
</tr>
<tr>
<td>Individual file </td>
<td>Individual file. If the file also was opened as a permanent group member, it is still available for reference as a group member or in an IN file clause.</td>
</tr>
<tr>
<td>Permanent group </td>
<td>All files in that group, except those that have been opened as individual files or that also are members of other groups. </td>
</tr>
<tr>
<td>Temporary group </td>
<td>None of the files in the group. </td>
</tr>
</table>

===Privileges according to reference context===

The privileges associated with individual files and groups can be granted and combined in different ways, depending upon the reference context:
<table>
<tr class="head">
<th>When you reference... </th>
<th>Your set of privileges are...</th>
</tr>
<tr>
<td>Individual file </td>
<td>Those granted by <var class="product">Model 204</var> when the file was opened. These are privileges associated with the specified file password or, if the password was not required or was specified incorrectly, the default file privileges. With application subsystems, user privileges are those associated with the user class or are the default file privileges.</td>
</tr>
<tr>
<td>Temporary or ad hoc group </td>
<td>Derived from the logical intersection of the individual privileges associated with the files that make up the group. <var class="product">Model 204</var> combines the privileges of all of the member files. You are granted only the privileges common to all the files in the group.</td>
</tr>
<tr>
<td>Permanent group </td>
<td>Those granted by <var class="product">Model 204</var> when the group was opened. These are the privileges associated with the specified group password or, if the password was not required or was specified incorrectly, the default group privileges.</td>
</tr>
<tr>
<td>File that is concurrently a member of two permanent groups and has not been opened as an individual file </td>
<td>Derived from the logical union of the privileges associated with the groups. <var class="product">Model 204</var> appends the privileges of each of the open groups of which the file is a member. A privilege granted to any of the groups is granted to the file.</td>
</tr>
<tr>
<td>File that has been opened both as an individual file and as a member of a permanent group </td>
<td>Those associated with the file, not the group. An open group has no effect on the file privileges. </td>
</tr>
</table>

When a file that is a member of a permanent group is not opened individually, its privileges are the same as those granted for the group. It still can be referenced individually in a command or in a <var class="product">SOUL</var> statement. A file that is a member of a permanent group can also be opened individually.

===Procedure file and update file references===

When operating on a group, certain commands and <var class="product">SOUL</var> statements refer to the procedure file or the update file associated with the group. 

The group procedure file is the file in which procedures for the group are stored and from which procedures are retrieved or deleted. If an explicit procedure file is not defined with the PROCFILE parameter in the CREATE GROUP command, the procedure file can be specified in an IN clause. The IN clause also can be used to override the group procedure file specification.

The group update file is the file in which records for the group are stored with the <var class="product">SOUL</var> STORE RECORD statement. If an explicit update file is not defined in the UPDTFILE parameter in the CREATE GROUP command, an update file can be specified in an IN clause. The IN clause also can be used to override the group update file specification. 

====Example====

This request illustrates the various methods of context specification:
OPEN CLIENTS
OPENC CLAIMS90
BEGIN
GET.RECS: FIND ALL RECORDS FOR WHICH
SETTLEMENT DATE IS LESS THAN 900401
END FIND
PROCESS: FOR EACH RECORD IN GET.RECS
DRIVER: %DRIVER = DRIVER INVOLVED
MATCH.REC: IN CLAIMS90 FIND ALL RECORDS FOR WHICH
DRIVER ID = %DRIVER
END FIND
COMPUTE: FOR EACH RECORD IN MATCH.REC
IF STATE EQ 'FLORIDA' THEN
%TOT = %TOT + 1
END IF
END FOR
END FOR PROCESS
PRINT '1ST QUARTER, 1990: ' WITH %TOT -
' FLORIDA DRIVERS INVOLVED IN ACCIDENTS'
END


In the preceding request, the OPEN command opens the CLIENTS file or group. The OPENC command also opens a file or group, in this case CLAIMS90. However, the OPENC command does not establish a new default. 

The GET.RECS (default) and PROCESS (explicit reference) statements operate on CLIENTS. The DRIVER statement operates on CLIENTS because it is within the record loop for records from CLIENTS. The MATCH.REC (IN clause) and COMPUTE (explicit reference) statements operate on CLAIMS90.

==IN clause==

The IN clause precedes <var class="product">SOUL</var> statements to override the default file or group. A special form also creates ad hoc groups. 

A variation of the IN clause, IN GROUP MEMBER, restricts CLEAR LIST, FIND, FOR RECORD NUMBER, and STORE RECORD statements to one member file in a group context. See [[#IN GROUP MEMBER clause|IN GROUP MEMBER clause]] for more information.
Syntax

The basic form of the IN clause is: 
IN [FILE | [PERM | TEMP] GROUP] groupname

MEMBER %member [AT {location | =}]

statement-clause


If no FILE or GROUP option is specified, <var class="product">Model 204</var> searches for the name among open temporary groups first, then open permanent groups, and finally open files.

===Specifying a remote file===

A statement or command that references a file using the AT clause is called a remote file specification. The AT clause is valid only for single remote files or remote members of a scattered group explicitly referenced by an IN GROUP MEMBER clause (see [[#IN GROUP MEMBER clause|IN GROUP MEMBER clause]]). Use an unquoted equal sign to instruct <var class="product">Model 204</var> to look for the file locally.
Note: The FOR RECORD NUMBER statement does not support remote files.

The location names of remote nodes are established with the DEFINE PROCESS command.
See the <var class="book">Rocket Parallel Query Option/204 User's Guide</var> for more on creating location names.

The location name in the AT clause can be coded as a dummy string inside a <var class="product">SOUL</var> procedure. Using a dummy string allows the application programmer to code a single file reference in the procedure. Then, at run time, the user can enter a valid remote node name or an equal sign (=) to access different versions of the same file (having the same name), either remotely or locally. See [[Procedures#Procedures|Procedures]] for a detailed discussion of dummy strings.

A remote file can also be specified using a file synonym. A file synonym is a symbolic name for a remote file that references both the actual file name and the location name. Therefore, when using a file synonym, you do not use the AT clause. Even though a file synonym has been defined, you can still use the full remote file specification, as described above.

File synonyms are discussed in detail in the
<var class="book">Rocket Parallel Query Option/204 User's Guide</var>.

===Ad hoc groups===

The form of the IN clause shown below creates an ad hoc group: 
IN file1[,file2] ...


This form can be used with FIND, FIND AND PRINT COUNT, FIND AND RESERVE, CLEAR LIST, and FOR EACH VALUE statements. The group consists of the listed files, which must already be open. The ad hoc group has no name and exists only for the duration of the request and any request continuations. 

Remote files which are members of ad hoc groups can be specified OPTIONAL or MANDATORY. These keywords can be abbreviated OPT and MAN, respectively, as in this example:
IN file1 (OPT), file2 (MAN) ...


If you want to refer to an ad hoc group you created earlier in a request, you must repeat the earlier IN clause. If all of the required conditions for duplicate ad hoc groups are met, repetition of the IN clause does not create a second, identical ad hoc group. It only calls on the original ad hoc group definition stored in FTBL.
Duplicate ad hoc groups

<var class="product">Model 204</var> considers two ad hoc groups as duplicates if all the following are true:
<ul>
<li>Their IN clauses contain the same set of files.</li>
</li>
<li>Their IN clauses list the files in the same order.</li>
</li>
<li>Corresponding files in their IN clauses are both optional or both mandatory.</li>
</li>
</ul>

Duplicate groups do not require additional server table space or network traffic.

===Clearing lists===

The CLEAR LIST statement normally clears an existing list; no IN clause is required. When CLEAR LIST appears in a request before the first reference to the list, an IN clause might be necessary to create the list in the same context as the later references. References to an existing set of records in the CLEAR LIST or FIND statement override the IN clause. 

==IN GROUP MEMBER clause==

The IN GROUP MEMBER clause can be used with CLEAR LIST, FIND ALL RECORDS (and its variants), FIND ALL VALUES, FOR RECORD NUMBER (or FRN), and STORE RECORD statements; they are restricted to one member file in a group context.

====Syntax====

The format of the IN GROUP MEMBER clause is:
IN [TEMPORARY | PERMANENT] GROUP groupname

MEMBER {%member | filename [AT {location | =]

statement

Where:
<ul>
<li>groupname is the name of the file group</li>
</li>
<li>%member is a valid %variable, image, or screen item that indicates the group member for the CLEAR LIST, FIND, FOR RECORD NUMBER (FRN), or STORE RECORD statement. </li>
</li>
<li>filename specifies the name of a file where location indicates a valid remote node name or the equal sign (=) indicates that you want <var class="product">Model 204</var> to look for the named file only locally.</li>
Note: The FOR RECORD NUMBER option does not support remote files.
</li>
<li>statement is one of the following:</li>
</li>
</ul>

CLEAR LIST

FIND ALL RECORDS

FIND ALL VALUES

FOR RECORD NUMBER (FRN)

STORE RECORD

====Examples====

Suppose, for example, that the group JANSALES consists of several files corresponding to sales regions. The following statement retrieves a set of records for a single region. The file to be searched has been specified by screen input.
FDREG: IN GROUP JANSALES MEMBER %SSCREEN:REGION -
FIND ALL RECORDS FOR WHICH TOT GT 500
END FIND


The following example illustrates using a FOR RECORD NUMBER (FRN) option:
BEGIN
%GRPMEMBER='AUGUST'
FD: IN GROUP YR2001 MEMBER %GRPMEMBER FRN 164
PRINT FULLNAME WITH DOB AT 35 WITH SSN AT 50
END FOR
END


===Uses for the IN GROUP MEMBER clause===

The most common use of the IN GROUP MEMBER clause is to improve the efficiency of FIND statements when it is known in advance that some group members contain no records that meet the FIND criteria. For example, if Red Sox caps are only sold in the Northeast, the FIND statement labeled 'GETNE' below avoids a search through all the regional files.

Another possible use of the IN GROUP MEMBER clause is to build a list by processing one file at a time. Suppose, for example, that a department store chain wants to analyze sales of Boston Red Sox caps in regions other than the Northeast. The selective IN syntax could be used to create the appropriate list by subtraction, as follows:
GETCAPS: IN GROUP JANSALES FIND ALL RECORDS -
FOR WHICH ITEM = 'SOXCAP'
CAPLIST: PLACE RECORDS IN GETCAPS ON LIST FARFANS
%X = 'NOREAST'
GETNE: IN GROUP JANSALES MEMBER %X -
FIND ALL RECORDS FOR WHICH ITEM = 'SOXCAP'
FARLIST: REMOVE RECORDS IN GETNE FROM LIST FARFANS


===Use with lists===

Lists can be created from the results of group FINDs. Records from a group FIND (not using the IN GROUP MEMBER clause) cannot be placed on a list created by an individual file FIND, even if the file is a member of the group, and vice versa.

However, records found using the IN GROUP MEMBER clause can be added to or removed from the same list as records from group FINDs that do not involve using the IN GROUP MEMBER clause.

===Use with $CURFILE and $UPDATE===

You cannot use an IN clause that includes both MEMBER and $CURFILE or $UPDATE.

==$CURFILE and $UPDATE functions==

===Use with IN clause===

The IN clause also can be specified as shown here:
IN {$CURFILE | $UPDATE}


$CURFILE and $UPDATE are the only functions that can be used outside of normal function syntax. 
<ul>
<li>$UPDATE can be used to satisfy the IN clause requirements of INCLUDE and STORE RECORD. </li>
</li>
<li>$CURFILE can be used to satisfy the IN clause requirements for STORE RECORD only.</li>
</li>
</ul>

===$CURFILE function===

The $CURFILE function returns the name of the current file in a record loop. The current file is defined as the file from which the current record has been selected when the record loop refers to a group. You can use an IN $CURFILE clause only within a record loop.

An IN $CURFILE clause can add records to a file based on other data in that file, without regard for the actual file name. The file need not be a member of a group.

===$UPDATE function===

The $UPDATE function returns the name of the update file in the current group or, if a current group does not exist, the name of the current file. If no update file for the current group was specified, an IN $UPDATE clause elicits an error message. 

===Restrictions for $CURFILE and $UPDATE===

You cannot use an IN clause that includes both MEMBER and $CURFILE or $UPDATE.

====Example 1====

This sequence illustrates the use of a temporary group with an update file:
CREATE TEMP GROUP FISCAL FROM FY89, FY90, FY91
PARAMETER UPDTFILE = FY91, PROCFILE = FY89
END
OPEN GROUP FISCAL
BEGIN
GET.ACCT.NO: %A = $READ('ENTER ACCT NO OR "CR"')
IF %A EQ " THEN
JUMP TO TOT.CT
END IF
%B = $READ('ENTER AMOUNT')
IF %B EQ " THEN
JUMP TO TOT.CT
END IF
FIND.ACCT.RECS: IN $UPDATE FIND ALL RECORDS FOR WHICH
ACCT NO = %A
END FIND
CT: COUNT RECORDS IN FIND.ACCT.RECS
IF COUNT IN CT GT 1 THEN
PRINT 'ACCT MULTIPLY DEFINED' AND %A
JUMP TO END.REQUEST
END IF
COMPUTE.B: FOR EACH RECORD IN FIND.ACCT.RECS
%B = %B + AMT
CHANGE AMT TO %B
JUMP TO GET.ACCT.NO
END FOR
ADD.REC: STORE RECORD
ACCT NO = %A
AMT = %B
END STORE
GET.NEXT: JUMP TO GET.ACCT.NO
TOT.CT: FIND AND PRINT COUNT
END.REQUEST:
END


The request searches the group update file (FY91) for an account number to match the one entered by the user. 
<ul>
<li>If there is more than one record with that number, the request ends. </li>
</li>
<li>If a single record exists, the amount entered by the user is added to that record. The request then asks for a new account number. </li>
</li>
<li>If no record exists with a particular account number, the FOR loop falls through to the ADD.REC statement. The STORE RECORD statement does not contain an IN clause and thus stores the new record in the update file, FY91.</li>
</li>
</ul>

When the user indicates that updating is finished by pressing a carriage return in response to the first prompt, execution proceeds to the TOT.CT statement. The TOT.CT statement contains neither an explicit reference to another statement nor an IN clause, so the request prints a single combined count of the number of records in the three files in the group.

====Example 2====

The next example creates an ad hoc group from the open files HISTORY and FY90. The COMPUTE.TOT statement causes the amount fields from both files to be added to a grand total to be printed at the end of the request. The CHANGE.CAT statement uses the $CURFILE function to limit the budget category change to records in the history file.
BEGIN
A.CAT: IN HISTORY, FY80 FIND ALL RECORDS FOR WHICH
BUDGET CAT = A OR AA
END FIND
FOR EACH RECORD IN A.CAT
COMPUTE.TOT: %TOT = AMT + %TOT
CHANGE.CAT: IF $CURFILE EQ 'HISTORY' AND -
BUDGET CAT EQ 'AA' THEN
CHANGE BUDGET CAT TO 'A'
END IF
END FOR
PRINT 'TOTAL DOLLARS THRU 1990: ' WITH %TOT
END


==Context when using statements outside record loops==

Most <var class="product">SOUL</var> statements that appear outside record loops can operate in either a file or group context. 

A few statements (such as the two listed below) require further specification in group context. Sometimes the specification appears in the group definition; in other cases, an IN clause is used to override a group default.
<ul>
<li>INCLUDE requires a group procedure file or an IN clause.</li>
<li>STORE RECORD requires a group update file or an IN clause. </li>
</ul>

==Groups with multiple procedure files==

If you specify "PROCFILE = *" when a group is created, then that group can contain more than one procedure file. When a procedure is included, search order is determined by the order in which the files were specified in the CREATE GROUP command.

The use of multiple procedure files in application subsystem development is explained in [[Application Subsystem development]].
For more information, see <var>[[CREATE command: Temporary group|CREATE GROUP]]</var> command information.

==Cross-referencing==

Cross-referencing means using data from one place to determine retrieval or update operations in another. 

====Example====

This example illustrates cross-referencing between a group and a file. The temporary group FISCAL is the group defined earlier in this page. 
OPEN FILE HISTORY
OPEN GROUP FISCAL
BEGIN
A.CAT: FIND ALL RECORDS FOR WHICH
BUDGET CAT = A
END FIND
PLACE RECORDS IN A.CAT ON LIST REMAINDER
FOR EACH RECORD ON LIST REMAINDER
%ACCT = ACCT NO
MATCH: FIND ALL RECORDS ON LIST REMAINDER FOR WHICH
ACCT NO = %ACCT
END FIND
REMOVE RECORDS IN MATCH FROM LIST REMAINDER
HIST.MATCH: IN HISTORY FIND ALL RECORDS FOR WHICH
ACCT NO = %ACCT
END FIND
HIST.CT: COUNT RECORDS IN HIST.MATCH
IF COUNT IN HIST.CT NE 0 THEN
PRINT %ACCT WITH ' FOUND IN HISTORY'
JUMP TO NEXT.REC
END IF
PRINT %ACCT WITH ' NOT FOUND IN HISTORY'
NEXT.REC: *GO TO NEXT RECORD ON LIST
END FOR
END


The A.CAT statement finds a set of records from the default group FISCAL. Records from the group are placed on a list. As records are processed, other records in the set that have identical account numbers are removed so that each account number is printed only once. Until the HIST.MATCH statement, all statements refer to FISCAL. The HIST.MATCH statement uses the account number from the current record in FISCAL to search the single file HISTORY. The HIST.MATCH through HIST.CT statements refer to the HISTORY file. A message is displayed to indicate whether or not the history file contains records with the current account number. 

==Group operations in SOUL==

The following discussion summarizes the ways in which file groups affect the following <var class="product">SOUL</var> operations:
<ul>
<li>FIND statement</li>
<li>Sorted files</li>
<li>SORT statement</li>
<li>Lists</li>
<li>Record numbers</li>
<li>FOR EACH VALUE statements</li>
<li>Field type variations within a group</li>
<li>FOR EACH RECORD statements</li>
</ul>

===FIND statement===

When a FIND, FIND AND PRINT COUNT, or FIND AND RESERVE statement is used in a group context, <var class="product">Model 204</var> performs a series of individual file FINDs; however, the group FIND results in one set of records instead of several sets. Records in the set are arranged by file in the order in which the members were listed when the group was created. Any record loop statement referring to this set automatically switches files at the appropriate time. Once a record is selected by the loop, operations are performed only on that record and the file that contains it. 

===Sorted files===

Files with sort key organization can be used as members of groups. However, there is no group sort sequence. Therefore, the SFL$ and SFGE$ conditions cannot be used in a group FIND. The IN ORDER clause is not allowed in a FOR EACH RECORD statement that refers to a group. 

===SORT statement===

The SORT statement can refer to a group FIND or a group list. The entire set of records is sorted across file boundaries to produce a single, temporary set of records. These records then can be processed with a FOR EACH RECORD loop. The $CURFILE function can be used to print the original file names of the individual sorted records. 

===Lists===

Lists can be created from the results of group FINDs. Records from a group FIND cannot be placed on a list created by an individual file FIND, even if the file is a member of the group, and vice versa. Records from different groups cannot be placed on a single list. 

An individual record within a FOR EACH RECORD loop on a group can be added to or removed from a list.

===Record numbers===

The $CURREC function and the POINT$ condition of the FIND statement are not recommended for use in a group context. Both $CURREC and POINT$ refer to the internal record numbers of a file; these numbers are assigned to records on a file basis as records are added. At a group level, the record numbers have no meaning because the record numbers are not unique within a group. POINT$ cannot be used as a condition in a group FIND. The $CURREC function can be used, but you must ensure that the number is used only in reference to the file from which the record came. 

The value form of the FOR RECORD NUMBER statement can be used in group context. When a value is specified and group context is desired, the statement must be preceded by an IN clause in order to indicate the name of the file in which the record number occurs. 

===FOR EACH VALUE statement===

When the FOR EACH VALUE statement refers to a group, the values are supplied in order. If, in at least one of the group members, the value field is ORDERED NUMERIC, the values are supplied in numerical order. Otherwise, they are supplied in order according to the standard EBCDIC collating sequence. 

===Field type variations within a group===

It is possible that a given field name might not have the same properties in every file in a group. A field name, for example, can have the NUMERIC RANGE attribute in some files, but not in others. Furthermore, a field that appears in one or more files of a group might not exist in any of the others. 

====KEY and NON-KEY fields====

Within a group, a field can be defined as KEY in some files and NON-KEY in others. When this occurs in a group FIND condition, the FIND statement performs a key search based on the index in those files in which the field is defined as KEY, and it does a direct search of the data records in the files in which it is defined as NON-KEY. 

====NUMERIC RANGE and NON-RANGE fields====

The FIND statement operates in a similar manner when a numeric retrieval is specified for a group in which some files have the field defined as NUMERIC RANGE, and others have it defined as NON-RANGE. Records in files that have the field defined as NUMERIC RANGE are retrieved through the index, and records in the other files are retrieved by a direct search. 

====Absent fields====

When some files in a group do not contain a specified field, records in those files are handled as if they contained the absent fields. If none of the files contain a specified field, any statement referring to that field is rejected.

====PRINT and SORT statements====

Another field type conflict affects PRINT and SORT statements. When specified fields have the INVISIBLE attribute in some files and not in others, records that contain INVISIBLE fields are handled as if the field does not exist. If the field is INVISIBLE in all the files, the PRINT or SORT statement is rejected. 

====Processing====

Suppose you attempt to change a field described as LENGTH 3 to the value COLORADO. In group context, this change is rejected during compilation only if it is invalid in all of the files in the group. Otherwise, the reference is accepted during compilation. It is rejected during evaluation only if an attempt is made to change a field that is too short to contain the new value.

In general, references in group context are rejected during compilation only if they are invalid for every file in the group. Otherwise, all validity checks are made at the file level during evaluation. 

===FOR EACH RECORD statement===

The FOR EACH RECORD IN ORDER BY form of the FOR EACH RECORD statement is not allowed in group context.

==Referencing remote files in requests==

Request compilation is initiated when <var class="product">Model 204</var> encounters a BEGIN command. A request that refers to a remote file is compiled on both client and server nodes. <var class="product">Model 204</var> initiates compilation on the remote server system when a reference to a remote file is first encountered.

During compilation, as remote references are encountered, the client system sends data manipulation language (DML) calls to the participating server node, or nodes, to be compiled. 

====Example====

The following example below shows an excerpt from a procedure that references a <var class="product">Model 204</var> file (named VEHICLES) residing at a remote location (whose symbolic name is defined as BOSTON).

Prior to accessing a remote file, the following conditions must be met:
<ul>
<li>The Parallel Query Option/204 network is defined on both the client and server systems.</li>
</li>
<li>The OPEN LINK command is successfully issued by the <var class="product">Model 204</var> system manager (or User 0) on both the client and server systems, so that the connection for the Parallel Query Option/204 conversation is enabled.</li>
</li>
</ul>
DEFINE FILE CARS WITH SCOPE=SYSTEM -
FILENAME=VEHICLES -
LOCATION=BOSTON
OPEN CARS
.
BEGIN
.
FD: IN CARS FD
MAKE=FORD
END FIND
.
.
.
FR: FR IN FD
PAI
END FOR
.
.
.
END


Input/output operations that involve network transmissions are entailed in using the OPEN, FIND, and FOR statements to reference a remotely located file. 

In the previous example:
<ul>
<li>OPEN </li>
</li>
</ul>

The user request to open a remote file (CARS) initiates activity at the remote location (BOSTON) where the file resides. 

The server sends a copy of the <var class="product">Model 204</var> file information (Table A) to the user's (client) node so that compilation can proceed.
<ul>
<li>FIND (FD)</li>
</li>
</ul>

The client sends FIND criteria (FORD vehicle records) to the remote location for evaluation. 
<ul>
<li>FOR EACH RECORD (FR) </li>
</li>
</ul>

The client processes records using a FOR EACH RECORD loop. 

The server sends records from the found set to the user's node, one page of records at a time. Only records in the found set are transmitted.

[[#Referencing remote files in requests|Referencing remote files in requests]] shows remote file references using a file synonym. As an alternative, if no DEFINE FILE command is issued on the client system, you can reference the remote file using a remote file specification (AT clause). 

For example, instead of OPEN CARS, you use:
OPEN VEHICLES AT BOSTON


Instead of IN CARS FD, you use:
FD: IN VEHICLES AT BOSTON FD


See the <var class="book">Rocket Parallel Query Option/204 User's Guide</var> for additional information.

===Request continuation is not supported===

Remote file reference is not supported in a request continuation.

The MORE command and END MORE statement are not supported if the continued request refers to a remote file. 

===Errors during compilation and evaluation===

Compilation and evaluation errors in Parallel Query Option/204 applications are discussed in separate sections below. Both sections discuss how <var class="product">Model 204</var> handles noncommunications errors and communications errors when a remote file is referenced. 

====Compile time error handling====

If a noncommunications error occurs during compilation when a client application references a file on a server node: 
<ul>
<li><var class="product">Model 204</var> prints on the client node the current line in the client procedure and the error message that was generated on the server node.</li>
</li>
<li>Compilation continues on the client node only, regardless of the number of errors encountered on server nodes. </li>
</li>
</ul>

If a communications problem occurs during compilation, in any remote file or group context:
<ul>
<li>The compilation is terminated. </li>
</li>
<li>All files at the referenced node are disabled for the client user.</li>
</li>
</ul>

====Evaluation time error handling====

<var class="product">Model 204</var> begins to execute a <var class="product">SOUL</var> request even though that request contains a reference to a remote file or group that was already made unavailable to the request prior to evaluation. The action <var class="product">Model 204</var> takes depends on the context of the file or group referenced in the request: 
<table>
<tr class="head">
<th>Context</th>
<th>Action</th>
</tr>

<tr>
<td>Remote single file</td>
<td>ON MISSING FILE unit invoked </td>
</tr>

<tr>
<td>Scattered group</td>
<td>ON MISSING FILE unit invoked</td>
</tr>

<tr>
<td>File member of scattered group</td>
<td>ON MISSING MEMBER unit not invoked </td>
</tr>
</table>


If a noncommunications error occurs on an already opened remote file, the error message generated at the remote node is printed on the client node, and the request is canceled. 

If you lose communications during evaluation with an already opened remote file, all files at that node are disabled for you, and <var class="product">Model 204</var> makes one of three responses: 
<ul>
<li>Takes no further action, if all of the following are true:</li>
</li>
</ul>

File is in group context 

File is an optional group member

MAXFAIL parameter setting in CREATE GROUP is not exceeded

Node to which the file belongs has no uncommitted updates
<ul>
<li>Invokes one of two ON units: </li>
</li>
</ul>

ON MISSING MEMBER

ON MISSING FILE 
<ul>
<li>Invokes the ON ERROR unit (if present) and cancels the request. </li>
</li>
</ul>

===Using ON MISSING MEMBER and ON MISSING FILE===

The specific behavior of the ON MISSING MEMBER and the ON MISSING FILE units is described below. For a code example with these ON units, see [[#Using file and group availability $functions|Using file and group availability $functions]]. 

====Using the ON MISSING MEMBER unit====

ON MISSING MEMBER handles errors involving the availability of scattered group members. It obeys the same scoping rules as all other ON units. Its format follows: 
 ON MISSING MEMBER
.
.
.
END ON


ON MISSING MEMBER is invoked whenever the following are all true: 
<ul>
<li>An operation in group context fails against a remote optional member of the group. </li>
</li>
<li>The member was not previously unavailable to the request. </li>
</li>
<li>The MISSING FILE condition is not raised. </li>
</li>
</ul>

When ON MISSING MEMBER is invoked, these consequences follow for all the user's member files at that server node: 
<ul>
<li>The group member is made unavailable to the group (both during and after request execution). </li>
</li>
<li>The group member is considered disabled. </li>
</li>
<li>Subsequent references to the group in the same request for files at that server do not invoke ON MISSING MEMBER. </li>
</li>
</ul>

If an operation in group context fails against a remote optional member of a group and no ON MISSING MEMBER unit is active, the member is made unavailable to the group and the operation completes as if the member were not part of the group definition.

When control is passed to an ON MISSING MEMBER unit, you can return control to the request with a RETRY, BYPASS, or JUMP TO statement. 

ON MISSING MEMBER units cannot be nested. 

====Communications failures during ON MISSING MEMBER====

If a communications failure occurs while communicating with a different node within an ON MISSING MEMBER unit, the ON ERROR unit is invoked or the request is cancelled. 

If a communications failure occurs while receiving records from a remote node in a FOR EACH RECORD loop in scattered group context, you can use either the CONTINUE statement or the BYPASS statement to instruct <var class="product">Model 204</var> how to proceed:
<ul>
<li>The CONTINUE statement causes the FOR loop to continue processing records from the next available group member. All unavailable files are skipped, but the remaining available files are processed. Note that you cannot use the CONTINUE statement with an ON MISSING MEMBER unit unless the return value of the $MISSTMT function is FOR.</li>
</li>
<li>The BYPASS statement tells <var class="product">Model 204</var> to exit the FOR loop, ignoring any unprocessed group members, and continuing request execution with the statement immediately following the END FOR which closes the current FOR loop. </li>
</li>
</ul>

====Using the ON MISSING FILE unit====

ON MISSING FILE handles errors involving the availability of remote files in single file context, and involving mandatory and MAXFAIL conditions of remote files in group context. It obeys the same scoping rules as all other ON units. Its format follows: 
 ON MISSING FILE
.
.
.
END ON


ON MISSING FILE is invoked for any of the following circumstances:
<ul>
<li>An operation in single file context fails against a remote file.</li>
</li>
<li>An operation in group context fails against a remote mandatory member.</li>
</li>
<li>An operation in group context fails against a remote optional group member and the number of missing members is greater than the MAXFAIL parameter (CREATE GROUP).</li>
</li>
</ul>

When ON MISSING FILE is invoked, these consequences follow: 
<ul>
<li>The file or group is made unavailable to the request. </li>
</li>
<li>The file or group is disabled for the user. </li>
</li>
<li>All future references to the file or group in the same request cause the request to be canceled.</li>
</li>
</ul>

If an operation that normally calls for an ON MISSING FILE unit fails, and no MISSING FILE unit is active, the ON ERROR unit is invoked. If no ON ERROR unit is active, the request is canceled. 

When control is passed to an ON MISSING FILE unit, you can return control to the request with a BYPASS or JUMP statement. RETRY is not allowed. 

ON MISSING FILE units cannot be nested. 

====Communications failures during ON MISSING FILE====

If a communications error failure occurs while communicating with a different node within an ON MISSING FILE unit, the ON ERROR unit is invoked or the request is canceled. 

====Clearing ON MISSING MEMBER and ON MISSING FILE====

Like other ON units, you can clear ON MISSING MEMBER and ON MISSING FILE with the CLEAR ON command, according to the following syntax:
CLEAR ON [MISSING FILE | MISSING MEMBER}


==Using retrieval statements with remote files==

This section describes the individual <var class="product">SOUL</var> retrieval statements (and any usage restrictions) that you can use with a remote file or group.

===Using the FIND ALL RECORDS statement===

All forms of the FIND ALL RECORDS statement are supported in remote file and scattered group context. 

A FIND statement in remote context produces a record set on each of the server nodes to which the statement refers.

All record locks are maintained on the server nodes. If a record locking conflict occurs, partial found sets are dequeued (on several nodes if necessary), and the normal FIND CONFLICT action is taken. 

See the discussion of LOCATION$ on [[#Using retrieval conditions|Using retrieval conditions]] for information about restricting group context FIND results.

===Using the FOR EACH RECORD statement===

All forms of the FOR EACH RECORD statement are supported in remote file and scattered group context except for the IN ORDER clause, which is not supported in scattered group context. 

Except for the following cases, when a FOR statement is executed, it retrieves from each record only the fields that are referred to in the loop. Data is handled differently by the server in the following cases: 
<ul>
<li>If the FOR loop references a field name variable, such as %%fieldname, or if it contains a PAI statement, the entire record is transmitted from the server node.</li>
</li>
<li>If a subscripted field reference is used in a FOR loop, all occurrences of the field are transmitted from the server node.</li>
</li>
</ul>

A CODED field is decoded before being transmitted from the server node.

====OPTIMIZING FNV option====

Use the OPTIMIZING FNV option with the FOR EACH RECORD statement to optimize retrievals with field name variables. You can abbreviate this option to OPT FNV. OPTIMIZING FNV prevents FOR loop retrievals with field name variables from triggering the retrieval of all fields and all occurrences.

Specify OPT FNV in one of two places:
<ul>
<li>Before the WHERE or WITH option and after all other options</li>
</li>
<li>At the end of the FOR statement when the WHERE or WITH option is not present</li>
</li>
</ul>

When you use OPTIMIZING FNV, only the initial value of the field name variables (%%variables) at the start of the FOR loop are used to select the fields that are retrieved and shipped to the client node. Therefore, the field name variable <var class="term">must</var> have the proper value at the time the FOR loop is first executed. Each time the FOR loop is entered (after the loop has completed), the field name variable values are reset.

If the field name variable is changed in the FOR loop to the name of another field that was not explicitly referenced, the other field is <var class="term">not</var> retrieved and a default value of null is used for the field name variable reference. See [[Record loops#Field name variable optimization|Field name variable optimization]]. 

===Using the FOR RECORD NUMBER statement===

All forms of the FOR RECORD NUMBER statement are supported in remote file and scattered group context, although FOR RECORD NUMBER and FOR RECORD NUMBER IN label might have different results if you are working with records that are not locked. 

FOR RECORD NUMBER IN label refers to a preceding FOR EACH RECORD statement. In Parallel Query Option/204, the records retrieved for the FOR EACH RECORD loop are copied and sent to the client when the FOR EACH RECORD statement is evaluated. If the records are not locked after the retrieval, by the time the FOR RECORD NUMBER IN label statement is executed, the record copy to which you are referring might no longer match the record at the server.

However, if you use FOR RECORD NUMBER without IN label, <var class="product">Model 204</var> locks the record to which you are referring and sends a copy to the client during FOR RECORD NUMBER execution. Only the fields referred to by FOR RECORD NUMBER are sent.

You can also use the OPTIMIZING FNV option with the FOR EACH RECORD NUMBER statement. If you do so, the information provided in [[#Using the FOR EACH RECORD statement|Using the FOR EACH RECORD statement]] is valid, with this exception: you must specify the OPT FNV option at the end of the statement.

===Using the FOR EACH VALUE statement===

All forms of the FOR EACH VALUE statement are supported in remote file and scattered group context. 

===Using the RELEASE statement===

The RELEASE ALL RECORDS and RELEASE RECORDS IN or ON statements are performed on the server system, causing any remotely held found sets to be released. 

===Using the SORT RECORDS statement===

The SORT RECORDS statement is supported in remote file and scattered group context. However, the SORT RECORDS k option is ignored. If you use SORT k RECORDS, all the records referred to, not just the first k records, are sorted. 

Sort operations for remote file data are executed on each affected server node and the results are merged. Sort keys can include fields that are not defined in all members of a scattered group. 

===Using LIST functions===

List processing functions are supported in remote context. List operations for remote file data are performed on the server node on which the file resides. For scattered groups, a list is created on each node that contains a member of the group. 

The following example is commented to show the resulting conversation elements: 
IN PARTS AT DETROIT BEGIN
CLEAR LIST XYZ (Send CLEAR LIST function to DETROIT)
A: FD PTYPE='XYZ' (Send FIND function to DETROIT)
B: FR A (Retrieve records)
PLACE RECORD ON LIST XYZ (Send PLACE RECORD function to DETROIT)
.
.
.


Note that PLACE RECORDS IN A ON LIST XYZ would have the same effect but requires only one network operation.

===Using the PRINT statement===

The PRINT *ID statement cannot be used in remote file context. All other forms of the PRINT statement can be used to print field values for remote files, with the exception of Large Object Data stored in Table E. You can print the Large Object Data locator stored in Table B. 

====Printing preallocated fields with a PAI statement====

PAI or PAI INTO normally displays preallocated fields first in its output. In Parallel Query Option/204, however, some update operations store new preallocated field values at the end of the record, which is displayed by PAI. 

PQO/204 ships a copy of all of the fields that are referenced in the FOR loop to the client node. If you change or add a preallocated field value, this value will be placed at the end of the buffer on the client that contains the copies of the fields from the server Online where the file actually resides and the original updates have been made.

PAI of this record, for performance reasons, will not ship the fields again, and simply takes the field data from the local buffer, and shows that the preallocated field value is at the end of the record.

In fact, the record on the remote file has been updated properly with the preallocated fields at the beginning of the record.

Fields in a remote file update are transferred to the local node in the non-preallocated format. Some updates to preallocated fields that take place within a FOR loop (for instance, ADD) store new values at the end of the record. 

If preallocated fields are not updated within a FOR loop, the output of the PAI statement is the same as in the non-distributed case.

===Using retrieval conditions===

Except as described below for FILE$ and LOCATION$, retrieval conditions act the same in remote context as they do locally. In scattered groups, retrieval conditions can include fields that are not defined in all members of the group. 

The following retrieval conditions are supported in remote context: 
FILE$
FIND$
LIST$
LOCATION$
POINT$
SFGE$
SFL$


====Using FILE$====

The FILE$ condition is valid only in group context. It can accept remote file specifications and remote synonyms. For example, the following FIND results are restricted to values in the STUDENTS file whose location is NYC:
IN GROUP STUDENTS FD FILE$ 'STUDENTS' AT NYC AND SEX = 'F'


Valid FILE$ argument formats for remote files are: 
<ul>
<li>Literal remote file specifications or file synonyms</li>
</li>
<li>Literal remote file specifications or file synonyms following dummy strings </li>
</li>
<li>The equality symbol (=) to point to the node on which the request is running</li>
</li>
</ul>

Invalid FILE$ argument formats for remote files are:
<ul>
<li>%Variables</li>
</li>
<li>Remote file specifications enclosed entirely in quotes ('STUDENTS AT NYC' is not valid) </li>
</li>
</ul>

====Using LOCATION$====

You can use the LOCATION$ condition to restrict group context FIND results to a particular node. Used like FILE$, LOCATION$ is valid only in group context. The following FIND results are restricted to files in the STUDENTS group whose location is either MA or VT:
IN GROUP STUDENTS FD (LOCATION$ MA OR LOCATION$ VT) AND COLOR = 'BLUE'


The location referred to by LOCATION$ is the location name used in file synonyms and remote file specifications —
the symbolic name specified in the DESTINATION parameter of a client DEFINE PROCESS command
(described in the
<var class="book">Rocket Parallel Query Option/204 User's Guide</var>). 

Valid LOCATION$ argument formats are: 
<ul>
<li>Literal location names</li>
</li>
<li>Literal location names following dummy strings </li>
</li>
<li>The equality symbol (=) to point to the node on which the request is running</li>
</li>
</ul>

LOCATION$ arguments cannot be %variables. 

If an optional member of a scattered group is unavailable, no records are found for that file and processing continues. 

==Using update statements with remote files==

With Parallel Query Option/204, you can execute single-node updates only; each <var class="product">Model 204</var> transaction can update data on only one node.

If the current transaction has updated a node (either local or remote) that is different from the node referred to by another update statement within the transaction, <var class="product">Model 204</var> displays an error message stating that you violated the single-node update rule. The current transaction is backed out and the request is canceled. This restriction is checked at evaluation time. 

An application program must end the current transaction (either commit it or back it out) before the application can update files on a different node (either remote or local). 

This section discusses the <var class="product">SOUL</var> update statements that you can use with a remote file or group and includes a discussion of updating records that are not locked. 

===Updating unlocked record sets===

In a typical Parallel Query Option/204 remote update, a client issues a FIND statement to retrieve a set of records from a service node file. A client FOR EACH RECORD statement triggers the transfer of a copy of the record set to the client node. The client application loops through and updates the records on the service node and the client node copy. 

If the service node records are not locked (for example, you use FIND WITHOUT LOCKS) during the update processing, other users might make changes on the service node to the records in the copied set. Changes that happen after the set is copied and before the update is finished can introduce inconsistencies between the client copy and the actual server data. Such changes make obsolete the client copy of the record set. 

For example, some field-level operations depend on the current state of a record: if there are three occurrences of a field, CHANGE fieldname(6) adds a fourth occurrence. If there are six or more occurrences, the same statement changes the sixth occurrence. 

A client issues this CHANGE anticipating six or more occurrences. Before the CHANGE is processed, users on the server delete all but three occurrences. The CHANGE is processed and the service node file ends up with three occurrences unchanged and four occurrences altogether; the client copy has no deletions and a changed sixth occurrence. 

If the client user prints the record information after the CHANGE but within the same FOR EACH RECORD loop, the display shows the client's view of the record. The client does not detect that this view does not match the current server data. 

If the print of the record information is after the CHANGE but within a new FOR EACH RECORD loop, the display is a refreshed view of the actual current server record. The client can detect at this point that the expected result of the CHANGE did not occur.

Though updates like CHANGE lock a record, they alone do not prevent inconsistencies between the client's view of the record and the actual state of the record on the server. For unlocked record processing, you need to use FOR RECORD NUMBER. 
Note: Always lock a record before updating it. If an unlocked record set or list is being processed, use the FOR RECORD NUMBER statement to lock the record, as shown below: 
%X = $CURREC
FOR RECORD NUMBER %X


FOR RECORD NUMBER locks, copies, and sends the record to the client when the FOR RECORD NUMBER statement is executed. Using FOR RECORD NUMBER IN label is not sufficient, as explained in [[#Using the FOR RECORD NUMBER statement|Using the FOR RECORD NUMBER statement]]. 

===Using ON FIELD CONSTRAINT CONFLICT $functions===

If a field constraint violation occurs on a remote node and there is an active ON FIELD CONSTRAINT CONFLICT (ON FCC) unit, clients can issue the $functions that report about the constraint. For more information on the following FCC $functions, refer to [[SOUL_$functions#Summary_of_standard_functions|SOUL functions]]:
<ul>
<li>$UNQREC</li>
</li>
<li>$UPDFILE</li>
</li>
<li>$UPDFLD</li>
</li>
<li>$UUPDOVAL</li>
</li>
<li>$UPDREC</li>
</li>
<li>$UPDSTAT</li>
</li>
<li>$UPDSTMT</li>
</li>
<li>$UPDVAL</li>
</li>
</ul>

===Using ADD, CHANGE, INSERT, and DELETE===

The following update statements are supported in remote file and in scattered group context with the limitation explained below:
ADD
CHANGE
DELETE
DELETE EACH
DELETE RECORD
INSERT


===Using the BACKOUT statement===

The BACKOUT statement backs out a transaction against data on a remote node if the current transaction is remote. In addition to backing out the transaction on the remote node, BACKOUT processing includes backing out the effects of the transaction on the local copy of the remote data. 

A remote transaction is backed out automatically in the same situations in which <var class="product">Model 204</var> backs out a local transaction.

===Using COMMIT and COMMIT RELEASE statements===

The COMMIT statement commits a transaction on a remote node if the current transaction is remote. 

A remote transaction is committed automatically in the same situations in which <var class="product">Model 204</var> automatically commits a local transaction.

The COMMIT RELEASE statement commits a transaction on a remote node and releases found sets on all nodes, local and remote. 

===Using the DELETE RECORDS statement===

The DELETE RECORDS statement is supported in remote file context and in scattered group context. The functionality of this statement depends on the setting of the PQOOPT parameter, which allows DELETE RECORDS to perform multiple-node updates.

If PQOOPT is not set for multi-node updates, DELETE RECORDS can be used in scattered group context only if either of the following conditions is true:
<ul>
<li>All files in the group reside on the same remote node.</li>
</li>
<li>The group found set to which either statement applies is restricted to a single node — the found set was created by:</li>
IN GROUP groupname MEMBER %var FIND ...


where: 

%var specifies a particular file (%var is not an asterisk (*)). 
</li>
</ul>

===Using FILE RECORDS===

The FILE RECORDS statement is supported in remote file context and in scattered group context. The functionality of this statement depends on the setting of the PQOOPT parameter, which allows FILE RECORDS to perform multiple-node updates.

If PQOOPT is not set for multi-node updates, FILE RECORDS can be used in scattered group context only if all group members reside on the same node.

If PQOOPT is set for multiple-node updates and an optional member of a scattered group is unavailable, it is skipped. The records are not filed on that node and the old index entries for the targeted field name = value pair are not deleted, but the statement executes (completes) successfully.

===Using STORE RECORD===

All forms of the STORE RECORD statement are supported in remote file and scattered group context. 

Field-value pairs specified by statements that are between STORE RECORD and END STORE are sent to and stored on the remote node. 

After a record is stored on a remote node, you can access it by requests using either FIND or FOR RECORD NUMBER statements. 

Using $CURREC, you can extract the record number of the record you most recently stored. 

The file in a scattered group in which STORE RECORD stores records cannot be resolved until evaluation time, so the statement might have to be compiled on multiple nodes. For storage files pointed to by the following IN clauses, STORE RECORD is compiled on all nodes in the group; at evaluation time, it is executed on one node only. 
<ul>
<li>IN GROUP groupname MEMBER, in temporary or permanent scattered group context</li>
</li>
<li>IN $CURFILE, in temporary or permanent scattered group context</li>
</li>
<li>IN GROUP groupname (where the group update file is the implied storage file), in temporary scattered group context </li>
</li>
</ul>

===Using UPDATE RECORD===

The UPDATE RECORD statement improves performance when you are executing a set of field-level update operations against the current record. UPDATE RECORD is allowed in remote and non-remote contexts.

====Syntax====

The UPDATE RECORD syntax is: 
UPDATE RECORD
field-level-operation-1
field-level-operation-2
.
.
.
field-level-operation-N
END UPDATE


where a field-level operation is one of the following:
ADD fieldname = value

CHANGE fieldname [(subscript)] [= value]
TO newvalue

DELETE fieldname [(subscript)] [= value]

INSERT fieldname [(subscript)] = value


All field-level operations between UPDATE RECORD and END UPDATE are packaged and sent to the remote node in one call. Without UPDATE RECORD, the same set of operations require one call per operation.

If there are no field-level operations between UPDATE RECORD and END UPDATE, <var class="product">Model 204</var> ignores the UPDATE RECORD statement. 
Note: DELETE EACH fieldname is not allowed in an UPDATE RECORD statement. 

====Usage====

<var class="product">Model 204</var> handles errors that occur during UPDATE RECORD the same as those that occur during STORE RECORD. For more information about STORE RECORD error handling, see [[Data maintenance#Storing values in preallocated fields|Storing values in preallocated fields]]. 

If a field constraint violation occurs, the entire UPDATE RECORD statement is backed out. The $UPDSTMT function returns the type of statement that caused the conflict: ADD, CHANGE, or INSERT.

If an ON unit is invoked during the execution of UPDATE RECORD and the ON unit is exited with a BYPASS statement, the request execution continues with the statement that follows the END UPDATE statement. 

==Using $functions with remote files==

Except for the following functions, all file-related $functions that applied to local files or groups now apply to remote files and scattered groups as well. 
$LSTPROC
$RDPROC
$View (works only for certain remote file parameters)


$View is valid in remote file context with the following file parameters:
ASTRPPG FITRANS
ATRPG HASHKEY
CURLOC LOCATION
CURFILE OPENCTL
FICREATE RECSCTY
FILEORG SORTKEY


If $View is issued in remote file context with any other file parameter, <var class="product">Model 204</var> processes the request but the result of $View is unreliable. 

If $LSTPROC or $RDPROC is coded in a <var class="product">SOUL</var> statement that is in remote context, <var class="product">Model 204</var> displays an error message at evaluation time. 

This section describes $functions that are new or whose use in Parallel Query Option/204 requires comment. 

===Using $CURFILE, $RLCFILE, $UPDATE, and $UPDFILE===

The output of the $CURFILE, $RLCFILE, $UPDATE, and $UPDFILE functions issued in remote context is the remote file specification (filename AT location). Each of these functions returns the string:
filename AT location

Where:

location is a name for the node where the remote file resides.

You can use $SUBSTR to extract the name or the location. 

===Using $FDEF and $LSTFLD functions===

You can use these $functions in local or remote file context. They recognize the following keywords in the file-name argument string: FILE, AT. You also can use a file synonym. 

===Using $ITSOPEN function===

The $ITSOPEN function indicates whether the current file or group is open. Its format is:
$ITSOPEN(name)


where name is a %variable or literal character string representing a file name, file synonym, or group name. This argument string can include the keywords AT, FILE, GROUP, PERM, or TEMP.

$ITSOPEN can be issued in any context. It returns 1 if the file or group is open; it returns 0 if the file or group is closed. 

===Using $ITSREMOTE function===

The $ITSREMOTE function indicates whether the current file or group is remote or scattered. Its format is:
$ITSREMOTE(name)


where name is a %variable or literal character string representing a file name, file synonym, or group name. This argument string can include the keywords AT, FILE, GROUP, PERM, or TEMP.

$ITSREMOTE can be issued in any context. It returns 1 if the context is remote file or scattered group; it returns 0 if the context is local. 

===Using file and group availability $functions===


The $functions in [[#Using file and group availability $functions|Using file and group availability $functions]] and [[#Using file and group availability $functions|Using file and group availability $functions]] provide information about file and group availability. The $functions in [[#Using file and group availability $functions|Using file and group availability $functions]] report on scattered group members. The $functions in [[#Using file and group availability $functions|Using file and group availability $functions]] are for files or groups but are valid only in an ON MISSING MEMBER or ON MISSING FILE unit.

An example in which these $functions are used is shown on [[#Using file and group availability $functions|Using file and group availability $functions]]. 

The index parameter in some of the $functions in [[#Using file and group availability $functions|Using file and group availability $functions]] and [[#Using file and group availability $functions|Using file and group availability $functions]] is assigned internally by <var class="product">Model 204</var> when those $functions are issued. Unavailable files are assigned index numbers in the order in which the files are listed in the CREATE GROUP command. 

For example, if unavailable fileA appears earlier in the CREATE GROUP list of files than unavailable fileB, fileA is assigned a lower index number than fileB. If fileA appears the earliest in the CREATE GROUP list, it always has the index value 1 when it is unavailable. And when fileA is available, another file has 1. 

====Scattered group $functions====

The $functions in [[#Using file and group availability $functions|Using file and group availability $functions]] are supported only in group context. If you do not use them in group context, <var class="product">Model 204</var> cancels the request which calls the $function. 

You can ensure the group context by specifying a group name (groupname in syntax in [[#Using file and group availability $functions|Using file and group availability $functions]]) as an argument of the $function. If you do not specify a group name, the context of the current statement is used. 

The index parameter is an integer from one to the value of $GRNMISS. If index is less than one or greater than $GRNMISS, <var class="product">Model 204</var> cancels the request. 
<table>
<caption>$functions for groups</caption>
<tr class="head">
<th>$function syntax</th>
<th>Returns...</th>
</tr>
<tr>
<td>
$GRMLOC(index [,groupname])
</td>
<td>Location of the missing (unavailable) group member identified by the index parameter. </td>
</tr>
<tr>
<td>
$GRMNAME(index [,groupname])
</td>
<td>Name of the missing (unavailable) group member represented by the index parameter. </td>
</tr>
<tr>
<td>
$GRNLEFT[(groupname)]
</td>
<td>Number of remaining available optional group members that can fail before the MAXFAIL parameter value (CREATE GROUP command) is exceeded. (MAXFAIL specifies the maximum number of optional members that might be unavailable.) </td>
</tr>
<tr>
<td>
$GRNMISS[(groupname)]
</td>
<td>Number of optional group members that are unavailable to the request. </td>
</tr>
</table>

====ON MISSING unit $functions====

The $functions in [[#Using file and group availability $functions|Using file and group availability $functions]] are valid only in an ON MISSING MEMBER or ON MISSING FILE unit. Any other use of these functions is treated as a compilation error. 

The index parameter is an integer from one to the value of $MISNUM. If index is less than one or greater than $MISNUM, <var class="product">Model 204</var> cancels the request. 
<table>
<caption>$functions for ON MISSING units</caption>
<tr class="head">
<th>$function</th>
<th>Returns...</th>
</tr>
<tr>
<td>[[$MisGrup]]</td>
<td>String containing the name of the group, if the error that invoked the ON unit occurred in group context. Otherwise, it returns the null string. </td>
</tr>
<tr>
<td>$MisLoc(index) </td>
<td>String containing the location of the unavailable file indicated by the index parameter. </td>
</tr>
<tr>
<td>$MisName(index) </td>
<td>Name of the unavailable file identified by the index parameter. </td>
</tr>
<tr>
<td>[[$MisNum]]</td>
<td>Number of files in the group that are newly unavailable (that have become unavailable since the last time the ON MISSING unit was invoked). </td>
</tr>
<tr>
<td>[[$MisStmt]]</td>
<td>String containing the type of <var class="product">SOUL</var> statement that failed, for example, 'DELETE ALL RECORDS'. </td>
</tr>
</table>
ON MISSING FILE unit example

The following ON MISSING FILE unit example uses the $functions in
[[#Using file and group availability $functions|Using file and group availability $functions]] and [[#Using file and group availability $functions|Using file and group availability $functions]]. The example works for an ON MISSING MEMBER unit as well. 
ON MISSING FILE
%C IS STRING LEN 255
%D IS STRING LEN 255
%C = $MisGrup
IF %C = '' THEN
* This is file context because $MisGrup returned nulls *
%C = 'MISSING FILE ' WITH $MISNAME(1) WITH ' AT ' WITH $MISLOC(1)
PRINT %C
ELSE
%GROUPNAME = %C
%C = 'MISSING GROUP ' WITH %C WITH ' FILES FOLLOW: '
FOR %JUNK FROM 1 TO $MISNUM BY 1
%C = %C WITH $MISNAME(%JUNK) WITH ' AT ' WITH $MISLOC(%JUNK)
END FOR
%C = %C WITH ' ON STATEMENT ' WITH $MISSTMT
PRINT %C
%D = 'COMPLETE LIST OF MISSING FILES FOR' WITH $MisGrup WITH ': '
FOR %INDEX FROM 1 TO $GRNMISS BY 1
%D = %D WITH $GRMNAME(%INDEX,%GROUPNAME) WITH ' AT '
%D = %D WITH $GRMLOC(%INDEX,%GROUPNAME)
END FOR
PRINT %D
END IF
BYPASS
END ON


</div> 

[[Category:SOUL]]

$VIEW

2014-07-31T18:53:35Z

Mlarocca: Mlarocca moved page $VIEW to $View: Lower case change

#REDIRECT [[$View]]

$View

2014-07-31T18:53:35Z

Mlarocca: Mlarocca moved page $VIEW to $View: Lower case change

The $VIEW function returns:
<ul>
<li>The value of a parameter (system, file, or user) to the request</li>
</li>
<li>File parameters</li>
While $VIEW works for all viewable parameters in local context, it does not work for some file parameters in remote context.
</li>
<li>Size and use of journal and checkpoint streams</li>
</li>
</ul>
Syntax to view a parameter value
The format of the $VIEW function to view parameter values is: 
$VIEW(parameter[,name])

where:
<ul>
<li>parameter is a character string that represents the name of a viewable <var class="product">Model 204</var> parameter or other information. For example:</li>
$VIEW('ERASE')

returns a value of @ if the ERASE parameter is set to the character @. If the parameter name is invalid or the user is not authorized to display parameter values for the file, a null string is returned.
</li>
<li>name overrides the default file or group context for the function. The format for this argument is:</li>
[[FILE | [PERM | TEMP] GROUP] name | $CURFILE

| $UPDATE] [AT location]

If this argument is omitted or null, the default context is the context of the statement containing the function. Thus, a default context is required for this function.
You can specify $CURFILE as the name argument in place of a file/group name. 
</li>
</ul>
Viewing file-specific information
In addition to viewable parameters, the following file-specific information can also be viewed with $VIEW:
<table>
<tr class="head">
<th>Name used with $VIEW</th>
<th>Description</th>
</tr>
<tr>
<td>DTSLBOPR</td>
<td>
Date and time transaction was backed out during roll forward (for TBO files)
Date and time partial transaction was applied during roll forward (for non-TBO files)
</td>
</tr>
<tr>
<td>DTSLCHKP</td>
<td>Date and time of last checkpoint rolled back to. Will be blank if the file has also been rolled forward.</td>
</tr>
<tr>
<td>DTSLRCVY</td>
<td>Date and time of last recovery</td>
</tr>
<tr>
<td>DTSLUPDT</td>
<td>Date and time of last update</td>
</tr>
<tr>
<td>DTSLDKWR</td>
<td>Date and time of last DKWR</td>
</tr>
<tr>
<td>DTSLRFWD</td>
<td>Date and time of last roll forward</td>
</tr>
<tr>
<td>FIWHEN</td>
<td>Date and time FISTAT was reset</td>
</tr>
<tr>
<td>FIWHO</td>
<td>Terminal ID that reset FISTAT</td>
</tr>
</table>
For example:
$VIEW ('FIWHEN')

returns:
FIWHEN 94.257 SEP 14 16.40.45. DATE AND TIME FISTAT WAS RESET

Syntax for viewing statistics fields
The first argument is the category, SLSTATS, SYSSTATS, or USRSTATS. The second argument is the name of the Statistic field to return. See the Rocket <var class="product">Model 204</var> System Managers Guide for the name of the statistics fields.
$VIEW(category, field-to-return)

Where the following categories and fields are valid: 
<table>
<caption>Valid categories and fields with $VIEW</caption>
<tr class="head">
<th>
Category</th>
<th>Statistics field-to-return</th>
<th>
Equivalent-to or returns-value-of</th>
</tr>
<tr>
<td>'SLSTATS'</td>
<td>'USERID'</td>
<td>[[$Userid]]</td>
</tr>
<tr>
<td>'SLSTATS'</td>
<td>'ACCOUNT'</td>
<td>[[$Account]]</td>
</tr>
<tr>
<td>'SLSTATS'</td>
<td>'SUBSYSTEM'</td>
<td>$SUBSYS with no argument</td>
</tr>
<tr>
<td>'SLSTATS'</td>
<td>'LAST'</td>
<td>LAST=field</td>
</tr>
<tr>
<td>'SLSTATS'</td>
<td>'PROC-FILE'</td>
<td>Current procedure file</td>
</tr>
<tr>
<td>'SLSTATS'</td>
<td>'PROC'</td>
<td>Current procedure </td>
</tr>
<tr>
<td>'SLSTATS'</td>
<td>'sl statistics name'</td>
<td>Statistics field</td>
</tr>
<tr>
<td>'SYSSTATS'</td>
<td>'system stat name'</td>
<td>Statistics field</td>
</tr>
<tr>
<td>'SYSSTATS'</td>
<td>'DKBM stat name'</td>
<td>Statistics field</td>
</tr>
<tr>
<td>'USRSTATS'</td>
<td>'user stat name'</td>
<td>Statistics field</td>
</tr>
<tr>
<td>'USRSTATS'</td>
<td>'conflict ctr name'</td>
<td>Statistics field</td>
</tr>
</table>
Usage
The time related Since Last statistics fields, CNCT, CPU, SCHDCPU, and STCPU, are not valid during evaluation time.
Specifying an invalid statistics field name returns a null value with the message:
M204.1463: INVALID PARAMETER: fieldname

Syntax to view the size and use of journal and checkpoint streams
The format of $VIEW for the use and size of journal and checkpoint streams is:
$VIEW('CCAJRNL'|'CCAJLOG'|'CHKPOINT'|'CHKPNTS')

Specify the following:
%STRING = $VIEW('CCAJRNL'|'CCAJLOG'|'CHKPOINT'|'CHKPNTS')

$VIEW returns a string that describes the usage of the specified stream with the following character format:
<table>
<tr>
<td>Describes </td>
<td>LENGTH </td>
<td>Displays</td>
</tr>
<tr>
<td>In use DDNAME</td>
<td align="right">8</td>
<td>Alphanumeric characters</td>
</tr>
<tr>
<td>Percentage used </td>
<td align="right">4</td>
<td>Integer with percentage sign</td>
</tr>
<tr>
<td>Maximum size </td>
<td align="right">9</td>
<td>Number of tracks</td>
</tr>
<tr>
<td>Current size </td>
<td align="right">9</td>
<td>Number of tracks</td>
</tr>
<tr>
<td>Unused spaces </td>
<td align="right">2</td>
<td>Number of tracks</td>
</tr>
<tr>
<td>VOLSER </td>
<td align="right">6</td>
<td>Alphanumeric characters</td>
</tr>
<tr>
<td>Separating back slash </td>
<td align="right">1</td>
<td>A back slash</td>
</tr>
<tr>
<td>Data set name</td>
<td>Variable</td>
<td>Data set name</td>
</tr>
<tr>
<td>Separating back slash</td>
<td align="right">1</td>
<td>A back slash</td>
</tr>
<tr>
<td>Generation number </td>
<td>Variable</td>
<td>Generation number with a leading plus sign</td>
</tr>
</table>
You must ensure that the %variable being used to hold the requested information is defined as STRING LEN 80 or greater, for example:
%STRING IS STRING LEN 80

BEGIN
%STRING = $VIEW('CCAJRNL')
PRINT %STRING
END

CCAJRNL 0% 37 0 0SU000\OHIO1.ONLINE.JOURNAL

[[Category:SOUL $functions]]

$VERIFY

2014-07-31T18:38:51Z

Mlarocca: Mlarocca moved page $VERIFY to $Verify: Lower case change

#REDIRECT [[$Verify]]

$Verify

2014-07-31T18:38:51Z

Mlarocca: Mlarocca moved page $VERIFY to $Verify: Lower case change

The $VERIFY function returns a 1 (true) if every character contained in the string is present in the second string. Otherwise, 0 (false) is returned. If the second argument is a null string, 0 is returned. If the first argument is a null string but the second argument is not, a 1 is returned. 
$VERIFY can be used whenever $ALPHA, $ALPHNUM, and $VNUM do not provide sufficient flexibility. 
Example 1
$VERIFY('1975','0123456789') equals 1
$VERIFY('-19.5','0123456789+-.') equals 1
$VERIFY('12A','0123456789') equals 0

Example 2
$VERIFY('ABC',") equals 0
$VERIFY(",") equals 0
$VERIFY(",'1234567890') equals 1

[[Category:SOUL $functions]]

$USRPRIV

2014-07-31T18:10:05Z

Mlarocca: Redirected page to $UsrPriv

#REDIRECT [[$UsrPriv]]

$UsrPrive

2014-07-31T18:08:40Z

Mlarocca: Mlarocca moved page $UsrPrive to $UsrPriv: Lower case change

#REDIRECT [[$UsrPriv]]

$UsrPriv

2014-07-31T18:08:40Z

Mlarocca: Mlarocca moved page $UsrPrive to $UsrPriv: Lower case change

The $USRPRIV function is used to test whether a user ID has been granted specific <var class="product">Model 204</var> privileges. 
Syntax
The format of the $USRPRIV function is:
$USRPRIV(privilege,logging option)

where:
<ul>
<li> privilege is the privilege that is to be validated. Privilege can be one of the following values:</li>
</li>
</ul>
ANY_ADMINISTRATOR
The ANY_ADMINISTRATOR privilege test verifies that the user is user zero or a system manager.
CHANGE_FILE_PASSWORD
CHANGE_LOGIN_PASSWORD 
OVERRIDE_RECORD_SECURITY
SUPER_USER
SYSTEM_ADMINISTRATOR
SYSTEM_MANAGER
<ul>
<li>logging option specifies whether <var class="product">Model 204</var> should indicate that an error message should be issued for security violations:</li>
</li>
</ul>
LOG indicates that any privilege violation is logged.
NOLOG indicates that the privileges should be determined but any violation found is not logged. 
Currently, the logging option affects only the Security Server (formerly RACF) or Top Secret interface. The option has no effect on <var class="product">Model 204</var>; the ACF2 Interface always logs a security violation regardless of the logging option.
LOG is the default if a logging option is not specified. 
$USRPRIV returns a numeric true/false value indicating the result of the authorization check as follows: 
<table>
<tr class="head">
<th>Value</th>
<th>User is...</th>
</tr>
<tr>
<td align="right">0</td>
<td>Not authorized for the privilege or an unknown privilege name is specified.</td>
</tr>
<tr>
<td align="right">1</td>
<td>Authorized for the specified privilege. </td>
</tr>
</table>
Example
The following statement could be used to test if the current user ID is authorized as a system manager.
IF $USRPRIV('SYSTEM_MANAGER','NOLOG') THEN
.
.
.
* PERFORM SYSTEM MANAGER AUTHORIZED CODE
END IF
* ELSE UNAUTHORIZED FOR SYSTEM MANAGER FUNCTIONS

[[Category:SOUL $functions]]

$USRPRIV

2014-07-31T18:06:21Z

Mlarocca: Mlarocca moved page $USRPRIV to $UsrPrive: Lower case change

#REDIRECT [[$UsrPrive]]