m204wiki - User contributions [en]

Janus Two-Phase Commit

2020-01-15T00:31:17Z

ELowell: /* Recovery */

Janus Two-Phase Commit support allows transactions running in multiple <var class="product">Model 204</var> Onlines to participate in a single global transaction using the [https://en.wikipedia.org/wiki/Two-phase_commit_protocol two-phase commit protocol].
In addition, it enables <var class="product">Model 204</var> to participate in a global transaction with an <var class="product">Imagine</var> database server.
An <var class="product">Imagine Two-Phase Commit Coordinator</var> is required to act as the two-phase commit coordinator.
<var>[[JANUS command|JANUS]]</var> commands are used to define and start a two-phase commit port. Since there is no way to specify a 2PC port on two-phase commit related statements and functions, there is no point in specifying more than one 2PC port – if more than one is specified the first started 2PC port is always used.

==Configuring Janus Two-Phase Commit==
These are the configuaration steps:
<ol>
<li>Using a <var>JANUS DEFINE</var> command, define a Janus 2PC that will be used to communicate with the coordinator.

The following is a typical command for a two-phase commit port:
JANUS DEFINE TWOPC * 2PC 10

</li>
<li>Specify the host address or name and port number for the coordinator. This is done with the JANUS ADDCOORDINATOR command as in:
JANUS ADDCOORDINATOR TWOPC IMAGINE IMAGINEHOST.MYDOMAIN.COM 3456

If, as in this example, the coordinator host is specified as a name, a name server must be specified using the [[JANUS NAMESERVER|JANUS NAMESERVER command]].
</li>
</ol>

==Recovery==
When running recovery (the [[RESTART command]] or the [[REGENERATE command]]) against journals that might contain global transactions, a JANUS 2PC port must be defined and a coordinator added to that port before the <var>RESTART</var> or <var>REGENERATE</var> command as in:
JANUS NAMESERVER 12.34.56.78
JANUS DEFINE TWOPC * 2PC 5 SSL 0
JANUS ADDCOORD TWOPC IMGCOORD IMGSERV.MYDOMAIN.COM 3333
JANUS ADDCA TWOPC PROCFILE TWOPC.CA
JANUS START TWOPC
RESTART ROLL BACK ERROR STOP ROLL FORWARD

If, as in this example, a certificate must be retrieved from a procedure file, it would be a really bad idea for that procedure file to be a file that needs to be recovered.

==Classes and methods==
The [[Transaction class]] contains methods:
<table>
<tr><th>[[NewGlobal (Transaction function)|NewGlobal]]</th><td>to start a global transaction</td></tr>
<tr><th>[[SetGlobal (Transaction subroutine)|SetGlobal]]</th><td>to add a branch to a global transaction</td></tr>
</table>

File integrity and recovery

2020-01-01T00:24:58Z

ELowell:

<div class="toclimit-3">

==Overview==

After files have been designed and loaded, one of the file manager's most important responsibilities is to maintain the integrity of the files. This topic describes some of the error conditions that threaten file structures and the steps that you can take to safeguard the files. 

==Error recovery features==

<var class="product">Model 204</var> provides many features to ensure the data integrity, including:
<ul>
<li>Extensive command syntax checking and compiler diagnostics.</li>

<li>Double-checking of files and tape backups to ensure that files are correctly mounted.</li>

<li>SNA Communications Server (formerly VTAM) error recovery routines for data transmission from user terminals. </li>

<li>Trailers on each page with information such as file name, page number, and table number, which <var class="product">Model 204</var> checks every time the page is read or written to protect against loss of integrity due to a disk error.</li>
</ul>

In addition, <var class="product">Model 204</var> provides error recovery facilities as described in the following sections.

===Transaction back out facility===

Data integrity and logical consistency of the files are protected by the <var class="product">Model 204</var> Transaction back out facility, which can undo the effects of incomplete transactions on file data. <var class="product">Model 204</var> automatically backs out an incomplete transaction for a transaction back out file if a user's request is canceled, if <var class="product">Model 204</var> detects a file problem such as a table full condition, or if <var class="product">Model 204</var> is restarting the user.
See [[Transaction back out]] for details. 

===RESTART recovery facility===

The system manager must include a RESTART command as part of User 0's input if an installation is to use system recovery facilities.
The <var>[[RESTART command|RESTART]]</var> command and [[System and media recovery]] pages discuss the syntax of this command and describe the Roll Back, Roll Forward, and Ignore features. 

===Media recovery===

In the event of a media failure, such as a disk head crash, <var class="product">Model 204</var> allows you to recover files using the media recovery feature. Media recovery works by restoring files from a previously made backup copy, and then using the Roll Forward feature to reapply the updates that were made to the files since the time the copy was made. 
Note:
The <var>[[REGENERATE command|REGENERATE]]</var> command invokes the Restore and Roll Forward facilities automatically. In a media recovery run, the RESTORE and RESTART commands are not specified. 

==FRCVOPT and FOPT parameters==

The <var>[[FRCVOPT parameter|FRCVOPT]]</var> (file recovery options) parameter determines whether or not an installation logs checkpoint and/or Roll Forward information. The system manager also must include the <var>[[RESTART command|RESTART]]</var> command in a <var class="product">Model 204</var> job in order for recovery to run. If an installation uses the system recovery facilities, the file manager can control how files are affected. 

The default setting of FRCVOPT is X'00'. The file participates in checkpointing, and batch <var class="product">Model 204</var> jobs that update the file can be run while the Online job is up. If your installation uses Roll Forward, the file participates. The back out mechanism of transaction back out is enabled. 

If the <var>[[FOPT parameter|FOPT]]</var> parameter is also set to X'00' (enabling lock pending updates), the file is a transaction back out file. If the FOPT setting includes the X'02' option, disabling lock pending updates, <var class="product">Model 204</var> automatically disables transaction back out by turning on the X'08' bit of FRCVOPT. 

===FRCVOPT parameter===

File recovery options are controlled by the FRCVOPT parameter. The possible FRCVOPT settings are: 
<table>
<tr class="head">
<th>Bit </th>
<th>Meaning</th>
</tr>

<tr>
<td align="right"> X'80'</td>
<td>File cannot be updated if Roll Forward logging is not active. </td>
</tr>

<tr>
<td align="right"> X'40'</td>
<td>File cannot be updated if checkpoint logging is not active. </td>
</tr>

<tr>
<td align="right"> X'20'</td>
<td>File does not participate in checkpoint logging.</td>
</tr>

<tr>
<td align="right"> X'10'</td>
<td>Discontinuities not allowed (hold enqueuing while file is closed if the file has been updated in this run).</td>
</tr>

<tr>
<td align="right"> X'08'</td>
<td>Transaction back out is disabled. If X'01' is specified, this option is automatically set. </td>
</tr>

<tr>
<td align="right"> X'04'</td>
<td>File does not participate in Roll Forward logging.</td>
</tr>

<tr>
<td align="right"> X'02'</td>
<td>File does not participate in Roll Forward logging.</td>
</tr>

<tr>
<td align="right"> X'01'</td>
<td>All updates are reapplied to the file during Roll Forward, without regard to update unit boundaries. Because transactions are explicitly handled differently between transaction back out (X'08' off) and Roll Forward all the way (X'01' on), this option forces the X'08' option; that is, transaction back out is automatically turned off. </td>
</tr>
</table>

===Eliminating checkpoints and Roll Forward logging===

You can eliminate the overhead of checkpoint and Roll Forward logging if system crashes are infrequent and if manual backup facilities provide sufficient protection. To do this, turn on the X'24' bits of FRCVOPT. This strategy also works well for scratch files.

===Logging all changes===

At the other extreme, you might want to log all changes for recovery purposes. You can enforce this by setting the X'C0' bits of FRCVOPT. OPEN turns off all updating if logging is not active. The X'80' and X'40' bits are ignored if the OPEN command or statement is issued by User 0 and the file privileges include file manager. This override capability is designed to allow you to run batch update jobs, such as the File Load utility, without the overhead of logging.

===Setting and clearing the X'10' bit===

The FRCVOPT X'10' bit (discontinuities not allowed) is somewhat independent of the recovery facilities, although preventing discontinuities is less important when checkpointing is not being used. After the file has been updated, if the X'10' bit is set, <var class="product">Model 204</var> retains a share enqueue for the file, even if all users have closed the file. A separate retrieval job runs, but an updating job waits.

To allow a specific job to run, clear the X'10' bit of FRCVOPT and then close the file. If no other users have the file open, the batch job runs. After the batch job has finished, set the X'10' bit again.

===Crash recovery features===

In case of failure, <var class="product">Model 204</var> makes every effort to clean up files and shut down softly. If <var class="product">Model 204</var> or the operating system under which it is running crashes, any <var class="product">Model 204</var> file being updated is flagged by a special setting of the <var>[[FISTAT parameter|FISTAT]]</var> parameter. The FILE PHYSICALLY INCONSISTENT message is issued whenever the file is opened thereafter until recovery procedures have been executed. In this case, or in the case of a hard crash, integrity can be recovered using the DUMP/RESTORE utility or restart/recovery facility. 

==FISTAT parameter==

FISTAT is a flag parameter that provides control of update completion and other file status information. Generally, the meaning of the FISTAT setting and the actual state of the file determine any special action to be taken. 

It is important to understand the different types of errors that can occur during processing, the effect each error has on the file and the setting of FISTAT, and the separation of updates into "update units." 

The possible settings of FISTAT are: 
<table>
<tr class="head">
<th>Bit </th>
<th>Meaning</th>
</tr>

<tr>
<td align="right">X'40'</td>
<td>File might be logically inconsistent. (Soft restart might have occurred.) Logical inconsistencies are described in more detail in [[#Logically inconsistent files|Logically inconsistent files]].</td>
</tr>

<tr>
<td align="right"> X'20'</td>
<td>File is in deferred update mode. Either a file load program or an OPEN in deferred update mode was applied to the file, and the Z command has not yet been issued.
See [[Deferred update feature]] for more information about deferred update mode. </td>
</tr>

<tr>
<td align="right"> X'10'</td>
<td>File has been recovered. This notifies you that the file is intact but that some updates might have been undone. You might need to do some additional work to get the file to its most up-to-date state. Messages that describe the last updates applied are displayed when the file is opened. </td>
</tr>

<tr>
<td align="right"> X'08'</td>
<td>File is full. One of the Tables A, B, C, or D has filled up. If Table A or C fills up, or if Table B fills up in a hashed file, a reorganization is required. Otherwise, the INCREASE command can be used to add more space.</td>
</tr>

<tr>
<td align="right"> X'02'</td>
<td>File is physically inconsistent. The file was being updated when some form of severe error or a system crash occurred. This is described in detail in [[#Hard restarts|Hard restarts]]. This setting produces the FILE PHYSICALLY INCONSISTENT message. (A hard restart might have occurred.) </td>
</tr>

<tr>
<td align="right"> X'01'</td>
<td>File is not initialized. After a file is created, it must be initialized before data can be added.
See [[Initializing files]] for more information.</td>
</tr>
</table>

==Restarts==

<var class="product">Model 204</var> provides two kinds of restarts: 
<ul>
<li>Soft</li>
<li>Hard</li>
</ul>

===Soft restarts===

Soft restarts occur when <var class="product">Model 204</var> recognizes a severe error that occurs between (as opposed to during) active update operations. 

====Causes of soft restarts====

Severe errors include nonrecoverable terminal I/O errors such as: 
<ul>
<li>Phone is hung up</li>

<li>No input is coming in on a thread (with the inactive thread timeout feature enabled) for a specified number of seconds. See [[Defining the user environment (CCAIN)#User environment control parameters|User environment control parameters]] for information on the TIMEOUT parameter.</li>

<li>Full server tables</li>
</ul>

====Full server tables in transaction back out files====

If any server tables are full and the file is a transaction back out file, <var class="product">Model 204</var> automatically backs out the incomplete transaction without a restart and informs the user through an error message that the transaction has been backed out. Otherwise, <var class="product">Model 204</var> performs a soft restart.

====Effects of soft restarts====

In a soft restart:
<ul>
<li>User receives the USER RESTARTED SOFTLY message and is automatically logged out.</li>

<li>File-physically-inconsistent flag is cleared (unless other users are updating the file) and the file-logically-inconsistent flag is set. </li>
</ul>

The file is physically consistent (that is, file structural elements are in order: entries in the index correspond to entries in the data, and so on). However, there is a possibility that the file might be logically inconsistent. The restarted user might have been in the middle of an update transaction that would cause multiple updates to the file. Some updates might have been made before the soft restart occurred, while other updates were not made. 

===Hard restarts===

Hard restarts occur for severe errors during active updating operations. 

====Causes of hard restarts====

Hard restarts can be caused by:
<ul>
<li>Disk I/O errors </li>

<li>Table A, B, C, or D full conditions if transaction back out is not in effect</li>
</ul>

For a description of how these errors are handled when transaction back out is in effect, see [[Transaction back out]].
If a severe error occurs, the user receives the USER RESTARTED message and is automatically logged out. The file-physically-inconsistent flag is set. 

====Effects of hard restarts====

One hard restart can affect other users. For example:
<ol>
<li>User 1 and user 2 are each updating the same non-transaction-back out file.</li>

<li>User 1 updates KEY fields and gets a message that Table D is full.</li>

<li>File-physically-inconsistent flag (X'02') is set and user 1 is restarted. </li>

<li>User 1 now knows that there is a problem with the file.</li>

<li>User 2, however, continues updating NON-KEY fields and is not notified that Table D is full. </li>

<li>User 2 finishes the request and closes the file without ever knowing that the file-physically-inconsistent flag was set. </li>
</ol>

===Logically inconsistent files===

A file is logically inconsistent when an incomplete update unit is left applied to the file. For example, consider an application that generates purchase orders. 

Records are generated using the User Language STORE RECORD/END STORE construct and the PO number is the internal record number ($CURREC). The internal record number (PO number) is displayed on the screen along with the input items to be added to the record (through FOR RECORD NUMBER and ADD statements) when the transaction is committed.

If you enter an EOJ command and <var class="product">Model 204</var> terminates before the transaction is committed, the file is marked logically inconsistent (FISTAT X'40' is set), because an update is active and a user is waiting for terminal input.

===Physically inconsistent files===

If the user is waiting for disk I/O during an ADD operation, and an EOJ is issued, it is possible that some, but not all tables were updated. In this case the file is marked physically inconsistent (FISTAT X'02' is set).

===Preventing inconsistent files===

In the previous examples, you could prevent the file from becoming logically or physically inconsistent by bumping all users before terminating <var class="product">Model 204</var>.

===File manager responsibilities===

It is the file manager's responsibility to determine which users have been affected by a file integrity problem and notify them of the status of the file. You can use the BROADCAST FILE command described in [[ Field display and message broadcast#BROADCAST command|BROADCAST command]] to do so. 

==System failure==

When the operating system or <var class="product">Model 204</var> crashes during an updating request, the file-physically-inconsistent flag is set. The file might or might not actually be broken, depending on whether the modified file pages were written out before the crash. There is no way to predict whether or not this happens. Even if the pages were written out, the file might be logically inconsistent, depending on the point in the processing at which the crash occurred. 

==Premature system termination==

<var class="product">Model 204</var> can be terminated prematurely (by operator cancellation or because of certain error conditions) while requests are still running. When <var class="product">Model 204</var> is prematurely terminated, modified pages are not automatically written. This means that a user might have been updating and some or all updates might not appear on the file. In addition, if any other users were updating the same file shortly before termination, their updates might not appear either, even though their requests ran to completion. 

==Request cancellation==

If a serious user error occurs during evaluation of a User Language request, the request is canceled. Examples of serious user errors are:
<ul>
<li>Incorrect use of a field name variable</li>
<li>Including field-level security violations</li>
<li>Attempt to store too many values or too long a value for a preallocated field</li>
</ul>

Request cancellation functions in the same manner as a soft user restart. The user is notified that the request has been canceled, and the file is marked with the flag. If the file is a transaction back out file, <var class="product">Model 204</var> cancels the request, backs out the incomplete transaction, and does not mark the file logically inconsistent. The user is notified that the transaction has been backed out. 

==Recovery methods==

Methods for recovering from file problems are presented in the following sections.

===Taking the necessary precautions===

Take the following precautions to allow your site to recover from a file problem:
<ul>
<li>Use the DUMP/RESTORE utility regularly to take regular backups. If a recent DUMP of the file is available, the file can be restored to its state at the time of the dump using the RESTORE command. See [[File dumping and restoring]] for more information. </li>

<li>Dump the files. If journaling is ordinarily active, and all subsequent file updates are available, then you can use media recovery to restore file integrity. See [[System and media recovery]] for information about using journals to recover files. </li>

<li>Activate checkpointing during Online processing. In the event of system crash, <var class="product">Model 204</var> crash, or hard restart, you can use the RESTART command to roll back to the last valid checkpoint. If journaling is also active during the Online processing, you can use the Roll Forward feature to restore as many file changes as possible. These system recovery procedures are described in [[System and media recovery]].</li>
</ul>
Warning:
To ensure file integrity, Rocket Software strongly recommends that you <var class="term">never</var> reset the FISTAT (file status) parameter when it is set to the file-physically-inconsistent flag until <var class="term">just before</var> you reorganize the file. However, you must reset FISTAT before you reorganize a physically inconsistent file. 

===Reloading broken files===

When the precautions recommended above have been neglected and the file is broken, recovery still might be possible. The safest method consists of resetting FISTAT temporarily and then running the following User Language request:
USE OUTFILE
BEGIN
ALL: FIND ALL RECORDS
END FIND
PRINT.LOOP: FOR EACH RECORD IN ALL
PRINT '*'
PRINT ALL INFORMATION
END FOR
END


You can then use a file load program with OUTFILE to reload the file (see the discussion of file reorganization and PAI FLOD in "Using PAI FLOD for files with varying record formats". 

==Reducing integrity problems==

In addition to procedures used by the file and system managers for backup purposes, applications can be designed to reduce file integrity problems. 

===Using COMMIT statements for manageable update units===

Use a COMMIT statement between each logical update so that the system can set the file-physically-inconsistent flag off and write out updated file pages frequently. Also, <var class="product">Model 204</var> can take checkpoints only between update units. Long update units can severely inhibit the taking of checkpoints. (Update units are discussed in detail in [[#Model 204 update units|Model 204 update units]].) 

To accomplish transaction back outs, <var class="product">Model 204</var> maintains a transaction back out and constraint log for each active update unit, built in the system file CCATEMP. Sizable update units can greatly increase the amount of CCATEMP space used by the system. Because insufficient CCATEMP space terminates the run, commit update units frequently to minimize the CCATEMP space requirement. 

===Updates to TBO and non-TBO files in the same request===

You can update a non-TBO file, commit it, and then update a TBO file-or reversed file order-in the same request.

Requests that attempt to update TBO and non-TBO files without an intervening COMMIT will compile, but will fail during evaluation with the following message:
*** 1 CANCELLING REQUEST; M204.2771: ATTEMPT TO UPDATE TBO AND NON-TBO FILES IN THE SAME TRANSACTION


===Designing Host Language Interface jobs===

For Host Language Interface jobs, set the update indicator in the IFSTRT function only when updating is really occurring, and issue the IFCHKPT call at various points during a long updating program. 

Retrieval-only Host Language Interface threads are not included in update units. Passing data from a retrieval-only thread to an update thread can result in logical inconsistencies to the updated file during Roll Forward.
To prevent these inconsistencies, start the thread as an update thread and use a retrieval-only password to open the file, thus providing share-mode enqueuing and preventing updating from this thread.
The file also is prevented from being marked physically inconsistent in the event of a hard restart or system crash. See [[HLI: Job design factors#Recovery considerations for single and multicursor IFAM2 threads|Recovery considerations for single and multicursor IFAM2 threads]] for further description.

==Update units and transactions==

In general data processing terms, a transaction is a sequence of operations that access a database. The order of these operations is defined by the application or the user. 

===Model 204 transaction types===

<var class="product">Model 204</var> recognizes the following types of transactions: 
<table>
<tr class="head">
<th>Type</th>
<th>Transactions that...</th>
</tr>

<tr>
<td>1</td>
<td>Cannot update the database</td>
</tr>

<tr>
<td>2</td>
<td>Can update the database but cannot be backed out</td>
</tr>

<tr>
<td>3 </td>
<td>Can update the database and can be backed out</td>
</tr>
</table>

===Model 204 update units===

In the <var class="product">Model 204</var> environment, the term update unit refers to any sequence of operations that is allowed to update the database. The two types of update transactions described above, types 2 and 3, are both update units in <var class="product">Model 204</var>: 
<ul>
<li>Update units that cannot be backed out (type 2) are called non-backoutable update units. </li>

<li>Update units that can be backed out (type 3), are called transactions or backoutable update units.</li>
</ul>

====Non-backoutable update units====

The following types of updates cannot be backed out and must be part of non-backoutable update units:
<ul>
<li>Updates to non-transaction-back out files</li>
<li>Updates resulting from file updating commands (such as RENAME field)</li>
<li>Host Language functions that correspond to the updates in the previous two items </li>
<li>Updates resulting from the EDIT subcommands END and GO</li>
<li>Procedure definitions </li>
</ul>

====Backoutable update units====

Backoutable update units are User Language updates to a transaction back out file and their Host Language Interface counterparts (record or record set updating calls). These are the only types of update operations that can occur inside a <var class="product">Model 204</var> transaction. A transaction can either be completed so that it persists in the file, or backed out so that the update is logically undone in the file. 

Detailed descriptions of the boundaries of User Language backoutable and non-backoutable update units are presented in the following sections, followed by a discussion of the Host Language Interface update unit boundaries.

===Boundaries of non-backoutable update units===

Updating commands must be in non-backoutable update units. Some updating commands end any previous active update unit, whether backoutable or not. 

The following updating commands always end active update units:
<table>
<tr>
<td><var>[[INITIALIZE command|INITIALIZE]]</var></td>
</tr>

<tr>
<td><var>TRANSFORM</var></td>
</tr>

<tr>
<td><var>[[REDEFINE command|REDEFINE FIELD]]</var> </td>
</tr>

<tr>
<td><var>[[RENAME FIELD command|RENAME FIELD]]</var> </td>
</tr>

<tr>
<td><var>[[DELETE command: Field|DELETE FIELD]]</var> </td>
</tr>

<tr>
<td><var>[[CREATE command: File|CREATE FILE]]</var> or <var>[[CREATE command: Permanent group|CREATE PERM GROUP]]</var> </td>
</tr>

<tr>
<td><var>[[EDIT command|EDIT]]</var> permanent-procedure </td>
</tr>

<tr>
<td><var>[[INCREASE command|INCREASE]]</var> +++ </td>
</tr>

<tr>
<td><var>[[DECREASE command|DECREASE]]</var> +++ </td>
</tr>

<tr>
<td><var>[[FLOD command|FLOD]]</var> +++ </td>
</tr>

<tr>
<td><var>[[FILELOAD command|FILELOAD]]</var> +++ </td>
</tr>

<tr>
<td><var>[[REGENERATE command|REGENERATE]]</var> +++ </td>
</tr>

<tr>
<td><var>[[REORGANIZE command|REORGANIZE]]</var> +++ </td>
</tr>

<tr>
<td><var>[[RESTORE command|RESTORE]]</var> </td>
</tr>

<tr>
<td><var>[[RESTOREG command|RESTOREG]]</var></td>
</tr>

<tr>
<td><var>[[Z command|Z]]</var> +++ </td>
</tr>
</table>

The commands followed by +++ cannot be issued inside a procedure.

====Updating commands that sometimes end active update units====

Other updating commands end the previous update unit only when that update unit is a User Language update. If a command non-backoutable update unit is in progress, the following commands are included in that non-backoutable update unit: 
<table>
<tr>
<td><var>[[SECURE command: File|SECURE]]</var></td>
</tr>

<tr>
<td><var>[[BROADCAST command: Sending a file message|BROADCAST FILE]]</var> </td>
</tr>

<tr>
<td><var>[[DEFINE command|DEFINE]]</var></td>
</tr>

<tr>
<td><var>[[PROCEDURE command|PROCEDURE or PROC]]</var> </td>
</tr>

<tr>
<td><var>[[DELETE command: Procedure|DELETE PROCEDURE]]</var> or <var>[[DELETE command: Permanent group|DELETE PERM GROUP]]</var> </td>
</tr>

<tr>
<td><var>[[RESET command|RESET]]</var> </td>
</tr>

<tr>
<td><var>[[RENAME PROCEDURE command|RENAME PROCEDURE]]</var> +++ </td>
</tr>

<tr>
<td><var>[[ASSIGN command|ASSIGN]]</var></td>
</tr>

<tr>
<td><var>[[DEASSIGN command|DEASSIGN]]</var></td>
</tr>

<tr>
<td><var>[[DESECURE command: Overview of DESECURE|DESECURE]]</var> </td>
</tr>

<tr>
<td><var>[[CREATEG command|CREATEG]]</var> +++ </td>
</tr>
</table>

====Nonupdating commands that end active update units====

Nonupdating commands that end any previous update unit are:
<table>
<tr>
<td><var>[[CLOSE command|CLOSE FILE]]</var> </td>
</tr>

<tr>
<td><var>[[ALLOCATE command|ALLOCATE]]</var></td>
</tr>

<tr>
<td><var>[[FREE command|FREE]]</var></td>
</tr>

<tr>
<td><var>[[DUMP command|DUMP]]</var></td>
</tr>

<tr>
<td><var>[[DUMPG command|DUMPG]]</var></td>
</tr>

<tr>
<td><var>[[LOGOUT or LOGOFF command|LOGOUT/LOGOFF]]</var> </td>
</tr>

<tr>
<td><var>[[DISCONNECT command|DISCONNECT]]</var></td>
</tr>

<tr>
<td><var>[[EOJ command|EOJ]]</var> +++ </td>
</tr>
</table>

When a BEGIN or MORE command follows another command that does not automatically end its own update unit (for example, DEFINE), BEGIN or MORE ends the current update unit. 

====SOUL statements that end active update units or transactions====

SOUL statements that end the current update unit or transaction are:
<table>
<tr>
<td><var>[[Record level locking and concurrency control#COMMIT statement|COMMIT]]</var></td>
</tr>

<tr>
<td><var>[[Record level locking and concurrency control#RELEASE option|COMMIT RELEASE]]</var></td>
</tr>

<tr>
<td><var>[[Data recovery#Manual backout|BACKOUT]]</var></td>
</tr>

<tr>
<td><var>[[Basic request structure#Beginning and ending a request|END]]</var>
(only when END returns the user to include level 0 or terminal command level)</td>
</tr>
</table>

For information about the commit exits feature, which enables you to set up SOUL code to run at commit time, see [[Application_Subsystem_development#Commit_exits|Application Subsystem development]].

====Other ways to end active update units====

Other situations that end the current update unit are:
<ul>
<li>Return to terminal command level</li>

<li>End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition </li>

<li>Request cancellation</li>

<li>User restart </li>
</ul>

====Starting non-backoutable update units====

Non-backoutable update units in User Language start with the first FIND statement or the first User Language statement that performs an update operation on a file that is not a transaction back out file.

In a procedure, non-backoutable update units start with the first FIND statement, the first User Language statement that performs an update operation on a non-transaction back out file, or the first updating command.
Each line of input to a procedure definition is treated as a separate update unit, but only one [[System and media recovery#Understanding update units|update ID]] is assigned to a single procedure definition.

Update units for the EDIT command start and end when the edited procedure is copied to the <var class="product">Model 204</var> file during the END, GO, or SAVE subcommand. 

===Boundaries of transactions===

A transaction (backoutable update unit) begins when the first SOUL statement performing an update operation on a transaction back out file in a User Language request or a procedure is executed. 

====SOUL statements that perform update operations====

The SOUL statements that perform update operations are: 
<table>
<tr>
<td><var>[[Data maintenance#STORE RECORD statement|STORE RECORD]]</var> </td>
</tr>

<tr>
<td><var>[[Data maintenance#DELETE RECORD statement|DELETE RECORD]]</var> </td>
</tr>

<tr>
<td><var>[[Data maintenance#DELETE ALL RECORDS statement|DELETE RECORDS]]</var> </td>
</tr>

<tr>
<td><var>[[Data maintenance#FILE RECORDS statement|FILE RECORDS]]</var></td>
</tr>

<tr>
<td><var>[[Data maintenance#ADD statement|ADD]]</var> fieldname = value </td>
</tr>

<tr>
<td><var>[[Data maintenance#DELETE statement|DELETE]]</var> fieldname = value</td>
</tr>

<tr>
<td><var>[[Processing multiply occurring fields and field_groups#DELETE statement|DELETE EACH]]</var> fieldname </td>
</tr>

<tr>
<td><var>[[Processing multiply occurring fields and field_groups#INSERT statement|INSERT]]</var> fieldname = value </td>
</tr>

<tr>
<td><var>[[Processing multiply occurring fields and field_groups#CHANGE statement|CHANGE]]</var> fieldname <var>TO</var> value</td>
</tr>
</table>

These are the only update operations that can occur inside transactions or can be backed out. A non-backoutable update unit must end before a transaction begins.

====Commands that end active transactions====

Commands that end an active transaction are: 
<table>
<tr>
<td>Any file updating command</td>
</tr>

<tr>
<td><var>[[CHECKPOINT command|CHECKPOINT]]</var></td>
</tr>

<tr>
<td><var>[[CLOSE command|CLOSE FILE]]</var> </td>
</tr>

<tr>
<td><var>[[RESET command|RESET]]</var> </td>
</tr>

<tr>
<td><var>[[ALLOCATE command|ALLOCATE]]</var> </td>
</tr>

<tr>
<td><var>[[FREE command|FREE]]</var></td>
</tr>

<tr>
<td><var>[[LOGOUT or LOGOFF command|LOGOUT/LOGOFF]]</var> </td>
</tr>

<tr>
<td><var>[[DISCONNECT command|DISCONNECT]]</var> </td>
</tr>

<tr>
<td><var>[[DUMP command|DUMP]]</var></td>
</tr>

<tr>
<td><var>[[DUMPG command|DUMPG]]</var></td>
</tr>
</table>

====Other events that can end active transactions====

Other events that end a transaction are:
<ul>
<li>Return to terminal command level</li>

<li>End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition </li>

<li>Request cancellation</li>

<li>User restart </li>
</ul>

In User Language, ending a transaction does not start a new transaction. A new transaction does not start until a User Language statement performs an update operation on a transaction back out file. 

===Host Language Interface update units===

For details about update units in the Host Language Interface environment, see [[HLI: Transactions]].

</div> 

[[Category:Model 204 files]]
[[Category:Recovery]]

File integrity and recovery

2020-01-01T00:20:59Z

ELowell: /* Host Language Interface update units */

<div class="toclimit-3">

==Overview==

After files have been designed and loaded, one of the file manager's most important responsibilities is to maintain the integrity of the files. This topic describes some of the error conditions that threaten file structures and the steps that you can take to safeguard the files. 

==Error recovery features==

<var class="product">Model 204</var> provides many features to ensure the data integrity, including:
<ul>
<li>Extensive command syntax checking and compiler diagnostics.</li>

<li>Double-checking of files and tape backups to ensure that files are correctly mounted.</li>

<li>SNA Communications Server (formerly VTAM) error recovery routines for data transmission from user terminals. </li>

<li>Trailers on each page with information such as file name, page number, and table number, which <var class="product">Model 204</var> checks every time the page is read or written to protect against loss of integrity due to a disk error.</li>
</ul>

In addition, <var class="product">Model 204</var> provides error recovery facilities as described in the following sections.

===Transaction back out facility===

Data integrity and logical consistency of the files are protected by the <var class="product">Model 204</var> Transaction back out facility, which can undo the effects of incomplete transactions on file data. <var class="product">Model 204</var> automatically backs out an incomplete transaction for a transaction back out file if a user's request is canceled, if <var class="product">Model 204</var> detects a file problem such as a table full condition, or if <var class="product">Model 204</var> is restarting the user.
See [[Transaction back out]] for details. 

===RESTART recovery facility===

The system manager must include a RESTART command as part of User 0's input if an installation is to use system recovery facilities.
The <var>[[RESTART command|RESTART]]</var> command and [[System and media recovery]] pages discuss the syntax of this command and describe the Roll Back, Roll Forward, and Ignore features. 

===Media recovery===

In the event of a media failure, such as a disk head crash, <var class="product">Model 204</var> allows you to recover files using the media recovery feature. Media recovery works by restoring files from a previously made backup copy, and then using the Roll Forward feature to reapply the updates that were made to the files since the time the copy was made. 
Note:
The <var>[[REGENERATE command|REGENERATE]]</var> command invokes the Restore and Roll Forward facilities automatically. In a media recovery run, the RESTORE and RESTART commands are not specified. 

==FRCVOPT and FOPT parameters==

The <var>[[FRCVOPT parameter|FRCVOPT]]</var> (file recovery options) parameter determines whether or not an installation logs checkpoint and/or Roll Forward information. The system manager also must include the <var>[[RESTART command|RESTART]]</var> command in a <var class="product">Model 204</var> job in order for recovery to run. If an installation uses the system recovery facilities, the file manager can control how files are affected. 

The default setting of FRCVOPT is X'00'. The file participates in checkpointing, and batch <var class="product">Model 204</var> jobs that update the file can be run while the Online job is up. If your installation uses Roll Forward, the file participates. The back out mechanism of transaction back out is enabled. 

If the <var>[[FOPT parameter|FOPT]]</var> parameter is also set to X'00' (enabling lock pending updates), the file is a transaction back out file. If the FOPT setting includes the X'02' option, disabling lock pending updates, <var class="product">Model 204</var> automatically disables transaction back out by turning on the X'08' bit of FRCVOPT. 

===FRCVOPT parameter===

File recovery options are controlled by the FRCVOPT parameter. The possible FRCVOPT settings are: 
<table>
<tr class="head">
<th>Bit </th>
<th>Meaning</th>
</tr>

<tr>
<td align="right"> X'80'</td>
<td>File cannot be updated if Roll Forward logging is not active. </td>
</tr>

<tr>
<td align="right"> X'40'</td>
<td>File cannot be updated if checkpoint logging is not active. </td>
</tr>

<tr>
<td align="right"> X'20'</td>
<td>File does not participate in checkpoint logging.</td>
</tr>

<tr>
<td align="right"> X'10'</td>
<td>Discontinuities not allowed (hold enqueuing while file is closed if the file has been updated in this run).</td>
</tr>

<tr>
<td align="right"> X'08'</td>
<td>Transaction back out is disabled. If X'01' is specified, this option is automatically set. </td>
</tr>

<tr>
<td align="right"> X'04'</td>
<td>File does not participate in Roll Forward logging.</td>
</tr>

<tr>
<td align="right"> X'02'</td>
<td>File does not participate in Roll Forward logging.</td>
</tr>

<tr>
<td align="right"> X'01'</td>
<td>All updates are reapplied to the file during Roll Forward, without regard to update unit boundaries. Because transactions are explicitly handled differently between transaction back out (X'08' off) and Roll Forward all the way (X'01' on), this option forces the X'08' option; that is, transaction back out is automatically turned off. </td>
</tr>
</table>

===Eliminating checkpoints and Roll Forward logging===

You can eliminate the overhead of checkpoint and Roll Forward logging if system crashes are infrequent and if manual backup facilities provide sufficient protection. To do this, turn on the X'24' bits of FRCVOPT. This strategy also works well for scratch files.

===Logging all changes===

At the other extreme, you might want to log all changes for recovery purposes. You can enforce this by setting the X'C0' bits of FRCVOPT. OPEN turns off all updating if logging is not active. The X'80' and X'40' bits are ignored if the OPEN command or statement is issued by User 0 and the file privileges include file manager. This override capability is designed to allow you to run batch update jobs, such as the File Load utility, without the overhead of logging.

===Setting and clearing the X'10' bit===

The FRCVOPT X'10' bit (discontinuities not allowed) is somewhat independent of the recovery facilities, although preventing discontinuities is less important when checkpointing is not being used. After the file has been updated, if the X'10' bit is set, <var class="product">Model 204</var> retains a share enqueue for the file, even if all users have closed the file. A separate retrieval job runs, but an updating job waits.

To allow a specific job to run, clear the X'10' bit of FRCVOPT and then close the file. If no other users have the file open, the batch job runs. After the batch job has finished, set the X'10' bit again.

===Crash recovery features===

In case of failure, <var class="product">Model 204</var> makes every effort to clean up files and shut down softly. If <var class="product">Model 204</var> or the operating system under which it is running crashes, any <var class="product">Model 204</var> file being updated is flagged by a special setting of the <var>[[FISTAT parameter|FISTAT]]</var> parameter. The FILE PHYSICALLY INCONSISTENT message is issued whenever the file is opened thereafter until recovery procedures have been executed. In this case, or in the case of a hard crash, integrity can be recovered using the DUMP/RESTORE utility or restart/recovery facility. 

==FISTAT parameter==

FISTAT is a flag parameter that provides control of update completion and other file status information. Generally, the meaning of the FISTAT setting and the actual state of the file determine any special action to be taken. 

It is important to understand the different types of errors that can occur during processing, the effect each error has on the file and the setting of FISTAT, and the separation of updates into "update units." 

The possible settings of FISTAT are: 
<table>
<tr class="head">
<th>Bit </th>
<th>Meaning</th>
</tr>

<tr>
<td align="right">X'40'</td>
<td>File might be logically inconsistent. (Soft restart might have occurred.) Logical inconsistencies are described in more detail in [[#Logically inconsistent files|Logically inconsistent files]].</td>
</tr>

<tr>
<td align="right"> X'20'</td>
<td>File is in deferred update mode. Either a file load program or an OPEN in deferred update mode was applied to the file, and the Z command has not yet been issued.
See [[Deferred update feature]] for more information about deferred update mode. </td>
</tr>

<tr>
<td align="right"> X'10'</td>
<td>File has been recovered. This notifies you that the file is intact but that some updates might have been undone. You might need to do some additional work to get the file to its most up-to-date state. Messages that describe the last updates applied are displayed when the file is opened. </td>
</tr>

<tr>
<td align="right"> X'08'</td>
<td>File is full. One of the Tables A, B, C, or D has filled up. If Table A or C fills up, or if Table B fills up in a hashed file, a reorganization is required. Otherwise, the INCREASE command can be used to add more space.</td>
</tr>

<tr>
<td align="right"> X'02'</td>
<td>File is physically inconsistent. The file was being updated when some form of severe error or a system crash occurred. This is described in detail in [[#Hard restarts|Hard restarts]]. This setting produces the FILE PHYSICALLY INCONSISTENT message. (A hard restart might have occurred.) </td>
</tr>

<tr>
<td align="right"> X'01'</td>
<td>File is not initialized. After a file is created, it must be initialized before data can be added.
See [[Initializing files]] for more information.</td>
</tr>
</table>

==Restarts==

<var class="product">Model 204</var> provides two kinds of restarts: 
<ul>
<li>Soft</li>
<li>Hard</li>
</ul>

===Soft restarts===

Soft restarts occur when <var class="product">Model 204</var> recognizes a severe error that occurs between (as opposed to during) active update operations. 

====Causes of soft restarts====

Severe errors include nonrecoverable terminal I/O errors such as: 
<ul>
<li>Phone is hung up</li>

<li>No input is coming in on a thread (with the inactive thread timeout feature enabled) for a specified number of seconds. See [[Defining the user environment (CCAIN)#User environment control parameters|User environment control parameters]] for information on the TIMEOUT parameter.</li>

<li>Full server tables</li>
</ul>

====Full server tables in transaction back out files====

If any server tables are full and the file is a transaction back out file, <var class="product">Model 204</var> automatically backs out the incomplete transaction without a restart and informs the user through an error message that the transaction has been backed out. Otherwise, <var class="product">Model 204</var> performs a soft restart.

====Effects of soft restarts====

In a soft restart:
<ul>
<li>User receives the USER RESTARTED SOFTLY message and is automatically logged out.</li>

<li>File-physically-inconsistent flag is cleared (unless other users are updating the file) and the file-logically-inconsistent flag is set. </li>
</ul>

The file is physically consistent (that is, file structural elements are in order: entries in the index correspond to entries in the data, and so on). However, there is a possibility that the file might be logically inconsistent. The restarted user might have been in the middle of an update transaction that would cause multiple updates to the file. Some updates might have been made before the soft restart occurred, while other updates were not made. 

===Hard restarts===

Hard restarts occur for severe errors during active updating operations. 

====Causes of hard restarts====

Hard restarts can be caused by:
<ul>
<li>Disk I/O errors </li>

<li>Table A, B, C, or D full conditions if transaction back out is not in effect</li>
</ul>

For a description of how these errors are handled when transaction back out is in effect, see [[Transaction back out]].
If a severe error occurs, the user receives the USER RESTARTED message and is automatically logged out. The file-physically-inconsistent flag is set. 

====Effects of hard restarts====

One hard restart can affect other users. For example:
<ol>
<li>User 1 and user 2 are each updating the same non-transaction-back out file.</li>

<li>User 1 updates KEY fields and gets a message that Table D is full.</li>

<li>File-physically-inconsistent flag (X'02') is set and user 1 is restarted. </li>

<li>User 1 now knows that there is a problem with the file.</li>

<li>User 2, however, continues updating NON-KEY fields and is not notified that Table D is full. </li>

<li>User 2 finishes the request and closes the file without ever knowing that the file-physically-inconsistent flag was set. </li>
</ol>

===Logically inconsistent files===

A file is logically inconsistent when an incomplete update unit is left applied to the file. For example, consider an application that generates purchase orders. 

Records are generated using the User Language STORE RECORD/END STORE construct and the PO number is the internal record number ($CURREC). The internal record number (PO number) is displayed on the screen along with the input items to be added to the record (through FOR RECORD NUMBER and ADD statements) when the transaction is committed.

If you enter an EOJ command and <var class="product">Model 204</var> terminates before the transaction is committed, the file is marked logically inconsistent (FISTAT X'40' is set), because an update is active and a user is waiting for terminal input.

===Physically inconsistent files===

If the user is waiting for disk I/O during an ADD operation, and an EOJ is issued, it is possible that some, but not all tables were updated. In this case the file is marked physically inconsistent (FISTAT X'02' is set).

===Preventing inconsistent files===

In the previous examples, you could prevent the file from becoming logically or physically inconsistent by bumping all users before terminating <var class="product">Model 204</var>.

===File manager responsibilities===

It is the file manager's responsibility to determine which users have been affected by a file integrity problem and notify them of the status of the file. You can use the BROADCAST FILE command described in [[ Field display and message broadcast#BROADCAST command|BROADCAST command]] to do so. 

==System failure==

When the operating system or <var class="product">Model 204</var> crashes during an updating request, the file-physically-inconsistent flag is set. The file might or might not actually be broken, depending on whether the modified file pages were written out before the crash. There is no way to predict whether or not this happens. Even if the pages were written out, the file might be logically inconsistent, depending on the point in the processing at which the crash occurred. 

==Premature system termination==

<var class="product">Model 204</var> can be terminated prematurely (by operator cancellation or because of certain error conditions) while requests are still running. When <var class="product">Model 204</var> is prematurely terminated, modified pages are not automatically written. This means that a user might have been updating and some or all updates might not appear on the file. In addition, if any other users were updating the same file shortly before termination, their updates might not appear either, even though their requests ran to completion. 

==Request cancellation==

If a serious user error occurs during evaluation of a User Language request, the request is canceled. Examples of serious user errors are:
<ul>
<li>Incorrect use of a field name variable</li>
<li>Including field-level security violations</li>
<li>Attempt to store too many values or too long a value for a preallocated field</li>
</ul>

Request cancellation functions in the same manner as a soft user restart. The user is notified that the request has been canceled, and the file is marked with the flag. If the file is a transaction back out file, <var class="product">Model 204</var> cancels the request, backs out the incomplete transaction, and does not mark the file logically inconsistent. The user is notified that the transaction has been backed out. 

==Recovery methods==

Methods for recovering from file problems are presented in the following sections.

===Taking the necessary precautions===

Take the following precautions to allow your site to recover from a file problem:
<ul>
<li>Use the DUMP/RESTORE utility regularly to take regular backups. If a recent DUMP of the file is available, the file can be restored to its state at the time of the dump using the RESTORE command. See [[File dumping and restoring]] for more information. </li>

<li>Dump the files. If journaling is ordinarily active, and all subsequent file updates are available, then you can use media recovery to restore file integrity. See [[System and media recovery]] for information about using journals to recover files. </li>

<li>Activate checkpointing during Online processing. In the event of system crash, <var class="product">Model 204</var> crash, or hard restart, you can use the RESTART command to roll back to the last valid checkpoint. If journaling is also active during the Online processing, you can use the Roll Forward feature to restore as many file changes as possible. These system recovery procedures are described in [[System and media recovery]].</li>
</ul>
Warning:
To ensure file integrity, Rocket Software strongly recommends that you <var class="term">never</var> reset the FISTAT (file status) parameter when it is set to the file-physically-inconsistent flag until <var class="term">just before</var> you reorganize the file. However, you must reset FISTAT before you reorganize a physically inconsistent file. 

===Reloading broken files===

When the precautions recommended above have been neglected and the file is broken, recovery still might be possible. The safest method consists of resetting FISTAT temporarily and then running the following User Language request:
USE OUTFILE
BEGIN
ALL: FIND ALL RECORDS
END FIND
PRINT.LOOP: FOR EACH RECORD IN ALL
PRINT '*'
PRINT ALL INFORMATION
END FOR
END


You can then use a file load program with OUTFILE to reload the file (see the discussion of file reorganization and PAI FLOD in "Using PAI FLOD for files with varying record formats". 

==Reducing integrity problems==

In addition to procedures used by the file and system managers for backup purposes, applications can be designed to reduce file integrity problems. 

===Using COMMIT statements for manageable update units===

Use a COMMIT statement between each logical update so that the system can set the file-physically-inconsistent flag off and write out updated file pages frequently. Also, <var class="product">Model 204</var> can take checkpoints only between update units. Long update units can severely inhibit the taking of checkpoints. (Update units are discussed in detail in [[#Model 204 update units|Model 204 update units]].) 

To accomplish transaction back outs, <var class="product">Model 204</var> maintains a transaction back out and constraint log for each active update unit, built in the system file CCATEMP. Sizable update units can greatly increase the amount of CCATEMP space used by the system. Because insufficient CCATEMP space terminates the run, commit update units frequently to minimize the CCATEMP space requirement. 

===Updates to TBO and non-TBO files in the same request===

You can update a non-TBO file, commit it, and then update a TBO file-or reversed file order-in the same request.

Requests that attempt to update TBO and non-TBO files without an intervening COMMIT will compile, but will fail during evaluation with the following message:
*** 1 CANCELLING REQUEST; M204.2771: ATTEMPT TO UPDATE TBO AND NON-TBO FILES IN THE SAME TRANSACTION


===Designing Host Language Interface jobs===

For Host Language Interface jobs, set the update indicator in the IFSTRT function only when updating is really occurring, and issue the IFCHKPT call at various points during a long updating program. 

Retrieval-only Host Language Interface threads are not included in update units. Passing data from a retrieval-only thread to an update thread can result in logical inconsistencies to the updated file during Roll Forward.
To prevent these inconsistencies, start the thread as an update thread and use a retrieval-only password to open the file, thus providing share-mode enqueuing and preventing updating from this thread.
The file also is prevented from being marked physically inconsistent in the event of a hard restart or system crash. See [[HLI: Job design factors#Recovery considerations for single and multicursor IFAM2 threads|Recovery considerations for single and multicursor IFAM2 threads]] for further description.

==Update units and transactions==

In general data processing terms, a transaction is a sequence of operations that access a database. The order of these operations is defined by the application or the user. 

===Model 204 transaction types===

<var class="product">Model 204</var> recognizes the following types of transactions: 
<table>
<tr class="head">
<th>Type</th>
<th>Transactions that...</th>
</tr>

<tr>
<td>1</td>
<td>Cannot update the database</td>
</tr>

<tr>
<td>2</td>
<td>Can update the database but cannot be backed out</td>
</tr>

<tr>
<td>3 </td>
<td>Can update the database and can be backed out</td>
</tr>
</table>

===Model 204 update units===

In the <var class="product">Model 204</var> environment, the term update unit refers to any sequence of operations that is allowed to update the database. The two types of update transactions described above, types 2 and 3, are both update units in <var class="product">Model 204</var>: 
<ul>
<li>Update units that cannot be backed out (type 2) are called non-backoutable update units. </li>

<li>Update units that can be backed out (type 3), are called transactions or backoutable update units.</li>
</ul>

====Non-backoutable update units====

The following types of updates cannot be backed out and must be part of non-backoutable update units:
<ul>
<li>Updates to non-transaction-back out files</li>
<li>Updates resulting from file updating commands (such as RENAME field)</li>
<li>Host Language functions that correspond to the updates in the previous two items </li>
<li>Updates resulting from the EDIT subcommands END and GO</li>
<li>Procedure definitions </li>
</ul>

====Backoutable update units====

Backoutable update units are User Language updates to a transaction back out file and their Host Language Interface counterparts (record or record set updating calls). These are the only types of update operations that can occur inside a <var class="product">Model 204</var> transaction. A transaction can either be completed so that it persists in the file, or backed out so that the update is logically undone in the file. 

Detailed descriptions of the boundaries of User Language backoutable and non-backoutable update units are presented in the following sections, followed by a discussion of the Host Language Interface update unit boundaries.

===Boundaries of non-backoutable update units===

Updating commands must be in non-backoutable update units. Some updating commands end any previous active update unit, whether backoutable or not. 

The following updating commands always end active update units:
<table>
<tr>
<td><var>[[INITIALIZE command|INITIALIZE]]</var></td>
</tr>

<tr>
<td><var>TRANSFORM</var></td>
</tr>

<tr>
<td><var>[[REDEFINE command|REDEFINE FIELD]]</var> </td>
</tr>

<tr>
<td><var>[[RENAME FIELD command|RENAME FIELD]]</var> </td>
</tr>

<tr>
<td><var>[[DELETE command: Field|DELETE FIELD]]</var> </td>
</tr>

<tr>
<td><var>[[CREATE command: File|CREATE FILE]]</var> or <var>[[CREATE command: Permanent group|CREATE PERM GROUP]]</var> </td>
</tr>

<tr>
<td><var>[[EDIT command|EDIT]]</var> permanent-procedure </td>
</tr>

<tr>
<td><var>[[INCREASE command|INCREASE]]</var> +++ </td>
</tr>

<tr>
<td><var>[[DECREASE command|DECREASE]]</var> +++ </td>
</tr>

<tr>
<td><var>[[FLOD command|FLOD]]</var> +++ </td>
</tr>

<tr>
<td><var>[[FILELOAD command|FILELOAD]]</var> +++ </td>
</tr>

<tr>
<td><var>[[REGENERATE command|REGENERATE]]</var> +++ </td>
</tr>

<tr>
<td><var>[[REORGANIZE command|REORGANIZE]]</var> +++ </td>
</tr>

<tr>
<td><var>[[RESTORE command|RESTORE]]</var> </td>
</tr>

<tr>
<td><var>[[RESTOREG command|RESTOREG]]</var></td>
</tr>

<tr>
<td><var>[[Z command|Z]]</var> +++ </td>
</tr>
</table>

The commands followed by +++ cannot be issued inside a procedure.

====Updating commands that sometimes end active update units====

Other updating commands end the previous update unit only when that update unit is a User Language update. If a command non-backoutable update unit is in progress, the following commands are included in that non-backoutable update unit: 
<table>
<tr>
<td><var>[[SECURE command: File|SECURE]]</var></td>
</tr>

<tr>
<td><var>[[BROADCAST command: Sending a file message|BROADCAST FILE]]</var> </td>
</tr>

<tr>
<td><var>[[DEFINE command|DEFINE]]</var></td>
</tr>

<tr>
<td><var>[[PROCEDURE command|PROCEDURE or PROC]]</var> </td>
</tr>

<tr>
<td><var>[[DELETE command: Procedure|DELETE PROCEDURE]]</var> or <var>[[DELETE command: Permanent group|DELETE PERM GROUP]]</var> </td>
</tr>

<tr>
<td><var>[[RESET command|RESET]]</var> </td>
</tr>

<tr>
<td><var>[[RENAME PROCEDURE command|RENAME PROCEDURE]]</var> +++ </td>
</tr>

<tr>
<td><var>[[ASSIGN command|ASSIGN]]</var></td>
</tr>

<tr>
<td><var>[[DEASSIGN command|DEASSIGN]]</var></td>
</tr>

<tr>
<td><var>[[DESECURE command: Overview of DESECURE|DESECURE]]</var> </td>
</tr>

<tr>
<td><var>[[CREATEG command|CREATEG]]</var> +++ </td>
</tr>
</table>

====Nonupdating commands that end active update units====

Nonupdating commands that end any previous update unit are:
<table>
<tr>
<td><var>[[CLOSE command|CLOSE FILE]]</var> </td>
</tr>

<tr>
<td><var>[[ALLOCATE command|ALLOCATE]]</var></td>
</tr>

<tr>
<td><var>[[FREE command|FREE]]</var></td>
</tr>

<tr>
<td><var>[[DUMP command|DUMP]]</var></td>
</tr>

<tr>
<td><var>[[DUMPG command|DUMPG]]</var></td>
</tr>

<tr>
<td><var>[[LOGOUT or LOGOFF command|LOGOUT/LOGOFF]]</var> </td>
</tr>

<tr>
<td><var>[[DISCONNECT command|DISCONNECT]]</var></td>
</tr>

<tr>
<td><var>[[EOJ command|EOJ]]</var> +++ </td>
</tr>
</table>

When a BEGIN or MORE command follows another command that does not automatically end its own update unit (for example, DEFINE), BEGIN or MORE ends the current update unit. 

====SOUL statements that end active update units or transactions====

SOUL statements that end the current update unit or transaction are:
<table>
<tr>
<td><var>[[Record level locking and concurrency control#COMMIT statement|COMMIT]]</var></td>
</tr>

<tr>
<td><var>[[Record level locking and concurrency control#RELEASE option|COMMIT RELEASE]]</var></td>
</tr>

<tr>
<td><var>[[Data recovery#Manual backout|BACKOUT]]</var></td>
</tr>

<tr>
<td><var>[[Basic request structure#Beginning and ending a request|END]]</var>
(only when END returns the user to include level 0 or terminal command level)</td>
</tr>
</table>

====Other ways to end active update units====

Other situations that end the current update unit are:
<ul>
<li>Return to terminal command level</li>

<li>End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition </li>

<li>Request cancellation</li>

<li>User restart </li>
</ul>

====Starting non-backoutable update units====

Non-backoutable update units in User Language start with the first FIND statement or the first User Language statement that performs an update operation on a file that is not a transaction back out file.

In a procedure, non-backoutable update units start with the first FIND statement, the first User Language statement that performs an update operation on a non-transaction back out file, or the first updating command.
Each line of input to a procedure definition is treated as a separate update unit, but only one [[System and media recovery#Understanding update units|update ID]] is assigned to a single procedure definition.

Update units for the EDIT command start and end when the edited procedure is copied to the <var class="product">Model 204</var> file during the END, GO, or SAVE subcommand. 

===Boundaries of transactions===

A transaction (backoutable update unit) begins when the first SOUL statement performing an update operation on a transaction back out file in a User Language request or a procedure is executed. 

====SOUL statements that perform update operations====

The SOUL statements that perform update operations are: 
<table>
<tr>
<td><var>[[Data maintenance#STORE RECORD statement|STORE RECORD]]</var> </td>
</tr>

<tr>
<td><var>[[Data maintenance#DELETE RECORD statement|DELETE RECORD]]</var> </td>
</tr>

<tr>
<td><var>[[Data maintenance#DELETE ALL RECORDS statement|DELETE RECORDS]]</var> </td>
</tr>

<tr>
<td><var>[[Data maintenance#FILE RECORDS statement|FILE RECORDS]]</var></td>
</tr>

<tr>
<td><var>[[Data maintenance#ADD statement|ADD]]</var> fieldname = value </td>
</tr>

<tr>
<td><var>[[Data maintenance#DELETE statement|DELETE]]</var> fieldname = value</td>
</tr>

<tr>
<td><var>[[Processing multiply occurring fields and field_groups#DELETE statement|DELETE EACH]]</var> fieldname </td>
</tr>

<tr>
<td><var>[[Processing multiply occurring fields and field_groups#INSERT statement|INSERT]]</var> fieldname = value </td>
</tr>

<tr>
<td><var>[[Processing multiply occurring fields and field_groups#CHANGE statement|CHANGE]]</var> fieldname <var>TO</var> value</td>
</tr>
</table>

These are the only update operations that can occur inside transactions or can be backed out. A non-backoutable update unit must end before a transaction begins.

====Commands that end active transactions====

Commands that end an active transaction are: 
<table>
<tr>
<td>Any file updating command</td>
</tr>

<tr>
<td><var>[[CHECKPOINT command|CHECKPOINT]]</var></td>
</tr>

<tr>
<td><var>[[CLOSE command|CLOSE FILE]]</var> </td>
</tr>

<tr>
<td><var>[[RESET command|RESET]]</var> </td>
</tr>

<tr>
<td><var>[[ALLOCATE command|ALLOCATE]]</var> </td>
</tr>

<tr>
<td><var>[[FREE command|FREE]]</var></td>
</tr>

<tr>
<td><var>[[LOGOUT or LOGOFF command|LOGOUT/LOGOFF]]</var> </td>
</tr>

<tr>
<td><var>[[DISCONNECT command|DISCONNECT]]</var> </td>
</tr>

<tr>
<td><var>[[DUMP command|DUMP]]</var></td>
</tr>

<tr>
<td><var>[[DUMPG command|DUMPG]]</var></td>
</tr>
</table>

====Other events that can end active transactions====

Other events that end a transaction are:
<ul>
<li>Return to terminal command level</li>

<li>End of an application subsystem procedure, when control is transferred through the communications global variable, unless the Auto Commit option was turned off in the subsystem definition </li>

<li>Request cancellation</li>

<li>User restart </li>
</ul>

In User Language, ending a transaction does not start a new transaction. A new transaction does not start until a User Language statement performs an update operation on a transaction back out file. 

===Commit exits===
For information about the commit exits feature, which enables you to set up SOUL code to run at commit time, see [[Application_Subsystem_development#Commit_exits|Application Subsystem development]].
===Host Language Interface update units===

For details about update units in the Host Language Interface environment, see [[HLI: Transactions]].

</div> 

[[Category:Model 204 files]]
[[Category:Recovery]]

Application Subsystem development

2019-12-31T22:14:22Z

ELowell: /* Commit exits */

==Overview==

Although only a system manager can define a subsystem, the determination of a subsystem's options and components typically also involves the file manager and application developer. This page focuses on subsystem facility topics most relevant to the application developer:

The Subsystem Management facility of Dictionary lets you define a collection of procedures to <var class="product">Model 204</var> as a subsystem and to assign certain characteristics to that subsystem. 

===Advantages of subsystems===

The following table summarizes the advantages of subsystems over other [[SOUL]] procedure applications: 
<table>
<tr class="head">
<th>Advantage </th>
<th>Subsystems...</th>
</tr>

<tr>
<td nowrap>Minimal end-user intervention </td>
<td>Require minimal knowledge of <var class="product">Model 204</var>. The end user need not know what files and procedures exist for the application. The subsystem is invoked simply by entering the subsystem name as a <var class="product">Model 204</var> command.</td>
</tr>

<tr>
<td>Driver facility </td>
<td>Eliminate the need for user-written drivers containing conditional INCLUDEs based on a global variable. This driver facility leads to smaller, more modular procedures that are easier to maintain and enhance.</td>
</tr>

<tr>
<td nowrap>Performance improvements </td>
<td>Improve performance by saving and reloading compiled SOUL requests, called precompiled procedures. Depending upon how often precompiled procedures are included, 20-90% of the operating costs of a <var class="product">Model 204</var> application can be saved.</td>
</tr>

<tr>
<td>Error handling facilities </td>
<td>Trap and handle <var class="product">Model 204</var> errors in a single, centralized routine. Each subsystem can have one error procedure that is invoked each time a <var class="product">Model 204</var> error occurs during that subsystem's processing. <var class="product">Model 204</var> provides facilities for determining the type of error that caused the error procedure to be invoked. </td>
</tr>

<tr>
<td>Security facilities </td>
<td>Allow or restrict access to the subsystem. </td>
</tr>

<tr>
<td>Parallel Query Option/204 compatibility </td>
<td>Can be defined to allow referral to remote files and scattered groups.</td>
</tr>
</table>

===Subsystem definition===

The characteristics and components of a subsystem are defined to <var class="product">Model 204</var> by the system manager during a process called subsystem definition. The defined options and components are stored in the system file CCASYS. Once a subsystem has been defined, all Dictionary users can display the options and components through Dictionary. For more information about:
<ul>
<li>Displaying a subsystem definition, see [[System requirements for Application Subsystems#Overview of the Subsystem Management facility|Overview of the Subsystem Management facility]]. </li>

<li>Defining subsystems that refer to remote files and scattered groups, see [[PQO: Scattered APSY subsystems#Client and service subsystems|PQO client and service subsystems]].
</li>
</ul>

==Subsystem design components==

During subsystem definition, the components listed below can be defined. These components impact various aspects of subsystem design. The following table summarizes the required component designations. 
<table>
<tr class="head">
<th>Component </th>
<th>Subsystem design requires designation of...</th>
</tr>

<tr>
<td nowrap>Command line global variable </td>
<td>(Optional) parameter global variable. The parameter global variable allows any parameters specified by a user during a subsystem login to be stored in this variable and retained when control is transferred to another subsystem. </td>
</tr>

<tr>
<td>Communication global variable and exit value </td>
<td>Communication global variable and exit value. The communication global variable is used to transfer control from one procedure to another. The exit value is used to leave the subsystem. Optionally, a reserved global variable is available for transferring control between subsystems. </td>
</tr>

<tr>
<td>Error global variable </td>
<td>Error global variable. If an error occurs while the subsystem is executing, a three-character error code is stored in this variable. This code can then be used by an error procedure to determine the action to be taken by the subsystem. </td>
</tr>

<tr>
<td>Prefix designations </td>
<td>Two prefixes for procedure names. These prefixes allow <var class="product">Model 204</var> to determine whether a procedure can be saved in its compiled form for later evaluation. </td>
</tr>

<tr>
<td>Processing components</td>
<td>Specific procedures for types of special processing. These procedures allow <var class="product">Model 204</var> to determine the flow of control within a subsystem. </td>
</tr>
</table>

==Command line global variable==

A command line global variable allows you to store any parameters specified by an end user during a subsystem login and retain this information when control is transferred to another subsystem. The designation of a command line global variable is optional. 

===Using the command line global variable===

The command line global variable is used in the following manner:
<ul>
<li>A user logs into a subsystem by entering the subsystem name followed by the parameter information. The total length of the parameter information entered by the user can consist of as many as 255 characters. (The portion of the command line reserved for parameter information is discarded if no parameter information is defined.)</li>

<li>The portion of the input following the subsystem name is placed into a command line global variable, which then is available to the application program. For example:
PAYROLL parameter1 parameter2


is the command that logs the current user into the subsystem named PAYROLL. The string parameter1 parameter2 is the subsystem command line and is made available to the application via a global variable. If CMDL is the name assigned to the command line global variable, the following statements:
BEGIN
%CMD.LINE = $GETG('CMDL')
%FIRST.PARM =
$Substr(%CMD.LINE,1,$INDEX(%CMD.LINE,' ')-1)


would assign the contents of the command line used to enter the subsystem to %CMD.LINE and the first parameter of the line to %FIRST.PARM. 
</li>
</ul>

===Transferring control to another subsystem===

The contents of command line global variables are not deleted when control is transferred from one subsystem to another. A request can set the contents of the command line global variable of the destination subsystem before transferring control to that subsystem. The effect is the same as if the parameters were entered on the user's terminal. 

===Impact of the UTABLE command===

The contents of the command line global variable are not deleted by UTABLE commands which normally delete the contents of GTBL, as long as the UTABLE command is issued from within a subsystem. 

==Communication global variable==

===Transferring control===

A communication global variable lets you transfer control at two levels: 
<table>
<tr class="head">
<th>From... </th>
<th>Control is transferred by a...</th>
</tr>

<tr>
<td>One procedure to another </td>
<td>User-designated global variable.</td>
</tr>

<tr>
<td>One subsystem to another </td>
<td>Reserved global variable named XFER. </td>
</tr>
</table>

===Transferring control between procedures===

Subsystem procedures pass control from one to another through the use of the communication global variable. The communication global variable name for a subsystem is specified in the subsystem definition. Each subsystem procedure must set the value of the communication global variable to the name of the next procedure to be executed.

====Example====

For example, the subsystem AUTOS has procedures PRE-MAIN.MENU and PRE-RPT.PGM and the communication global variable NEXT.
PRE-MAIN.MENU is currently executing and wants to pass control to
PRE-RPT.PGM. Before PRE-MAIN.MENU finishes, the function $SETG is used to store procedure name PRE-RPT.PGM in NEXT:
IF $SETG('NEXT','PRE-RPT.PGM') THEN ...


After PRE-MAIN.MENU ends, <var class="product">Model 204</var> examines NEXT and begins executing PRE-RPT.PGM.

====Subsystem exit value====

A subsystem is exited by setting the value of the communication global variable to the subsystem exit value. The exit value for the communication global variable is also specified in the subsystem definition. 

For the AUTOS subsystem used in the preceding example, the exit value of the communication global variable is defined as EXIT. To disconnect the user from the AUTOS subsystem after procedure PRE-RPT.PGM is finished executing, PRE-RPT.PGM assigns the exit value, EXIT, to the communication global variable, NEXT.
IF $SETG('NEXT','EXIT') THEN
.
.
.


===Transferring control between subsystems===

One subsystem can invoke another subsystem by transferring control from itself to another subsystem. To accomplish this, you must perform these steps:
<ol>
<li>Set the communication global variable to the value XFER.</li>
<li>Set the global variable XFER to the name of the subsystem to which control is being passed. </li>
</ol>

When the current procedure finishes executing, <var class="product">Model 204</var> disconnects the user from the old subsystem, transfers control to the new subsystem, and invokes the login procedure for the new subsystem. 

====Design considerations====

You should consider the following factors when coding logic for transferring control between two subsystems:
<ul>
<li>The transfer always invokes the login procedure of the subsystem receiving control. For more information on the login procedure, refer to the discussion [[#Subsystem processing flow|Subsystem processing flow]].</li>

<li>The destination subsystem must be active. The $SUBSYS function should be used to determine if the subsystem to which control is being transferred is active; refer to the discussion on [[#Subsystem procedure control functions|Subsystem procedure control functions]]. If the destination subsystem does not use the automatic start option, (see [[#Operating options|Operating options]]), the subsystem must be started before control is passed. </li>

<li>The destination subsystem should not reset LGTBL if any parameters are passed in global variables. </li>

<li>To return to the original subsystem, a global variable must be set to the name of the original subsystem. The communication global variable and the XFER global variable can then be used with the global variable that stores the subsystem name to return control to the original subsystem.</li>

<li>The destination subsystem can return control to the procedure that the user was in when the user transferred. To do this, the subsystem must save the name of the procedure in a global variable. In addition, the login procedure must contain logic to return control to the procedure that the user was in.</li>

<li>If the transferring subsystem is in test mode (see [[#Security options|Security options]]), the transferring subsystem stops after it passes control. The destination subsystem is not placed in test mode.
</li>
</ul>

====Example====

The following request in procedure PRE-SUB.MENU provides an example of subsystem transfer code. CREDIT and AUTOS are two defined subsystems with the automatic start option. (See [[#Automatic start|Automatic start]].) Subsystem CREDIT transfers control to AUTOS by setting NEXT (the communication global variable) to XFER and the global variable XFER to AUTOS. After the PRE-SUB.MENU procedure ends, the user is connected to AUTOS.
BEGIN
.
.
.
*SELECTION = 4 INDICATES CHOICE OF AUTOS SUBSYSTEM
*
SEL.AUTOS: IF %CREDITMENU:SELECTION = 4 AND -
$SUBSYS('AUTOS') =1 THEN
IF $SETG('XFER','AUTOS') OR -
$SETG('NEXT','XFER') OR -
$SETG('SUBFROM','CREDIT') OR -
$SETG('PROCFROM','PRE-SUB.MENU') THEN
PRINT 'GLOBAL TABLE FULL'
END IF
JUMP TO GET.NEXT
.
.
.


===Coding considerations===
<ul>
<li>Procedures to which control is passed via the communication global variable must be stored in a designated procedure file. The procedure file is the default file for a subsystem application unless the default file is explicitly changed by a DEFAULT command or overridden by an IN clause.</li>

<li>Each procedure must set the communication global variable to indicate the next procedure to be included. If this variable is not set, an error or loop occurs.</li>

<li>To exit the subsystem, the communication global variable must be set to the exit value. Server table sizes and other parameters should be reset to the values existing prior to entering the subsystem so that the user is returned to his/her normal operating environment. Parameter values are restored automatically when the automatic login option is used.
</li>
</ul>

==Error global variable==

The name of the error global variable must be specified in the subsystem definition. Whenever an error is detected that is not trapped by an ON unit, <var class="product">Model 204</var> automatically sets the subsystem's error global variable to a value which indicates the type of error that occurred. 

===Error code values===

The "Error global variable values and reasons" table lists the error global variable values and their corresponding causes. Correct the cause of the error, and/or change your error procedure as discussed in [[#Error procedures|Error procedures]]. 
<table>
<caption>Error global variable values and reasons</caption>
<tr class="head">
<th>Error code</th>
<th>Reason</th>
</tr>

<tr>
<td>ATN </td>
<td>User pressed attention</td>
</tr>

<tr>
<td>BUG </td>
<td>Evaluation errors</td>
</tr>

<tr>
<td>CAN</td>
<td>Request evaluation canceled due to invalid terminal I/O in error procedure after BUMP or inactive thread time out.</td>
</tr>

<tr>
<td>CNT </td>
<td>Counting errors</td>
</tr>

<tr>
<td>FIL - BROKEN </td>
<td>Referenced file is not initialized, full, or physically inconsistent. Check the audit trail to determine the condition of the file. </td>
</tr>

<tr>
<td>FIL - NOT OPEN </td>
<td>Referenced file not open</td>
</tr>

<tr>
<td>GRP - FTBL </td>
<td>FTBL too small</td>
</tr>

<tr>
<td>GRP - NOT OPEN </td>
<td>Group not open</td>
</tr>

<tr>
<td>GRP - TEMP FIELD </td>
<td>TEMP group field has wrong type (see [[#Restrictions for temporary and ad hoc groups in precompiled procedures|Restrictions for temporary and ad hoc groups in precompiled procedures]])</td>
</tr>

<tr>
<td nowrap>GRP - TEMP MISMATCH </td>
<td>TEMP group has wrong type</td>
</tr>

<tr>
<td>INCLUDE MAX</td>
<td>Maximum iterations value has been exceeded.</td>
</tr>

<tr>
<td>HNG </td>
<td>Phone hung up, connection lost</td>
</tr>

<tr>
<td>HRD </td>
<td>Hard restart</td>
</tr>

<tr>
<td>REC </td>
<td>Record locking table filled up during the load of a
precompiled request</td>
</tr>

<tr>
<td>RFR</td>
<td>After several tries, an APSY failed to invoke a procedure, because the procedure is in the process of being refreshed.</td>
</tr>

<tr>
<td>SFT </td>
<td>Soft restart</td>
</tr>

<tr>
<td>TBL - FSCB </td>
<td>FSCB too small</td>
</tr>

<tr>
<td>TBL - NTBL </td>
<td>NTBL too small</td>
</tr>

<tr>
<td>TBL - QTBL </td>
<td>QTBL too small</td>
</tr>

<tr>
<td>TBL - STBL </td>
<td>STBL too small</td>
</tr>

<tr>
<td>TBL - VTBL </td>
<td>VTBL too small</td>
</tr>
</table>

===Error procedures===

An error procedure must test for different error conditions. The resulting value stored in the error global variable helps the application programmer determine the type of error that occurred.
<ul>
<li>For all error codes except ATN, the error procedure should avoid re-executing the procedure that caused the error; otherwise, the error recurs. </li>

<li>In most cases, the error procedure should display an informational message and set the global communication variable to the exit value. </li>

<li>If a HNG error code is indicated, all terminal I/O (such as PRINT, READ) is ignored. </li>

<li>If a HNG, HRD, or SFT error code is indicated, no terminal I/O (such as PRINT or READ) should be attempted. Instead, send a message to the audit trail in an AUDIT statement that indicates the error code encountered.
</li>
</ul>

====Considerations for the communications global variable====

The communications global variable is ignored and disconnect processing completed when one of the following conditions occurs:
<ul>
<li>Error is a soft restart, a hard restart, or a phone hang-up condition.

If you attempt to set the communications global variable to the name of another procedure, the procedure is not executed.
</li>

<li>No error procedure is specified in the subsystem definition.
</li>
</ul>

An example illustrating how a subsystem error procedure can test for different error conditions is provided in [[#Error procedure|Error procedure]]. 

==Precompiled and non-precompiled procedures==

You can use two types of procedures in a subsystem: 
<ul>
<li>Precompiled procedure

The first time a precompilable procedure is invoked after a subsystem starts, it is compiled and stored for re-use. Because the compiler phase is bypassed each subsequent time the procedure is invoked (except as noted below), precompilation saves both CPU and elapsed time. Exceptions include the following:
<ul>
<li>The procedure is recompiled the first time it is invoked for each SCLASS. The new compilation is evaluated, then discarded. It does not replace the original stored compilation. </li>
<li>Further recompilations might be required due to temporary group differences. See [[#Recompiling precompiled procedures|Recompiling precompiled procedures]] for more on this. </li>
</ul></li>

<li>Non-precompiled procedure

A non-precompiled procedure is compiled each time it is invoked.</li>
</ul>

All procedures, whether precompiled or not, are invoked using the communication global variable.

===Defining prefixes===

During subsystem definition, two prefixes must be defined. The first prefix identifies precompiled procedures; the second identifies non-precompiled procedures. All procedures that are included for the subsystem through the use of the communication global variable (such as the login and main processing procedures) must have names that begin with one of these prefixes.

===Contents of subsystem procedures===

Subsystem procedures can contain <var class="product">Model 204</var> commands, a request, multiple requests, continued requests, sections of User Language code (for example, subroutines), or any combination thereof. However, the form of the procedure affects whether the procedure can be precompiled and should be taken into account when the subsystem is designed. Restrictions for precompiled procedures are discussed in detail below.

===Shared versions of precompiled procedures===

Server I/O can be reduced by allowing users executing shared precompiled procedures to use a shared version of QTBL.
See [[Performance monitoring and tuning#Resident Request feature for precompiled procedures|Resident Request feature for precompiled procedures]]. 

===Restrictions for precompiled procedures===

<var class="product">Model 204</var> must ensure that all of the code compiled and saved for a request with the precompiled prefix is consistent for all loading users. To achieve consistency, <var class="product">Model 204</var> restricts the way in which certain features are used. 

Note the following restrictions for precompiled procedures when designing subsystem procedures:
<ul>
<li>Procedures must contain exactly one request. The last statement must be END or END MORE.</li>

<li>Requests cannot start with MORE.</li>

<li>Procedures that include multiple BEGIN/END blocks are not eligible for precompilation.</li>

<li>Requests must not refer to files or permanent groups that are not mentioned in the subsystem definition.</li>

<li>Precompiled procedures can contain the User Language INCLUDE statement. The included procedures must be from a subsystem file. Any code inserted as a result of an INCLUDE statement is subject to all the restrictions for precompiled procedures. </li>

<li>If a precompiled procedure issues the INCLUDE command to compile and run a User Language request, the INCLUDE command is saved, not the compilation of the request that was included.</li>

<li>Compiler table sizes must be the same each time a precompiled procedure is invoked. The UTABLE command should be used carefully.</li>

<li>Dummy strings (??, ?$, ?&) in precompiled procedures are resolved only during compilation for the first user.</li>

<li>Dummy string substitution does not take place when saving commands that contain dummy strings. Instead, when the saved commands are loaded and executed, the current value of the dummy string is used. For example, if you include the following command in a precompiled procedure, whatever is currently in the global COMMAND is executed.
?%COMMAND
</li>

<li>If a subsystem file is referenced by a precompiled procedure, no user can RESTORE or INITIALIZE the file, or RENAME, DELETE, or REDEFINE a field while the subsystem is active.</li>

<li>Procedures in UNLOCKed members of a PROCFILE GROUP are not precompiled.
</li>
</ul>

===Restrictions for temporary and ad hoc groups in precompiled procedures===

Precompiled requests can refer to temporary or ad hoc groups as long as the files making up the group are specified in the subsystem definition. A temporary group of the same name must have the same composition characteristics for all loading users, as described below. If this condition is not met, <var class="product">Model 204</var> sets the error global variable to GRP-TEMP MISMATCH (see [[#Error global variable|Error global variable]]).
<ul>
<li>The temporary group for all loading users must be the same type. <var class="product">Model 204</var> assigns a type, based on the following file conditions:
<ul>
<li>Some files have record security.</li>
<li>All files are sorted or all are hashed.</li>
<li>The sort or hash key has the same name in all files. </li>
</ul></li>

<li>Fields of the same name in the temporary group must be of the same type. Each field referenced in a temporary group each time a precompiled procedure is invoked must be found in a file. If this condition is not met, <var class="product">Model 204</var> sets the error global variable to GRP-TEMP FIELD (see [[#Error global variable|Error global variable]]).

Field definition attributes can change for fields in temporary groups between compile and loading time. The following changes are allowed:
<ul>
<li>If the field is NON-CODED in any file at compile time, it can be CODED in all files at loading time.</li>
<li>If the field is BINARY or FLOAT in any file at compile time, it can be STRING in all files at loading time.</li>
<li>If the field is non-NUMERIC RANGE in any file at compile time, the field can be NUMERIC RANGE in all of the files at loading time.</li>
</ul></li>
</ul>

===Recompiling precompiled procedures===

When designing applications which use precompiled procedures and temporary groups, be aware that temporary groups can cause <var class="product">Model 204</var> to recompile precompiled procedures under certain conditions. 

Precompiled procedures are recompiled when the request references a temporary group and the:
<ul>
<li>Compiling user's temporary group consists of files which are smaller than one or more of the files in the loading user's temporary group of the same name.</li>

<li>Compiling user's temporary group has fewer files than the loading user's temporary group of the same name. </li>

<li>Update and retrieve privileges do not match those of the compiling user's temporary group (of the same name).
</li>
</ul>

If one user's temporary group contains one large file, and another user's temporary group contains a number of smaller files, it is possible that a precompiled procedure is recompiled every time it is invoked. To prevent constant recompiling when files are of different sizes, compile temporary groups originally with the largest files and the greatest number files you expect to be included in the temporary group.

If, despite precautions, <var class="product">Model 204</var> must discard and recompile a precompiled procedure, the loading user must have exclusive access to that procedure: no other user can be executing the procedure within the same subsystem. If another user is executing the procedure, the loading user recompiles a private copy of the procedure. <var class="product">Model 204</var> discards the private copy when execution has completed. 

===Procedure compilation and Parallel Query Option/204===

When a non-precompiled procedure that references remote files is invoked, one or more remote nodes participate in the compilation and evaluation. When a precompiled procedure is invoked, <var class="product">Model 204</var> loads the procedure on each of the nodes that participated in the original compilation.

When a subsystem member becomes unavailable during evaluation, the appropriate ON unit is activated. 

Errors which occur while loading a remote procedure produce error messages which have the prefix RMT in the global error variable.

====Saving compilations====

As part of the compilation process, a list of remote nodes referenced in the request is generated with the compiled code. When compilation is complete, the compilation is saved along with the list of nodes. Each remote node referenced in the request is sent a signal to save the compilation. 

If for any reason a compilation cannot be saved by a server node, the entire save operation fails.

====Loading saved compilations====

At the client node, the saved remote node reference list is checked to see which nodes are loading the request. When the request is loaded on the client, a signal is transmitted to each referenced server node to load the compilation. 

====New and missing nodes====

A temporary group can be changed so that a node is new (not previously referenced) or missing (referenced but no longer available). [[#New and missing nodes|Temporary groups with new and missing nodes]] shows how new and missing nodes affect recompilations and saves. 
<table>
<caption>Temporary groups with new and missing nodes</caption>
<tr class="head">
<th> </th>
<th>If there are
missing nodes...</th>
<th>If there are no
missing nodes....</th>
</tr>

<tr>
<td>And there are new nodes...</td>
<td>Recompile the procedure, do not save</td>
<td>Recompile and save again</td>
</tr>

<tr>
<td>And there are no new nodes...</td>
<td>Just load and evaluate</td>
<td>Just load and evaluate</td>
</tr>
</table>

====Recompiling saved requests====

Saved requests are always recompiled if a new node is introduced into a temporary group. Recompilation can cause a noticeable delay in response time.

In addition, the following changes in the composition of a subgroup also force recompilation of a request. A subgroup is the group of files at a server node referenced as a part of a group.

<var class="product">Model 204</var> recompiles saved requests when:
<ul>
<li>The number of files in the subgroup has increased (for example, if a user's request includes a file that was unavailable to the previous user)</li>

<li>The maximum number of segments in a subgroup has increased
</li>
</ul>

==Subsystem procedures==

===Types of subsystem procedures===

Subsystem development involves writing the collection of procedures that make up a subsystem. Subsystem procedures can be categorized as one of four types: 
<table>
<tr class="head">
<th>Procedure category </th>
<th>Performs...</th>
</tr>

<tr>
<td><var>Initialization</var> </td>
<td>Specified operations each time the subsystem is initialized.</td>
</tr>

<tr>
<td><var>Login</var> </td>
<td>As the entry point for each user of the subsystem.</td>
</tr>

<tr>
<td><var>Main processing</var> </td>
<td>Specific tasks of the subsystem.</td>
</tr>

<tr>
<td><var>Error</var> </td>
<td>Error handling. </td>
</tr>
</table>

===Guidelines and restrictions===
<ul>
<li>Procedures should be small and modular.</li>

<li>Included procedures normally are included by using the INCLUDE command. Included procedures cannot be precompiled.</li>

<li>Non-subsystem files can be opened and referenced only by non precompiled procedures.</li>

<li>If a subsystem file is referenced by a precompiled procedure, no user can RESTORE or INITIALIZE the file, or RENAME, DELETE, or REDEFINE a field while the subsystem is active.</li>

<li>A subsystem procedure cannot issue the CREATE command for a subsystem file.</li>

<li>LXTBL and LFTBL cannot be reset from within a subsystem procedure.</li>

<li>All DO YOU REALLY WANT TO messages are suppressed and the default action is assumed. The default action for each type of message is listed in [[M204.1076]].

If you do not wish the default action to be executed, statements to handle a situation that would invoke the message should be added to the procedure. 
</li>
</ul>

===Initialization procedure===

The initialization procedure stores instructions for tasks you need to perform each time the subsystem is initialized. An example of such a task is the initialization of a particular work file. 

The initialization procedure is optional. If a subsystem uses an initialization procedure, the procedure name must be specified in the subsystem definition.

===Login procedure===

The login procedure performs the start up for each user of an application. Every time a user invokes the subsystem, <var class="product">Model 204</var> automatically includes the subsystem login procedure. 

The login procedure name must be specified in the subsystem definition. 

Typically, the login procedure is used to store current server table sizes in the global variable table for later reference, issue UTABLE commands to set compiler table sizes for the subsystem, and set the communication global variable to the name of the procedure that displays an initial menu. 
Example

Here is a sample login procedure:
CLEARG
BEGIN
IF $SETG('NTBL',$VIEW('LNTBL')) OR -
$SETG('VTBL',$VIEW('LVTBL')) OR -
$SETG('QTBL',$VIEW('LQTBL')) OR -
$SETG('STBL',$VIEW('LSTBL')) OR -
$SETG('FSCB',$VIEW('LFSCB')) OR -
$SETG('LECHO',$VIEW('LECHO')) OR -
$SETG('NEXT','PRE-MAIN.MENU') THEN
PRINT 'GTBL FULL'
END IF
END
UTABLE LNTBL=450,LQTBL=2300,LVTBL=600,LSTBL=3300
UTABLE LFSCB=5000
RESET LECHO 0


===Main processing procedures===

Main processing procedures perform the specific tasks of the subsystem. There can be as few or as many main processing procedures as necessary for the subsystem to perform its tasks. Main processing procedures are not specified in the subsystem definition. However, each procedure must follow the procedure naming conventions and subsystem coding rules discussed on this page. 

====Example====

Here is a sample procedure:
BEGIN
MENU MAINMENU
TITLE 'AUTO INSURANCE SYSTEM (MAIN MENU)' AT 10 BRIGHT
MAX PFKEY 12
SKIP 5 LINES
PROMPT 'MAINTENANCE' AT 10 BRIGHT
SKIP 2 LINES
PROMPT 'REPORTING' AT 10 BRIGHT
SKIP 2 LINES
PROMPT 'EXIT' AT 10 BRIGHT
END MENU
%NEXT = 'X'
REPEAT WHILE %NEXT = 'X'
READ MAINMENU
IF %MAINMENU:SELECTION = '1' THEN
%NEXT = 'PRE-MAINT.PGM'
ELSEIF %MAINMENU:SELECTION = '2' THEN
%NEXT = 'PRE-RPT.PGM'
ELSE %NEXT = 'NON-FINISH'
END IF
END REPEAT
CHK.GTAB: IF $SETG('NEXT',%NEXT) THEN
AUDIT 'GLOBAL TABLE FULL - "NEXT"'
END IF
END


===Error procedure===

An error procedure, which is optional, performs error handling. This procedure is invoked when a condition occurs that cannot be trapped by the executing procedure (for example, a compiler error or an attention with no ON ATTENTION unit coded). An error procedure tests for different error conditions and determines the next procedure to execute, based on the error code value stored in the error global variable. Terminal I/O in a subsystem error procedure following a BUMP or inactive thread timeout results in cancellation of the procedure. 

====Example====

The following error procedure assumes that the error global variable name is ERRCLASS, the communication global variable name is NEXT, and the exit value of the communication global variable is EXIT.
PROCEDURE SYS-ERROR
BEGIN
*
* GET THE VALUE OF THE ERROR CLASS GLOBAL VARIABLE
*
GET.VALUE: %ERRORCODE = $GETG('ERRCLASS')
*
* IF THE USER HIT ATTENTION, INCLUDE THE MAIN MENU SCREEN
*
IF.ERROR: IF %ERRORCODE = 'ATN' THEN
%NEXT = 'SYS-MAIN-MENU'
*
* IF PHONE WAS HUNG UP, OR ANY KIND OF RESTART, THEN AUDIT
* MESSAGE AND EXIT. DO NOT ATTEMPT ANY TERMINAL I/O
* SINCE USER IS NO LONGER CONNECTED.
*
ELSEIF %ERRORCODE = 'HNG' OR -
%ERRORCODE = 'SFT' OR -
%ERRORCODE = 'HRD' THEN
AUDIT 'SUBSYSTEM ERROR CODE: ' -
WITH %ERRORCODE
%NEXT = 'EXIT'
*
* CHECK FOR BROKEN FILE
*
ELSEIF %ERRORCODE = 'FIL - BROKEN' THEN
PRINT ' SUBSYSTEM FILE IS BROKEN'
PRINT ' CONTACT YOUR FILE MANAGER '
%NEXT = 'EXIT'
*
* SOME UNACCOUNTABLE ERROR HAS OCCURRED, SET EXIT
* ROUTINE, AND EXIT WITHOUT DOING ANY TERMINAL I/O.
*
ELSE
AUDIT 'NOT ACCOUNTED FOR SUBSYSTEM ERROR CODE: ' -
WITH %ERRORCODE
%NEXT = 'EXIT'
END IF IF.ERROR
*
* SET COMMUNICATIONS VARIABLE TO EXIT VALUE
*
COMM.VAR: IF $SETG('NEXT',%NEXT) THEN
AUDIT 'GTBL full in SYS-ERROR trying to set NEXT to ' WITH %NEXT
PRINT 'GTBL FULL'
END IF
END.REQUEST: *
END
END PROCEDURE


==Security options==

During subsystem definition, various options are specified for a subsystem. Security options determine subsystem command and file and group privileges assigned to a user. 

You can also specify system operation options during subsystem definition. System operation options are discussed in the [[#Operating options|Operating options]] section.
For a detailed discussion of subsystem definition options, refer to [[System requirements for Application Subsystems]]. 

===Status of subsystem===

The status of the subsystem affects the type of subsystem security that is implemented. The subsystem can have one of three status settings: 
<table>
<tr class="head">
<th>Status setting </th>
<th>Allows access to...</th>
</tr>

<tr>
<td>Public </td>
<td>All users. All users who enter a public subsystem are assigned to the single subsystem user class and have the same set of privileges. </td>
</tr>

<tr>
<td>Semipublic </td>
<td>All users but permits different privileges to be assigned for each user. In a semipublic subsystem, one subsystem user class can be defined as the default class for all users not specifically assigned to another subsystem user class. </td>
</tr>

<tr>
<td>Private </td>
<td>Only to specified users. Using a private subsystem prevents any unauthorized entry into the subsystem. All users who are allowed access must be assigned to one of the defined user classes. Unlike a semipublic subsystem, a private subsystem has no default user class. </td>
</tr>
</table>

===User class===

The set of privileges assigned to a user is based on the user's subsystem user class or SCLASS. The SCLASS is used by <var class="product">Model 204</var> to determine the privileges assigned for each file and group in the subsystem when files are opened for the user. File and group privileges must be specified in the subsystem definition because <var class="product">Model 204</var> bypasses <var>OPENCTL</var> parameter settings and file passwords when opening subsystem files and groups for each user. Whenever the user invokes the subsystem, he/she is assigned the file and group privileges of that subsystem user class. 

The SCLASS also determines whether or not the user can issue any of the subsystem control commands listed below. If <var class="product">Model 204</var> discovers that the user does not have the correct privileges to issue a command, an error message is displayed.
<table>
<tr class="head">
<th>Subsystem control commands </th>
<th>Directs Model 204 to...</th>
</tr>

<tr>
<td><var>DEBUG SUBSYSTEM</var> </td>
<td>Establish a test environment for a multiuser version of the <var>TEST</var> command extension. The subsystem does not have to be stopped to issue the <var>DEBUG</var> command.

When a user enters a subsystem in <var>TEST</var> or <var>DEBUG</var> mode, the user's MSGCTL parameter setting is not changed. All error and informational messages that are not suppressed by the user's <var>MSGCTL</var> setting are displayed on the user's terminal. 
</td>
</tr>

<tr>
<td><var>START SUBSYSTEM</var> </td>
<td>Activate the subsystem and make it available for use. If the subsystem is inactive when the <var>START</var> command is issued, <var class="product">Model 204</var> opens all the subsystem files and includes the subsystem initialization procedure. </td>
</tr>

<tr>
<td><var>STOP SUBSYSTEM</var> </td>
<td>Stop the subsystem and make it unavailable for use. Once a subsystem is stopped and all users have exited, then all locking and storage resources held by the subsystem are released and all the subsystem files and groups are closed. </td>
</tr>

<tr>
<td><var>TEST</var> </td>
<td>Establish a single user test environment. The <var>TEST</var> command is extended to <var>TEST DEBUG SUBSYSTEM</var>. The subsystem must be stopped to enter <var>TEST</var> mode.</td></tr>
</table>

Note: Several aspects of <var>START SUBSYSTEM</var> and <var>STOP SUBSYSTEM</var> processing are unique to distributed applications. For a discussion, see [[PQO: Scattered APSY subsystems#Subsystem command processing|Subsystem command processing]].

===Processing of security violations===

The application subsystem traps security violations that occur while a user is running in a subsystem. File read and update security violations, procedure security violations, and field level security violations are interpreted as compilation or evaluation errors in the error global variable. The audit trail messages produced when the error occurred can be examined in order to identify a compilation or evaluation error as a security violation. 

===Compiling procedures with a different SCLASS===

In the following situation, <var class="product">Model 204</var> saves User 1's compilation:
<ol>
<li>There are multiple SCLASSes for a subsystem.</li>
<li>User 1 saves a procedure under SCLASS 1.</li>
<li>User 2, under SCLASS 2, recompiles the procedure.</li>
<li>User 2's global variables contain different information from User 1's so User 2 tries to open different files or groups than User 1. </li>
</ol>

However, User 2's compilation is not saved: User 2 receives an error message:
M204.0468: COMPILATION NOT SAVED - reason


==Operating options==

Operating options affect certain aspects of the overall behavior of a subsystem. Operating options are distinct from security options, which are discussed in [[#Security options|Security options]].
Subsystem options are also discussed in [[System requirements for Application Subsystems]]. 

The following table lists the operating options and what they determine.
<table>
<tr class="head">
<th>Operating option </th>
<th>Determines whether...</th>
</tr>

<tr>
<td>Automatic start </td>
<td>Subsystem automatically starts for the first user entering the subsystem. </td>
</tr>

<tr>
<td>Locking files and groups for subsystem use </td>
<td>Users from outside the subsystem can open and update subsystem files while the subsystem is active. </td>
</tr>

<tr>
<td>Automatic login </td>
<td>Users are automatically logged into <var class="product">Model 204</var> upon entering a subsystem. </td>
</tr>

<tr>
<td>Automatic logout </td>
<td>Users are automatically logged out of <var class="product">Model 204</var> upon exiting a subsystem. </td>
</tr>

<tr>
<td>Automatic COMMIT </td>
<td>Any outstanding updates are committed automatically whenever a subsystem procedure ends and transfers control using the communications global variable. </td>
</tr>

<tr>
<td>Message displays </td>
<td>Disconnect, informational, and error messages are displayed for subsystem users. </td>
</tr>

<tr>
<td>File usage </td>
<td>Subsystem can run when one or more files used by the subsystem are unavailable for use. </td>
</tr>
</table>

===Automatic start===

If the automatic start option is selected, <var class="product">Model 204</var> invokes subsystem initialization when the first user attempts to enter the subsystem. The subsystem can be used without a privileged user first issuing the START SUBSYSTEM command.

If the automatic start option is not selected, subsystem initialization occurs only when the START SUBSYSTEM command is issued. The subsystem is then available for use. 

===Locking files and groups for subsystem use===

If the locking files and groups option is selected, <var class="product">Model 204</var> prevents users that are not running in the subsystem from opening any of the subsystem files or groups while the subsystem is active. 

If the locking files and groups option is not selected, users from outside the subsystem can retrieve, modify, or delete records in a subsystem file while the subsystem is active. 

===Automatic login===

If the automatic login option is selected, <var class="product">Model 204</var> logs on the user when the user enters a subsystem. The user is logged in using the subsystem name as the <var class="product">Model 204</var> user ID. If the user already has logged into <var class="product">Model 204</var> before entering the subsystem, <var class="product">Model 204</var> first closes all the user's files and logs out the user. 

The LOGOUT operations that occur as a result of Automatic Login (both at subsystem Login and Disconnect) ignore the SYSOPT=8 (DISCONNECT on LOGOUT) option.

If the login option is not selected, the user's <var class="product">Model 204</var> user ID is used during subsystem processing. 

===Automatic logout===

If the automatic logout option is selected, the user is logged out of <var class="product">Model 204</var> upon exiting the subsystem. This option is particularly useful when combined with the automatic disconnect feature of <var class="product">Model 204</var>. 

The START SUBSYSTEM command ignores the SYSOPT=8 option for the Automatic Logout subsystem.

If the automatic logout option is not selected, <var class="product">Model 204</var> logs the user out of the subsystem in one of three ways:
<ul>
<li>If the user was previously logged into <var class="product">Model 204</var>, <var class="product">Model 204</var> restores the user's original user ID and returns the user to the <var class="product">Model 204</var> command environment.</li>

<li>If the user was not previously logged into <var class="product">Model 204</var>, the user is logged out of <var class="product">Model 204</var>.</li>

<li>The SYSOPT=8 option causes the user to be disconnected from <var class="product">Model 204</var>.
</li>
</ul>

===Automatic COMMIT===

If the automatic COMMIT option is selected, <var class="product">Model 204</var> automatically issues a COMMIT statement for any outstanding updates whenever a subsystem procedure terminates and transfers control using the communication global variable. If the COMMIT option is not selected, the application must issue the COMMIT statement to commit any pending updates. 
===Commit exits===
Note: This feature is available as of Model 204 release 7.8. It is licensed and purchased separately from Model 204.
A commit exit enables you to set up SOUL code to run at commit time, as in: "on commit run <var class="term">xxx</var>".

When the user executes a commit (or an implied commit), the APSY specified by <var>COMMITX</var> is driven on a transactional daemon.

The APSY follows standard APSY rules. The commit exit is only driven once; that is, subsequent commits do not call the APSY. The commit exit is only driven for TBO transactions.

A commit/backout coded inside the commit exit commits/backs out the active transaction. Any new transaction within the exit causes a new update unit to begin.

====COMMITX parameter====
The commit exit runs within the APSY defined by the <var>COMMITX</var> parameter and uses normal APSY processing.

The new parameter <var>COMMITX</var> is settable from User 0's parameter line or by the system manager. It can be reset at any time by the system manager.

Setting/Resetting the parameter sends a DYRWT message to the issuer and requires a Yes or No response (unless set/reset by user0).

If <var>COMMITX</var> is specified, all APSY subsystems participate by default but any can be exempted.

====Activating the commit exit APSY====
<ul>
<li>To activate the commit exit APSY, issue:
Reset COMMITX <var class="term">apsyname</var>
where <var class="term">apsyname</var> is the APSY where you are running the commit exit.
Enter <code>Yes</code> at the confirmation prompt.</li>
<li>To exempt any APSY subsystem:
<ol>
<li>Pull up the SUBSYSMGMT <var>Operational Parameters</var> screen for that subsystem.</li>
<li>At the 'Subsystem supports commit exit' item, enter <code>N</code>.</li>
</ol>
</li>

<li>To deactivate the commit exit APSY, issue:
Reset COMMITX
Enter <code>Yes</code> at the confirmation prompt.
</li>
</ul>

====Examples====

The following are examples of login exits which print all changed records.
=====Example 1=====
b
%d object xmldoc auto new
%rec object xmldoc auto new
%d:loadchangedrecords
%f string len 8
%r float
%c float initial(1)
repeat %d:selectcount('//Record') times
%f = %d:value('//Record[' %c ']/@file')
%r = %d:value('//Record[' %c ']/@number')
%c = %c + 1
%rec:loadfromrecord(FILE=%f,RECORDNUMBER=%r)
%rec:print
%rec = new
end repeat
if $SETG('NEXT','EXIT') then
audit 'gtbl full'
end if
end 

=====Example 2=====
b
%d object xmldoc auto new
%d:loadchangedrecords(fields=true)
%d:print
if $SETG('NEXT','EXIT') then
audit 'gtbl full'
end if
end 

=====Example 3=====
b
%d object xmldoc auto new
%recs object xmldoc auto new
%n object xmlnode
%d:loadchangedrecords
%f string len 8
%r float
%c float initial(1)
%n = %recs:AddElement('ChangedRecords')
repeat %d:selectcount('//Record') times
%f = %d:value('//Record[' %c ']/@file')
%r = %d:value('//Record[' %c ']/@number')
%c = %c + 1
%n:loadfromrecord(FILE=%f,RECORDNUMBER=%r,HEADER=TRUE)
end repeat
%recs:print
if $SETG('NEXT','EXIT') then
audit 'gtbl full'
end if
end 

There are new parameters for several of the methods (as demonstrated above):
LoadChangedRecords:
Fields=boolean (default=false)

If true, each individual changed record is loaded into the XMLDOC similar to LoadFromRecord.

LoadFromRecord:
File=name
RecordNumber=number 

LoadFrom Record must normally be issued within a FOR record context. However, if both of these name required parameters are specified, the LoadFromRecord statement need not be within a FOR record context.

If either of these name required parameters is specified from within a FOR record context, an error message will be issued: <code>ERROR 1081: %C inside record loop: Recordnumber/File parameters not allowed</code>

LoadFromRecord:
Header=Boolean (default=false)

If true, the header line of the method will be included for each item. This may be useful when LoadFromRecord is issued in order to load an XMLNODE.

The header will separate each record and designate the file and record number.

====Error handling====

=====Current behavior without commit exits=====

Without commit exits, an APSY does not commit automatically unless AUTOCOMMIT=Y is specified in the APSY definition.
<ul>
<li>If a transactional daemon is created:
Commit/backout must be explicitly specified within a daemon in order to effect the master’s transaction.
Implicit commit on the daemon is never done. Normal end of the daemon does not affect the master.
If the daemon procedure is cancelled, the master transaction is backed out.
If the daemon procedure is abended, the master transaction is backed out and the APSY error proc is run on the master.</li>

<li>If a non-transactional daemon is created:
The master transaction is unaffected by the daemon.
Both implicit and explicit commit affect the daemon transaction only.
If the daemon procedure is cancelled, only the daemon transaction is backed out.
If the daemon procedure is abended, both the daemon and master transaction are backed out and the APSY error proc is run on the master.</li>
</ul>

Each time that an APSY loads a new procedure, the various KSERRC flags are always cleared. So when an error procedure is called, the error flags are always zero.

=====With commit exits=====

With the commit exits feature, the commit exit essentially runs as a transactional daemon with the original user being a pseudo master. Lower level daemons follow normal daemon behavior.
If a commit exit is running, and the APSY fails, the APSY error exit is scheduled to run. If the APSY error exit exists, the original transaction unit will be unaffected, unless the exit specifically designates a commit/backout. If there is no APSY error exit, the original transaction unit is aborted with <code>ERROR 2971: Action disabled by commit exit</code> and the user is restarted.

===Message displays===

<var class="product">Model 204</var> provides these message display options for subsystem users: 
<ul>
<li>Disconnect message display</li>

<li><var class="product">Model 204</var> informational message display</li>

<li><var class="product">Model 204</var> error message display
</li>
</ul>

When a message display option is selected, messages of that type are displayed on the user's terminal. If a message display option is not selected, all messages of that type are not displayed on the user's terminal. Note that if the display of any <var class="product">Model 204</var> type message is suppressed, messages for the corresponding type are not displayed on the user's terminal, but are written to the audit trail file (CCAAUDIT).

Typically, subsystem applications are written so that all messages displayed on the user's terminal are produced by the subsystem and <var class="product">Model 204</var> messages are suppressed. 

===File usage===
====Mandatory vs. optional members====

Files and permanent groups contained within the subsystem definition can be designated as mandatory (the default) or optional members of the subsystem: 
<ul>
<li>Mandatory members

Mandatory files or groups are automatically opened by <var class="product">Model 204</var> when a user logs into a subsystem and automatically closed when the user leaves the subsystem. Subsystem requests can assume that all mandatory files are open and that they are physically consistent. The user's file privileges are those defined in the subsystem definition for the current user's SCLASS. The opening of a mandatory member cannot be prevented by the subsystem administrator with the <var>STOP FILE</var> command when the subsystem is active. A mandatory member cannot be accessed by another copy of <var class="product">Model 204</var> until the entire subsystem is stopped.

If a subsystem procedure issues an <var>OPEN</var> or <var>CLOSE</var> command for a mandatory member, the command is ignored by <var class="product">Model 204</var> and the user's current privileges are not changed.</li>

<li>Optional members

Optional files or groups provide the ability for a file or group to be stopped by a subsystem administrator (using the <var>STOP FILE</var> command) without stopping the entire subsystem. If a member is defined as optional, it is not automatically opened during the subsystem login. It must be opened by the application by using an OPEN/OPENC statement or command. The file privileges assigned are those specified in the subsystem definition for the current user's SCLASS. The member is closed (for that user only) when the user leaves the subsystem if a <var>CLOSE</var> command has not been issued.

When an optional member is not in use, it can be processed by another copy of <var class="product">Model 204</var>. </li>
</ul>

Requests that reference mandatory or optional members can be precompiled. Files not contained in the subsystem definition can be opened and referenced within a subsystem application, but the requests that reference those files cannot be precompiled. 

====Automatic vs. manual members====

Subsystem files and permanent group members can also be designated automatic or manual:
<ul>
<li>An automatic member is a subsystem group or file that is opened automatically when the subsystem is started or when a user enters the subsystem. </li>

<li>A manual member is a group or file that must be opened explicitly by the OPEN or OPENC command.
</li>
</ul>

Mandatory files cannot be designated manual. Optional files can be designated either automatic or manual.

====Permanent vs. temporary groups in subsystem definitions====

The GROUP parameter of the subsystem definition applies only to permanent groups. Temporary group names cannot be used. To include temporary group members in a subsystem definition, and thus to enable their use in precompiled code, the members of the temporary group should be individually specified in the subsystem definition.

====Summary of file definition options====

[[#Summary of file definition options|Subsystem file definition options]] summarizes the subsystem file definition options. 
<table>
<caption>Subsystem file definition options</caption>
<tr class="head">
<th>Subsystem definition option</th>
<th>Automatic
open and close?</th>
<th>
Pre-compiled code?</th>
<th>Start/stop file command allowed?</th>
<th>File privileges assigned</th>
</tr>

<tr>
<td>Mandatory</td>
<td>Must be automatic</td>
<td>Yes</td>
<td>No</td>
<td>SCLASS</td>
</tr>

<tr>
<td>Optional</td>
<td>Can be automatic or manual</td>
<td>Yes</td>
<td>Yes</td>
<td>SCLASS</td>
</tr>

<tr>
<td>None</td>
<td>Cannot be
automatic</td>
<td>No</td>
<td>Yes</td>
<td>File Password</td>
</tr>
</table>

==Subsystem processing flow==

To design a subsystem, you must be familiar with the flow of control that occurs during subsystem processing. Subsystem processing typically involves the following phases:
<table>
<tr class="head">
<th>Type of processing </th>
<th>During this processing...</th>
</tr>

<tr>
<td>Initialization </td>
<td>Subsystem is started and an optional initialization procedure is included. </td>
</tr>

<tr>
<td>Login </td>
<td>User is logged into the subsystem; the user's privileges are determined by the subsystem definition. The appropriate required files and groups are opened for access. </td>
</tr>

<tr>
<td>Driver </td>
<td>Procedures that make up the main body of the application are included. </td>
</tr>

<tr>
<td>Disconnect </td>
<td>All files and groups are closed for the user, who is then logged out of the subsystem. </td>
</tr>

<tr>
<td>Error </td>
<td>An optional error procedure is included. The type of error that occurred is available to the error procedure. For many types of errors, the error procedure can resume normal driver processing. </td>
</tr>
</table>

===Initialization processing===

Initialization processing is invoked when the subsystem is started. A subsystem is started by the START SUBSYSTEM command, or, if the start option is indicated in the subsystem definition, when the first user enters the subsystem. 

During subsystem initialization, <var class="product">Model 204</var> finds the subsystem definition and opens only required subsystem files and groups. If a required file or group cannot be opened, the subsystem initialization procedure terminates and the user is returned to command level.

One of the subsystem components opened during initialization is the procedure file (or group, if a multiple-procedure group has been specified). The procedure file or group must contain all of the subsystem procedures that are included by the subsystem through the communication global variable. <var class="product">Model 204</var> scans the subsystem procedure file or group for all procedures whose names begin with either of the subsystem procedure prefixes. 

The subsystem initialization procedure is included at this time. This is the only time during subsystem processing that the initialization procedure is executed.

If no error occurs, <var class="product">Model 204</var> adds the subsystem name to the list of active subsystems. At this point, the subsystem is initialized and ready for use. 

===Login processing===

Login processing is invoked when a user enters a subsystem. If the automatic login option is indicated in the subsystem definition, <var class="product">Model 204</var> logs on the user using the subsystem name as the user ID. If the automatic login option is not indicated, the user's <var class="product">Model 204</var> user ID remains in use. 

<var class="product">Model 204</var> next finds the user's subsystem user class definition in CCASYS and opens only the required subsystem files and groups with the privileges that are found for that user class. The MSGCTL parameter automatically is set for the user according to the subsystem definition. 

<var class="product">Model 204</var> sets the communication global variable to the name of subsystem login procedure and proceeds into driver processing. 

===Driver processing===

<var class="product">Model 204</var> determines which procedure to include next by examining the value of the communication global variable. The procedure name must be one of the names located by the scan of the procedure file during subsystem initialization. 

If either the global variable or the procedure name cannot be found, the subsystem's error procedure is included. If an error procedure is not specified in the subsystem definition, the user is disconnected from the subsystem. 

If the procedure name is found, <var class="product">Model 204</var> determines which prefix begins the procedure name. Processing then occurs as follows:
<ul>
<li>If the procedure name begins with the non-precompiled prefix, <var class="product">Model 204</var> includes the procedure for compilation and evaluation. </li>

<li>If the procedure name begins with the precompiled prefix, <var class="product">Model 204</var> verifies whether the procedure was compiled previously with the set of privileges defined by the user's subsystem user class.

Once the compilation status of the procedure is determined, processing is as follows: 
<ul>
<li>If the procedure was not previously compiled successfully for the set of privileges defined by the user's subsystem user class, <var class="product">Model 204</var> includes the procedure for compilation and evaluation. If compilation is successful and no previous compilation was saved for the procedure, the contents of the compiler tables are saved in the system file CCATEMP.</li>

<li>If the procedure was previously compiled successfully for the user's privilege set, <var class="product">Model 204</var> loads the contents of the compiler tables from CCATEMP and evaluates the request.</li>
</ul></li>
</ul>

<var class="product">Model 204</var> repeats driver processing until the value of the communication global variable is set to the exit value specified in the subsystem definition. When the communication global variable is set to the exit value, <var class="product">Model 204</var> proceeds into disconnect processing. 

===Disconnect processing===

Disconnect processing is invoked when the subsystem application sets the communication variable to the exit value, when an error occurs with no subsystem error procedure, or when a subsystem user is restarted by <var class="product">Model 204</var>. During disconnect processing, <var class="product">Model 204</var> closes all required subsystem files and groups for the user, as well as any optional files and groups that have not been closed by the application. 

Depending upon whether the automatic logout option is indicated, the user is then either logged out of <var class="product">Model 204</var> or returned to the <var class="product">Model 204</var> command environment. 

===Error processing===

Error processing is invoked whenever a <var class="product">Model 204</var> error occurs that cannot be handled by the procedure being executed at the time. When an error is detected, <var class="product">Model 204</var> sets the value of the error global variable. 

If the subsystem has a defined error procedure, the error procedure is included at this time. If the subsystem does not have a defined error procedure, <var class="product">Model 204</var> proceeds into disconnect processing. 

If the error trapped by the subsystem is a soft restart, a hard restart, or a terminal disconnect condition, the error procedure is invoked. The communication global variable is ignored when the error procedure completes and <var class="product">Model 204</var> proceeds with subsystem disconnect processing. 

==Parallel Query Option/204 (PQO) considerations==

This section introduces several terms and concepts which are unique to subsystems that reference remote files and scattered groups. These concepts, and related design considerations, are discussed in greater detail in [[PQO: Scattered APSY subsystems]]. 

===Remote file access===

Parallel Query Option/204 provides access to remote files under the Subsystem Management facility by allowing the system manager to define client and service subsystems:
<ul>
<li>A client subsystem is the subsystem a user is running in when requesting access to remote data. </li>

<li>A service subsystem is the subsystem on a server node that a client user's service thread is logged into.
</li>
</ul>

A service subsystem definition is stored in the CCASYS file on each node that the client subsystem accesses. The name of a subsystem must be the same at each node. The location of the client node is included in the subsystem name to uniquely identify it to the server node.

===Node availability===

A server node can be available or unavailable to a client subsystem.
<ul>
<li>A node is available if the service subsystem has been successfully started. </li>

<li>If the service subsystem has not been started, it does not have a subsystem definition structure accessible to the client and is therefore unavailable.
</li>
</ul>

A node can only be marked unavailable during start processing if there are mandatory members on a server node and the service subsystem cannot be started. If this happens, start processing also fails on the client node.

Client subsystems attempting to access service subsystems that are not started receive an error message from the server node. 

A previously available node can become unavailable when: 
<ul>
<li>Resumption of communication fails after recovering from a system failure.</li>

<li>A user attempts to log into the service subsystem by logging into the client subsystem, the service subsystem definition is not found, and at least one mandatory member resides on that node.</li>

<li>A user attempts to open a file on a node where the user was not previously logged in. </li>
</ul>

The user is automatically logged into all associated service subsystems when entering a subsystem that contains remote files. If the service subsystem is unavailable on a node, the user cannot be logged in. 

===File and group availability===

The members of a subsystem are files and permanent groups. With Parallel Query Option/204, members can be either automatic or manual: 
<ul>
<li>An automatic member is a subsystem group or file that is opened automatically when the subsystem is started or when a user enters the subsystem. </li>

<li>A manual member is a group or file that must be opened explicitly by the OPEN or OPENC command.
</li>
</ul>

Members can also be either mandatory or optional:
<ul>
<li>A mandatory member must be open in order to access a subsystem. Mandatory members cannot be manual.</li>

<li>An optional member is not required for subsystem access (start and login processing can succeed without it).
</li>
</ul>

At any given time a member can be open or closed to a subsystem or to a user within a subsystem. The following sections explain the conditions under which the different kinds of members are accessible to APSY subsystems and their users.

====Member availability to subsystems====

Automatic members of subsystems are always opened by the START SUBSYSTEM command or by SUBSYSTEM LOGIN. At the end of START processing, each automatic member is open unless either the START or OPEN failed. 

Manual members of subsystems are in the closed state at the completion of START SUBSYSTEM processing and must be explicitly opened by the user. Manual members become open to the subsystem if an OPEN operation succeeds. If OPEN fails due to node unavailability or for user-specific reasons (for example, if the user's line goes down) the member remains closed to the subsystem.

If a node becomes unavailable to a subsystem, all automatic subsystem members and all open manual subsystem members residing on the unavailable node are marked disabled.

If a STOP FILE/GROUP command is issued for a manual member on the client subsystem's node, the member is closed to the client subsystem when the last user closes it. If the member is located on the service subsystem node, the file is closed to the service subsystem when the STOP is complete or the last user closes the file.

====Member availability to subsystem users====

When a user enters a subsystem, automatic subsystem members are opened.

If a user LOGIN or OPEN operation fails for an optional member, the member is left closed for the user but remains available to the subsystem. If a mandatory member cannot be opened, the user is denied access to the subsystem.

If a user LOGIN or OPEN operation fails for an already open member, the member is left disabled for the user but remains open to the subsystem. 

If an automatic mandatory member is closed to the subsystem, new users are not allowed to enter the subsystem.

Manual members of subsystems are closed for a user within a subsystem until the user issues an OPEN command or statement. In this case it does not matter whether the member is open or closed to the subsystem.

If compilation and/or loading of a request fails due to a communications failure, previously opened members on the failing node become disabled to the user. 

A user can close optional members at any time by issuing the CLOSE command.

====Enabling disabled subsystem files====

In the event that a subsystem file or group is marked disabled, you can enable it (after correcting the problem) without having to bring the subsystem down. To do this, use the ENABLE SUBSYSTEM command:

====Syntax====
ENABLE SUBSYSTEM subsysname
[FILE name AT location | GROUP name]

Where:
<ul>
<li><var class="term">subsysname</var> is the name of the client subsystem</li>

<li><var class="term">location</var> is the name of the remote node where the file is stored. Note that the location must be explicitly specified; you cannot reference local files with the ENABLE SUBSYSTEM command.
</li>
</ul>

====Intentionally disabling a subsystem file====

You can make a subsystem file or group (or an entire subsystem, if a file is mandatory) temporarily inaccessible without having to bring the subsystem down, using the DISABLE SUBSYSTEM command:
DISABLE SUBSYSTEM subsysname
[FILE name AT location | GROUP name]


When a file or group is intentionally disabled with the DISABLE SUBSYSTEM command, subsystem behavior is exactly the same as when a communications failure causes the disabling. This behavior is described in [[#File and group availability|File and group availability]].

===Trust===

As an alternative to the privilege settings normally available through the Subsystem Management facility, the system manager at a service node can control client subsystem access by creating a trust definition for the client subsystem. If a client subsystem is fully or partially trusted, the trust definition is sufficient for maintaining the relationship with the client; the system manager at the service node does not have to create and maintain a separate set of file and SCLASS definitions for the client subsystem.

For example, suppose a subsystem located on a node named DETROIT (the client node) includes in its definition files located on a node named CLEVELAND (the service node). Further, suppose the subsystem is fully or partially trusted by CLEVELAND. In this case, the file and SCLASS definitions are maintained only on the client node (DETROIT), and the service node (CLEVELAND) needs only to maintain the trust definition.

The four levels of trust available with Parallel Query Option/204 are:
<ul>
<li>Full trust

Only the subsystem name and location appear on the service node's definition, which you create on the Subsystem Trust screen.</li>

<li>Partial trust

Along with the subsystem name and location, you can specify maximum file privileges. In this case, the client subsystem is trusted, but the maximum file privileges and field level security levels specified on the Subsystem Trust screen cannot be exceeded.
<ul>
<li>If a user requests file privileges that would exceed the maximum, the service node does not open the file to that user.</li>
<li>If a user requests a field level security status that would exceed the maximum, <var class="product">Model 204</var> automatically resets the request to the allowed level (that is, the maximum) and opens the file to that user.</li>
</ul></li>

<li>Restricted trust

For a subsystem that has a restricted trust definition, you make no entries on the Subsystem Trust screen. A restricted trust definition is based solely on entries you make on these five screens:
<ul>
<li>Subsystem Activity</li>
<li>Subsystem File Use</li>
<li>Operational Parameters</li>
<li>Subsystem Classes</li>
<li>Subsystem Class Users</li>
</ul>

The accessibility of service node files to a client subsystem is determined by the SCLASS, user, and file privileges that you specify on these screens. 
</li>

<li>No trust

No subsystem service definition exists for the subsystem. The client subsystem cannot access any files on the service node as subsystem files. The files on the service node can, however, be accessed from within a client subsystem as individual, non-subsystem files if the following criteria are met:
<ul>
<li>Parallel Query Option/204 is installed at both sites.</li>
<li>Horizon is installed at both sites, and there are link, processgroup, and process definitions connecting the client node to the service node.</li>
<li>For any given file, the value of the <var>[[OPENCTL parameter|OPENCTL]]</var> parameter allows remote access (X'02', X'04', or X'08'). </li>
</ul>
</li>
</ul>

See the
<var class="book">Rocket Parallel Query Option/204 User's Guide</var> for detailed information on creating and managing trust definitions.

==Subsystem design considerations==

This section presents coding considerations for subsystem procedures. Some of the guidelines listed below also appear in earlier sections. They are consolidated here for the convenience of the application developer. 

===Coding considerations===
<ul>
<li>Procedures should be small and modular.</li>

<li>Procedures to which control is passed via the communication global variable must be stored in a designated procedure file. The procedure file is the default file for a subsystem application unless the default file is explicitly changed by a DEFAULT command or overridden by an IN clause.</li>

<li>Each procedure must set the communication global variable to indicate the next procedure to be included. If this variable is not set, an error or loop occurs.</li>

<li>The communication global variable must be set to the exit value in order to exit the subsystem. Server table sizes and other parameters should be reset to the values existing prior to entering the subsystem so that the user is returned to his/her normal operating environment. Parameter values are restored automatically when the automatic login option is used.</li>

<li>Included procedures normally are included by using the INCLUDE command. Included procedures cannot be precompiled.</li>

<li>Non-subsystem files can be opened and referenced only by non-precompiled procedures.</li>

<li>Precompiled procedures cannot reference PERM groups that are not members of the same subsystem.</li>

<li>Compiler table sizes must be the same each time a precompiled procedure is invoked. The UTABLE command should be used carefully.</li>

<li>The contents of the command line global variable are not deleted by UTABLE commands which normally delete the contents of GTBL, as long as the UTABLE command is issued from within a subsystem. </li>

<li>Distinct group numbers are assigned to optional groups at START SUBSYSTEM time. Those numbers cannot be used by non-subsystem members opened within the subsystem. Thus the NGROUP limit used for earlier releases might be exceeded during either START or OPEN processing inside the subsystem.</li>

<li>To prevent you from having the wrong file or group privileges in a subsystem, <var class="product">Model 204</var> closes optional files and groups before entering a subsystem. In earlier releases, optional files and groups were only closed when you left the subsystem.
</li>
</ul>

Users should be aware of the following conditions when coding applications to run under the Subsystem Management facility:
<ul>
<li>Dummy strings (??, ?$, ?&) in precompiled procedures are resolved only during compilation for the first user.</li>

<li>If a subsystem file is referenced by a precompiled procedure, no user can RESTORE or INITIALIZE the file, or RENAME, DELETE, or REDEFINE a field while the subsystem is active.</li>

<li>A subsystem procedure cannot issue the CREATE command for a subsystem file.</li>

<li>LXTBL and LFTBL cannot be reset from within a subsystem procedure.</li>

<li>All DO YOU REALLY WANT TO messages are suppressed and the default action is assumed.

The default action for each type of message is listed in [[M204.1076]]. 

If you do not wish the default action to be executed, you need to add a message handler routine to the procedure containing the statement that invokes the message. 
</li>
</ul>

====Keeping track of the number of files referenced====

To keep track of the files referenced in a subsystem procedure, which cannot exceed 6,043 files — a CCATEMP page, use the following formula:
NFILE + NRFILE + 1 (for CCAGRP) + 1 (for CCASYS)


==Record locking considerations==

Depending upon the subsystem definition, <var class="product">Model 204</var> might place a share lock on one or more subsystem procedure names or group names. 

If the subsystem is defined with permanent groups, <var class="product">Model 204</var> locks the group names to ensure that the group definitions do not change while the subsystem is running. A share lock is maintained for each group while the subsystem is active. 

===If subsystem files are defined as unlocked===

If the subsystem definition specifies that subsystem files are unlocked, <var class="product">Model 204</var> locks in share mode each of the subsystem procedures to ensure that the procedures do not change or move. This prevents any user from:
<ul>
<li>Issuing the DELETE PROCEDURE command</li>

<li>Issuing the RENAME PROCEDURE command</li>

<li>Updating the procedure while the subsystem is active.
</li>
</ul>

==Subsystem procedure control functions==

The User Language functions, [[$Sclass#$Sclass|$Sclass]] and [[$Subsys#$Subsys|$Subsys]] can be useful in determining subsystem program control.

===$Sclass function===

The $Sclass function returns the Sclass name of the current user. $Sclass is useful when the transfer of control is dependent upon a user's privileges. For example:
 BRANCH: JUMP TO (ADD.REC, VIEW.REC, UPD.REC) -
%MAIN.MENU:SELECTION
.
.
.
UPD.REC: IF $sclass = 'READ' THEN
IF $SETG('NEXT','PRE-RPT.PGM') THEN
PRINT 'GLOBAL TABLE FULL'
END IF
ELSEIF $sclass = 'UPDATE' THEN
IF $setg('NEXT','PRE-MAINT.PGM') THEN
PRINT 'GLOBAL TABLE FULL'
END IF
.
.
.


===$Subsys function===

The $Subsys function returns a numeric value indicating the status of a subsystem, or the name of the current subsystem (if no argument is specified). $Subsys often is used to determine whether a subsystem is active before a transfer is attempted. 

==Subsystem development tools==

This section describes three <var class="product">Model 204</var> features that are useful in developing, testing and debugging subsystem procedures:
<ul>
<li>The <var>[[DEBUG command|DEBUG]]</var> and <var>[[TEST command|TEST]]</var> commands, which assist subsystem debugging by allowing you to display the global communications variable and specify the next procedure to be INCLUDEd.</li>

<li>Multiple procedure file groups, which allow users to change procedures without stopping the subsystem or interfering with other users.</li>

<li>The Cross-Reference facility, which produces reports on the variable names, global dummy strings, and other language elements used in a specified set of User Language procedures. </li>
</ul>

===Debugging and testing facilities===

The <var class="product">Model 204</var> DEBUG and TEST SUBSYSTEM commands assist you in debugging subsystem code while it is being developed. Both commands display the value of the communication global variable, prompt you for changes, and display since-last statistics. 

DEBUG differs from TEST SUBSYSTEM in the following ways:
<ul>
<li>DEBUG can be executed by more than one user in the same subsystem at the same time; TEST SUBSYSTEM can only be executed by a single user.</li>

<li>To execute TEST SUBSYSTEM, the user must stop the subsystem, which will be restarted in single user mode as a result of issuing the TEST command. To execute DEBUG, the user does not have to stop the subsystem. The DEBUG command can be issued for any subsystem that has been started, or for any subsystem that has the AUTOSTART feature.</li>

<li>Since-last statistics are provided automatically with DEBUG; they are optional with TEST.
</li>
</ul>

In general, the DEBUG command is more convenient for subsystem developers in a multiuser environment.

To execute the DEBUG command, the user must be named to an SCLASS which has been granted either the TEST or DEBUG privilege. The DEBUG privilege does not entitle the user to execute the TEST command.

====Syntax====

The format of the DEBUG command is: 
DEBUG SUBSYSTEM subsystemname [parameters]


The extended format of the TEST command is:
TEST [DEBUG] [STATS] [SUBSYSTEM] subsystemname parameters

Where:
<ul>
<li>DEBUG specifies that the communication global variable is displayed on the user's terminal before the next procedure is included. The user then has the option of specifying a different procedure to be included next. If the user presses <var>ENTER</var> without specifying a different procedure, the procedure whose name is currently displayed is included next. </li>

<li>STATS specifies that since-last statistics are displayed on the user's terminal after each procedure is evaluated. Since-last statistics are described in [[Using system statistics#User since-last statistics|User since-last statistics]]. </li>

<li>SUBSYSTEM specifies that the word following the keyword is the name of a subsystem and that parameters follow the subsystem name. This keyword can be used to eliminate confusion when DEBUG or STATS is the name of a subsystem or subsystem parameter. </li>

<li>parameters specifies the parameters to be stored in the command line global variable. The parameter information can be as many as 255 characters in length.
</li>
</ul>

===Multiple procedure files===

If <code>PROCFILE=*</code> is specified when a group is created, then several files in a group can contain procedures. When the <var>INCLUDE</var> command is executed in the context of a multiple procedure file group, files are searched, left to right, in the order they were defined in the original <var>CREATE GROUP</var> command.

Multiple procedure file groups make it possible to change subsystem procedures without having to stop the subsystem. This is accomplished by setting GROUP to <code>Y</code> for the subsystem's procedure file in the subsystem definition, and by specifying a number value for Procs NUMLK that is less than the number of files in the group. The application subsystem locks the procedures in the last (or rightmost) NUMLK number of files, as determined by the right-to-left order they were specified in the <var>CREATE GROUP</var> command that defined the procedure group. For an example, see [[System requirements for Application Subsystems#Subsystem File Use screen|Subsystem File Use screen]].

The multiple procedure file option also allows different users to make changes to procedures in the same subsystem without interfering with each other. The procedure group specified in the subsystem definition must have a corresponding <var>CREATE PERM GROUP</var> definition. However, any individual user can create or open a temporary group with the same name as the subsystem's permanent procedure group. If a user has such a temporary group open and enters a subsystem, the subsystem uses the temporary group instead of the subsystem's permanent group. 

The following restrictions apply to the use of temporary groups to store subsystem procedure files:
<ul>
<li>The user's SCLASS must have the <var>TEST</var> or <var>DEBUG</var> privilege.</li>

<li>The last n files of the <var>CREATE PERM GROUP</var> command (where n is set by the <code>NUMLK</code> parameter) must correspond exactly to the last n files of the <var>CREATE TEMP GROUP</var> command. </li>
</ul>

===Cross-Reference facility===

The Cross-Reference facility is a Dictionary facility that can be invoked from both the Dictionary Main Menu and <var class="product">Model 204</var> command level. It produces reports for users who develop and maintain <var class="product">Model 204</var> User Language procedures.

The output reports show the line numbers where language elements such as labels, functions, images and variable names occur in a specified set of procedures. Elements within subroutines and nested INCLUDEs can also be cross-referenced.

The Cross-Reference Report is produced in batch mode (by a batch job in OS and DOS, by a service machine in CMS). Prior to submitting a cross-reference job, the user can specify:
<ul>
<li>A set of procedures in a procedure file or group</li>

<li>A set of language elements to be cross referenced</li>

<li>Substitute values for User Language global dummy strings</li>

<li>Job-related parameters such as output destination and lines per page
</li>
</ul>

The Cross-Reference facility also includes Preview and Browse functions, which inform the user about the procedures selected for processing.

For a complete description of the Cross-Reference facility, refer to the [[:Category:Dictionary/204#Dictionary/204 topics|Dictionary/204 topics]].

[[Category:SOUL]]

Release notes for Model 204 version 7.8

2019-12-31T22:12:31Z

ELowell: /* New in this release */

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>[[Application_Subsystem_development#Commit_exits|Commit exits]] are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus and TN3270 debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>When execution pauses, the debuggers now [[#Subroutine or method display|display the subroutine or method]] being executed.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumeration values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string will determine truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in Julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same <var>SNAPCTL</var> settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter <var>CUSTOM=11</var> setting no longer requires that a <var>*LOWER</var> command be issued prior to a <var>LOGCTL</var> command (to add or change a password) to preserve mixed case input. Prior to this release, with <var>CUSTOM=11</var> in place, *LOWER had to be issued before a <var>LOGCTL</var> command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname (the owning id for the ONLINE job) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed (previously such a LOGON would have failed). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL. This in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new <var>WEBSOCKET</var> parameter. The WEBSOCKET option can be specified on either the port definition or the JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the <var>WEBSOCKET</var> and <var>NOWEBSOCKET</var> parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value is enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up a maximum of 1024 such requests before dropping any. This increased backlog reduces, or in most cases eliminates, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change is enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of <var>[[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]]</var> input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client was freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of <var>[[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]]</var> has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use <var>[[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]]</var>.

This change is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the <var>NLDAPBUF</var> parameter in CCAIN. See below for details on <var>[[#NLDAPBUF|NLDAPBUF]]</var>.

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==
These enhancements apply to the Janus and TN3270 debuggers.

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. This feature is enabled in V7.7 with the application of zap 77z363.

===Subroutine or method display===
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
The above improvements are enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change is enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===MONITOR IODEV===
This new command displays the total number, the current usage and the maximum number of each IODEV type.
M IODEV 
Iodev Total Active ( % ) Maximum ( % )
1 1 1 100% 1 100%
7 300 100 33% 150 50%
11 4 0 0% 1 25%
15 500 50 10% 80 16%
25 1 0 0% 0 0%
27 10 0 0% 0 0%
29 10 1 10% 1 10%
51 5 0 0% 0 0%

===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

<code>D ECF M</code> displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

<code>D ECF N</code> displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

<code>D ECF U</code> displays details of users currently accessing ECF modules. This is also the default option, and so <code>D ECF</code> will display the same output as <code>D ECF U</code>. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

<code>D ECF <var class="term">function</var> LIKE <var class="term">?</var> </code> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>[[REGENERATE command|REGENERATE]]</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>[[SETGRC command|SETGRC]]</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. <var>ENQTIME</var> can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of <var>ENQTIME</var> is 3000 (3 seconds).

For example, with <code>ENQTIME = 100</code> and <code>ENQRETRY = 7</code>, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The <var>ENQTIME</var> parameter may also be reset with $ResetN.

This new parameter is enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
<var>LFSCB</var>, the length of the full screen buffer, now has a new minimum value of 8 (the previous minimum was 0). This change is enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If <var>SERV4G</var> is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.
===SIRTERM===
The <var>[[SIRTERM parameter|SIRTERM]]</var> (Sirius terminal options) parameter settings have changed.
The changes to <var>SIRTERM</var> allow a user to preclude a reset to a Model that is not supported by the terminal emulator in use.

The X'01' setting (MODEL 6 support) is no longer used.

The X'02' setting (Write Structured Field Query Support) now supports MODEL 6 terminals by default.

The new X'08' setting always issues a Write Structured Field Query for Terminal Model Resets for terminals connected to Model 204 through VTAM or TELNET, provided that X'02' has been set. This precludes Terminal Model RESETs to Models that are not supported by the terminal emulator in use.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. This new parameter is enabled in V7.7 with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need <var>WEBDFLT=1</var>, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use <var>[[MONITOR_command|MONITOR]] SYSTEM STATISTICS</var> to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The <var>[[CUSTOM parameter|CUSTOM=38]]</var> parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the <var>RESET</var> command. This <var>CUSTOM</var> setting is now restricted to the <var>RESET</var> of the <var>LAUDIT</var> parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change is enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the <var>PAGESZ</var> parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of <var>ECPRIV</var>, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The <var>ECPRIV</var> 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the <var>ECPRIV</var> 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the <var>ECFPRIV</var> 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resettable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the <var>ZHPF</var> command without being logged on. From this release onwards, a user must be logged on with system manager privileges in order to issue this command.

Additionally, the command output will now only display results for currently open files.

This change is enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal <var>MODEL</var> parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of <var>LOUTPB</var> necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Application Subsystem development

2019-12-31T22:09:26Z

ELowell: /* Automatic COMMIT */

==Overview==

Although only a system manager can define a subsystem, the determination of a subsystem's options and components typically also involves the file manager and application developer. This page focuses on subsystem facility topics most relevant to the application developer:

The Subsystem Management facility of Dictionary lets you define a collection of procedures to <var class="product">Model 204</var> as a subsystem and to assign certain characteristics to that subsystem. 

===Advantages of subsystems===

The following table summarizes the advantages of subsystems over other [[SOUL]] procedure applications: 
<table>
<tr class="head">
<th>Advantage </th>
<th>Subsystems...</th>
</tr>

<tr>
<td nowrap>Minimal end-user intervention </td>
<td>Require minimal knowledge of <var class="product">Model 204</var>. The end user need not know what files and procedures exist for the application. The subsystem is invoked simply by entering the subsystem name as a <var class="product">Model 204</var> command.</td>
</tr>

<tr>
<td>Driver facility </td>
<td>Eliminate the need for user-written drivers containing conditional INCLUDEs based on a global variable. This driver facility leads to smaller, more modular procedures that are easier to maintain and enhance.</td>
</tr>

<tr>
<td nowrap>Performance improvements </td>
<td>Improve performance by saving and reloading compiled SOUL requests, called precompiled procedures. Depending upon how often precompiled procedures are included, 20-90% of the operating costs of a <var class="product">Model 204</var> application can be saved.</td>
</tr>

<tr>
<td>Error handling facilities </td>
<td>Trap and handle <var class="product">Model 204</var> errors in a single, centralized routine. Each subsystem can have one error procedure that is invoked each time a <var class="product">Model 204</var> error occurs during that subsystem's processing. <var class="product">Model 204</var> provides facilities for determining the type of error that caused the error procedure to be invoked. </td>
</tr>

<tr>
<td>Security facilities </td>
<td>Allow or restrict access to the subsystem. </td>
</tr>

<tr>
<td>Parallel Query Option/204 compatibility </td>
<td>Can be defined to allow referral to remote files and scattered groups.</td>
</tr>
</table>

===Subsystem definition===

The characteristics and components of a subsystem are defined to <var class="product">Model 204</var> by the system manager during a process called subsystem definition. The defined options and components are stored in the system file CCASYS. Once a subsystem has been defined, all Dictionary users can display the options and components through Dictionary. For more information about:
<ul>
<li>Displaying a subsystem definition, see [[System requirements for Application Subsystems#Overview of the Subsystem Management facility|Overview of the Subsystem Management facility]]. </li>

<li>Defining subsystems that refer to remote files and scattered groups, see [[PQO: Scattered APSY subsystems#Client and service subsystems|PQO client and service subsystems]].
</li>
</ul>

==Subsystem design components==

During subsystem definition, the components listed below can be defined. These components impact various aspects of subsystem design. The following table summarizes the required component designations. 
<table>
<tr class="head">
<th>Component </th>
<th>Subsystem design requires designation of...</th>
</tr>

<tr>
<td nowrap>Command line global variable </td>
<td>(Optional) parameter global variable. The parameter global variable allows any parameters specified by a user during a subsystem login to be stored in this variable and retained when control is transferred to another subsystem. </td>
</tr>

<tr>
<td>Communication global variable and exit value </td>
<td>Communication global variable and exit value. The communication global variable is used to transfer control from one procedure to another. The exit value is used to leave the subsystem. Optionally, a reserved global variable is available for transferring control between subsystems. </td>
</tr>

<tr>
<td>Error global variable </td>
<td>Error global variable. If an error occurs while the subsystem is executing, a three-character error code is stored in this variable. This code can then be used by an error procedure to determine the action to be taken by the subsystem. </td>
</tr>

<tr>
<td>Prefix designations </td>
<td>Two prefixes for procedure names. These prefixes allow <var class="product">Model 204</var> to determine whether a procedure can be saved in its compiled form for later evaluation. </td>
</tr>

<tr>
<td>Processing components</td>
<td>Specific procedures for types of special processing. These procedures allow <var class="product">Model 204</var> to determine the flow of control within a subsystem. </td>
</tr>
</table>

==Command line global variable==

A command line global variable allows you to store any parameters specified by an end user during a subsystem login and retain this information when control is transferred to another subsystem. The designation of a command line global variable is optional. 

===Using the command line global variable===

The command line global variable is used in the following manner:
<ul>
<li>A user logs into a subsystem by entering the subsystem name followed by the parameter information. The total length of the parameter information entered by the user can consist of as many as 255 characters. (The portion of the command line reserved for parameter information is discarded if no parameter information is defined.)</li>

<li>The portion of the input following the subsystem name is placed into a command line global variable, which then is available to the application program. For example:
PAYROLL parameter1 parameter2


is the command that logs the current user into the subsystem named PAYROLL. The string parameter1 parameter2 is the subsystem command line and is made available to the application via a global variable. If CMDL is the name assigned to the command line global variable, the following statements:
BEGIN
%CMD.LINE = $GETG('CMDL')
%FIRST.PARM =
$Substr(%CMD.LINE,1,$INDEX(%CMD.LINE,' ')-1)


would assign the contents of the command line used to enter the subsystem to %CMD.LINE and the first parameter of the line to %FIRST.PARM. 
</li>
</ul>

===Transferring control to another subsystem===

The contents of command line global variables are not deleted when control is transferred from one subsystem to another. A request can set the contents of the command line global variable of the destination subsystem before transferring control to that subsystem. The effect is the same as if the parameters were entered on the user's terminal. 

===Impact of the UTABLE command===

The contents of the command line global variable are not deleted by UTABLE commands which normally delete the contents of GTBL, as long as the UTABLE command is issued from within a subsystem. 

==Communication global variable==

===Transferring control===

A communication global variable lets you transfer control at two levels: 
<table>
<tr class="head">
<th>From... </th>
<th>Control is transferred by a...</th>
</tr>

<tr>
<td>One procedure to another </td>
<td>User-designated global variable.</td>
</tr>

<tr>
<td>One subsystem to another </td>
<td>Reserved global variable named XFER. </td>
</tr>
</table>

===Transferring control between procedures===

Subsystem procedures pass control from one to another through the use of the communication global variable. The communication global variable name for a subsystem is specified in the subsystem definition. Each subsystem procedure must set the value of the communication global variable to the name of the next procedure to be executed.

====Example====

For example, the subsystem AUTOS has procedures PRE-MAIN.MENU and PRE-RPT.PGM and the communication global variable NEXT.
PRE-MAIN.MENU is currently executing and wants to pass control to
PRE-RPT.PGM. Before PRE-MAIN.MENU finishes, the function $SETG is used to store procedure name PRE-RPT.PGM in NEXT:
IF $SETG('NEXT','PRE-RPT.PGM') THEN ...


After PRE-MAIN.MENU ends, <var class="product">Model 204</var> examines NEXT and begins executing PRE-RPT.PGM.

====Subsystem exit value====

A subsystem is exited by setting the value of the communication global variable to the subsystem exit value. The exit value for the communication global variable is also specified in the subsystem definition. 

For the AUTOS subsystem used in the preceding example, the exit value of the communication global variable is defined as EXIT. To disconnect the user from the AUTOS subsystem after procedure PRE-RPT.PGM is finished executing, PRE-RPT.PGM assigns the exit value, EXIT, to the communication global variable, NEXT.
IF $SETG('NEXT','EXIT') THEN
.
.
.


===Transferring control between subsystems===

One subsystem can invoke another subsystem by transferring control from itself to another subsystem. To accomplish this, you must perform these steps:
<ol>
<li>Set the communication global variable to the value XFER.</li>
<li>Set the global variable XFER to the name of the subsystem to which control is being passed. </li>
</ol>

When the current procedure finishes executing, <var class="product">Model 204</var> disconnects the user from the old subsystem, transfers control to the new subsystem, and invokes the login procedure for the new subsystem. 

====Design considerations====

You should consider the following factors when coding logic for transferring control between two subsystems:
<ul>
<li>The transfer always invokes the login procedure of the subsystem receiving control. For more information on the login procedure, refer to the discussion [[#Subsystem processing flow|Subsystem processing flow]].</li>

<li>The destination subsystem must be active. The $SUBSYS function should be used to determine if the subsystem to which control is being transferred is active; refer to the discussion on [[#Subsystem procedure control functions|Subsystem procedure control functions]]. If the destination subsystem does not use the automatic start option, (see [[#Operating options|Operating options]]), the subsystem must be started before control is passed. </li>

<li>The destination subsystem should not reset LGTBL if any parameters are passed in global variables. </li>

<li>To return to the original subsystem, a global variable must be set to the name of the original subsystem. The communication global variable and the XFER global variable can then be used with the global variable that stores the subsystem name to return control to the original subsystem.</li>

<li>The destination subsystem can return control to the procedure that the user was in when the user transferred. To do this, the subsystem must save the name of the procedure in a global variable. In addition, the login procedure must contain logic to return control to the procedure that the user was in.</li>

<li>If the transferring subsystem is in test mode (see [[#Security options|Security options]]), the transferring subsystem stops after it passes control. The destination subsystem is not placed in test mode.
</li>
</ul>

====Example====

The following request in procedure PRE-SUB.MENU provides an example of subsystem transfer code. CREDIT and AUTOS are two defined subsystems with the automatic start option. (See [[#Automatic start|Automatic start]].) Subsystem CREDIT transfers control to AUTOS by setting NEXT (the communication global variable) to XFER and the global variable XFER to AUTOS. After the PRE-SUB.MENU procedure ends, the user is connected to AUTOS.
BEGIN
.
.
.
*SELECTION = 4 INDICATES CHOICE OF AUTOS SUBSYSTEM
*
SEL.AUTOS: IF %CREDITMENU:SELECTION = 4 AND -
$SUBSYS('AUTOS') =1 THEN
IF $SETG('XFER','AUTOS') OR -
$SETG('NEXT','XFER') OR -
$SETG('SUBFROM','CREDIT') OR -
$SETG('PROCFROM','PRE-SUB.MENU') THEN
PRINT 'GLOBAL TABLE FULL'
END IF
JUMP TO GET.NEXT
.
.
.


===Coding considerations===
<ul>
<li>Procedures to which control is passed via the communication global variable must be stored in a designated procedure file. The procedure file is the default file for a subsystem application unless the default file is explicitly changed by a DEFAULT command or overridden by an IN clause.</li>

<li>Each procedure must set the communication global variable to indicate the next procedure to be included. If this variable is not set, an error or loop occurs.</li>

<li>To exit the subsystem, the communication global variable must be set to the exit value. Server table sizes and other parameters should be reset to the values existing prior to entering the subsystem so that the user is returned to his/her normal operating environment. Parameter values are restored automatically when the automatic login option is used.
</li>
</ul>

==Error global variable==

The name of the error global variable must be specified in the subsystem definition. Whenever an error is detected that is not trapped by an ON unit, <var class="product">Model 204</var> automatically sets the subsystem's error global variable to a value which indicates the type of error that occurred. 

===Error code values===

The "Error global variable values and reasons" table lists the error global variable values and their corresponding causes. Correct the cause of the error, and/or change your error procedure as discussed in [[#Error procedures|Error procedures]]. 
<table>
<caption>Error global variable values and reasons</caption>
<tr class="head">
<th>Error code</th>
<th>Reason</th>
</tr>

<tr>
<td>ATN </td>
<td>User pressed attention</td>
</tr>

<tr>
<td>BUG </td>
<td>Evaluation errors</td>
</tr>

<tr>
<td>CAN</td>
<td>Request evaluation canceled due to invalid terminal I/O in error procedure after BUMP or inactive thread time out.</td>
</tr>

<tr>
<td>CNT </td>
<td>Counting errors</td>
</tr>

<tr>
<td>FIL - BROKEN </td>
<td>Referenced file is not initialized, full, or physically inconsistent. Check the audit trail to determine the condition of the file. </td>
</tr>

<tr>
<td>FIL - NOT OPEN </td>
<td>Referenced file not open</td>
</tr>

<tr>
<td>GRP - FTBL </td>
<td>FTBL too small</td>
</tr>

<tr>
<td>GRP - NOT OPEN </td>
<td>Group not open</td>
</tr>

<tr>
<td>GRP - TEMP FIELD </td>
<td>TEMP group field has wrong type (see [[#Restrictions for temporary and ad hoc groups in precompiled procedures|Restrictions for temporary and ad hoc groups in precompiled procedures]])</td>
</tr>

<tr>
<td nowrap>GRP - TEMP MISMATCH </td>
<td>TEMP group has wrong type</td>
</tr>

<tr>
<td>INCLUDE MAX</td>
<td>Maximum iterations value has been exceeded.</td>
</tr>

<tr>
<td>HNG </td>
<td>Phone hung up, connection lost</td>
</tr>

<tr>
<td>HRD </td>
<td>Hard restart</td>
</tr>

<tr>
<td>REC </td>
<td>Record locking table filled up during the load of a
precompiled request</td>
</tr>

<tr>
<td>RFR</td>
<td>After several tries, an APSY failed to invoke a procedure, because the procedure is in the process of being refreshed.</td>
</tr>

<tr>
<td>SFT </td>
<td>Soft restart</td>
</tr>

<tr>
<td>TBL - FSCB </td>
<td>FSCB too small</td>
</tr>

<tr>
<td>TBL - NTBL </td>
<td>NTBL too small</td>
</tr>

<tr>
<td>TBL - QTBL </td>
<td>QTBL too small</td>
</tr>

<tr>
<td>TBL - STBL </td>
<td>STBL too small</td>
</tr>

<tr>
<td>TBL - VTBL </td>
<td>VTBL too small</td>
</tr>
</table>

===Error procedures===

An error procedure must test for different error conditions. The resulting value stored in the error global variable helps the application programmer determine the type of error that occurred.
<ul>
<li>For all error codes except ATN, the error procedure should avoid re-executing the procedure that caused the error; otherwise, the error recurs. </li>

<li>In most cases, the error procedure should display an informational message and set the global communication variable to the exit value. </li>

<li>If a HNG error code is indicated, all terminal I/O (such as PRINT, READ) is ignored. </li>

<li>If a HNG, HRD, or SFT error code is indicated, no terminal I/O (such as PRINT or READ) should be attempted. Instead, send a message to the audit trail in an AUDIT statement that indicates the error code encountered.
</li>
</ul>

====Considerations for the communications global variable====

The communications global variable is ignored and disconnect processing completed when one of the following conditions occurs:
<ul>
<li>Error is a soft restart, a hard restart, or a phone hang-up condition.

If you attempt to set the communications global variable to the name of another procedure, the procedure is not executed.
</li>

<li>No error procedure is specified in the subsystem definition.
</li>
</ul>

An example illustrating how a subsystem error procedure can test for different error conditions is provided in [[#Error procedure|Error procedure]]. 

==Precompiled and non-precompiled procedures==

You can use two types of procedures in a subsystem: 
<ul>
<li>Precompiled procedure

The first time a precompilable procedure is invoked after a subsystem starts, it is compiled and stored for re-use. Because the compiler phase is bypassed each subsequent time the procedure is invoked (except as noted below), precompilation saves both CPU and elapsed time. Exceptions include the following:
<ul>
<li>The procedure is recompiled the first time it is invoked for each SCLASS. The new compilation is evaluated, then discarded. It does not replace the original stored compilation. </li>
<li>Further recompilations might be required due to temporary group differences. See [[#Recompiling precompiled procedures|Recompiling precompiled procedures]] for more on this. </li>
</ul></li>

<li>Non-precompiled procedure

A non-precompiled procedure is compiled each time it is invoked.</li>
</ul>

All procedures, whether precompiled or not, are invoked using the communication global variable.

===Defining prefixes===

During subsystem definition, two prefixes must be defined. The first prefix identifies precompiled procedures; the second identifies non-precompiled procedures. All procedures that are included for the subsystem through the use of the communication global variable (such as the login and main processing procedures) must have names that begin with one of these prefixes.

===Contents of subsystem procedures===

Subsystem procedures can contain <var class="product">Model 204</var> commands, a request, multiple requests, continued requests, sections of User Language code (for example, subroutines), or any combination thereof. However, the form of the procedure affects whether the procedure can be precompiled and should be taken into account when the subsystem is designed. Restrictions for precompiled procedures are discussed in detail below.

===Shared versions of precompiled procedures===

Server I/O can be reduced by allowing users executing shared precompiled procedures to use a shared version of QTBL.
See [[Performance monitoring and tuning#Resident Request feature for precompiled procedures|Resident Request feature for precompiled procedures]]. 

===Restrictions for precompiled procedures===

<var class="product">Model 204</var> must ensure that all of the code compiled and saved for a request with the precompiled prefix is consistent for all loading users. To achieve consistency, <var class="product">Model 204</var> restricts the way in which certain features are used. 

Note the following restrictions for precompiled procedures when designing subsystem procedures:
<ul>
<li>Procedures must contain exactly one request. The last statement must be END or END MORE.</li>

<li>Requests cannot start with MORE.</li>

<li>Procedures that include multiple BEGIN/END blocks are not eligible for precompilation.</li>

<li>Requests must not refer to files or permanent groups that are not mentioned in the subsystem definition.</li>

<li>Precompiled procedures can contain the User Language INCLUDE statement. The included procedures must be from a subsystem file. Any code inserted as a result of an INCLUDE statement is subject to all the restrictions for precompiled procedures. </li>

<li>If a precompiled procedure issues the INCLUDE command to compile and run a User Language request, the INCLUDE command is saved, not the compilation of the request that was included.</li>

<li>Compiler table sizes must be the same each time a precompiled procedure is invoked. The UTABLE command should be used carefully.</li>

<li>Dummy strings (??, ?$, ?&) in precompiled procedures are resolved only during compilation for the first user.</li>

<li>Dummy string substitution does not take place when saving commands that contain dummy strings. Instead, when the saved commands are loaded and executed, the current value of the dummy string is used. For example, if you include the following command in a precompiled procedure, whatever is currently in the global COMMAND is executed.
?%COMMAND
</li>

<li>If a subsystem file is referenced by a precompiled procedure, no user can RESTORE or INITIALIZE the file, or RENAME, DELETE, or REDEFINE a field while the subsystem is active.</li>

<li>Procedures in UNLOCKed members of a PROCFILE GROUP are not precompiled.
</li>
</ul>

===Restrictions for temporary and ad hoc groups in precompiled procedures===

Precompiled requests can refer to temporary or ad hoc groups as long as the files making up the group are specified in the subsystem definition. A temporary group of the same name must have the same composition characteristics for all loading users, as described below. If this condition is not met, <var class="product">Model 204</var> sets the error global variable to GRP-TEMP MISMATCH (see [[#Error global variable|Error global variable]]).
<ul>
<li>The temporary group for all loading users must be the same type. <var class="product">Model 204</var> assigns a type, based on the following file conditions:
<ul>
<li>Some files have record security.</li>
<li>All files are sorted or all are hashed.</li>
<li>The sort or hash key has the same name in all files. </li>
</ul></li>

<li>Fields of the same name in the temporary group must be of the same type. Each field referenced in a temporary group each time a precompiled procedure is invoked must be found in a file. If this condition is not met, <var class="product">Model 204</var> sets the error global variable to GRP-TEMP FIELD (see [[#Error global variable|Error global variable]]).

Field definition attributes can change for fields in temporary groups between compile and loading time. The following changes are allowed:
<ul>
<li>If the field is NON-CODED in any file at compile time, it can be CODED in all files at loading time.</li>
<li>If the field is BINARY or FLOAT in any file at compile time, it can be STRING in all files at loading time.</li>
<li>If the field is non-NUMERIC RANGE in any file at compile time, the field can be NUMERIC RANGE in all of the files at loading time.</li>
</ul></li>
</ul>

===Recompiling precompiled procedures===

When designing applications which use precompiled procedures and temporary groups, be aware that temporary groups can cause <var class="product">Model 204</var> to recompile precompiled procedures under certain conditions. 

Precompiled procedures are recompiled when the request references a temporary group and the:
<ul>
<li>Compiling user's temporary group consists of files which are smaller than one or more of the files in the loading user's temporary group of the same name.</li>

<li>Compiling user's temporary group has fewer files than the loading user's temporary group of the same name. </li>

<li>Update and retrieve privileges do not match those of the compiling user's temporary group (of the same name).
</li>
</ul>

If one user's temporary group contains one large file, and another user's temporary group contains a number of smaller files, it is possible that a precompiled procedure is recompiled every time it is invoked. To prevent constant recompiling when files are of different sizes, compile temporary groups originally with the largest files and the greatest number files you expect to be included in the temporary group.

If, despite precautions, <var class="product">Model 204</var> must discard and recompile a precompiled procedure, the loading user must have exclusive access to that procedure: no other user can be executing the procedure within the same subsystem. If another user is executing the procedure, the loading user recompiles a private copy of the procedure. <var class="product">Model 204</var> discards the private copy when execution has completed. 

===Procedure compilation and Parallel Query Option/204===

When a non-precompiled procedure that references remote files is invoked, one or more remote nodes participate in the compilation and evaluation. When a precompiled procedure is invoked, <var class="product">Model 204</var> loads the procedure on each of the nodes that participated in the original compilation.

When a subsystem member becomes unavailable during evaluation, the appropriate ON unit is activated. 

Errors which occur while loading a remote procedure produce error messages which have the prefix RMT in the global error variable.

====Saving compilations====

As part of the compilation process, a list of remote nodes referenced in the request is generated with the compiled code. When compilation is complete, the compilation is saved along with the list of nodes. Each remote node referenced in the request is sent a signal to save the compilation. 

If for any reason a compilation cannot be saved by a server node, the entire save operation fails.

====Loading saved compilations====

At the client node, the saved remote node reference list is checked to see which nodes are loading the request. When the request is loaded on the client, a signal is transmitted to each referenced server node to load the compilation. 

====New and missing nodes====

A temporary group can be changed so that a node is new (not previously referenced) or missing (referenced but no longer available). [[#New and missing nodes|Temporary groups with new and missing nodes]] shows how new and missing nodes affect recompilations and saves. 
<table>
<caption>Temporary groups with new and missing nodes</caption>
<tr class="head">
<th> </th>
<th>If there are
missing nodes...</th>
<th>If there are no
missing nodes....</th>
</tr>

<tr>
<td>And there are new nodes...</td>
<td>Recompile the procedure, do not save</td>
<td>Recompile and save again</td>
</tr>

<tr>
<td>And there are no new nodes...</td>
<td>Just load and evaluate</td>
<td>Just load and evaluate</td>
</tr>
</table>

====Recompiling saved requests====

Saved requests are always recompiled if a new node is introduced into a temporary group. Recompilation can cause a noticeable delay in response time.

In addition, the following changes in the composition of a subgroup also force recompilation of a request. A subgroup is the group of files at a server node referenced as a part of a group.

<var class="product">Model 204</var> recompiles saved requests when:
<ul>
<li>The number of files in the subgroup has increased (for example, if a user's request includes a file that was unavailable to the previous user)</li>

<li>The maximum number of segments in a subgroup has increased
</li>
</ul>

==Subsystem procedures==

===Types of subsystem procedures===

Subsystem development involves writing the collection of procedures that make up a subsystem. Subsystem procedures can be categorized as one of four types: 
<table>
<tr class="head">
<th>Procedure category </th>
<th>Performs...</th>
</tr>

<tr>
<td><var>Initialization</var> </td>
<td>Specified operations each time the subsystem is initialized.</td>
</tr>

<tr>
<td><var>Login</var> </td>
<td>As the entry point for each user of the subsystem.</td>
</tr>

<tr>
<td><var>Main processing</var> </td>
<td>Specific tasks of the subsystem.</td>
</tr>

<tr>
<td><var>Error</var> </td>
<td>Error handling. </td>
</tr>
</table>

===Guidelines and restrictions===
<ul>
<li>Procedures should be small and modular.</li>

<li>Included procedures normally are included by using the INCLUDE command. Included procedures cannot be precompiled.</li>

<li>Non-subsystem files can be opened and referenced only by non precompiled procedures.</li>

<li>If a subsystem file is referenced by a precompiled procedure, no user can RESTORE or INITIALIZE the file, or RENAME, DELETE, or REDEFINE a field while the subsystem is active.</li>

<li>A subsystem procedure cannot issue the CREATE command for a subsystem file.</li>

<li>LXTBL and LFTBL cannot be reset from within a subsystem procedure.</li>

<li>All DO YOU REALLY WANT TO messages are suppressed and the default action is assumed. The default action for each type of message is listed in [[M204.1076]].

If you do not wish the default action to be executed, statements to handle a situation that would invoke the message should be added to the procedure. 
</li>
</ul>

===Initialization procedure===

The initialization procedure stores instructions for tasks you need to perform each time the subsystem is initialized. An example of such a task is the initialization of a particular work file. 

The initialization procedure is optional. If a subsystem uses an initialization procedure, the procedure name must be specified in the subsystem definition.

===Login procedure===

The login procedure performs the start up for each user of an application. Every time a user invokes the subsystem, <var class="product">Model 204</var> automatically includes the subsystem login procedure. 

The login procedure name must be specified in the subsystem definition. 

Typically, the login procedure is used to store current server table sizes in the global variable table for later reference, issue UTABLE commands to set compiler table sizes for the subsystem, and set the communication global variable to the name of the procedure that displays an initial menu. 
Example

Here is a sample login procedure:
CLEARG
BEGIN
IF $SETG('NTBL',$VIEW('LNTBL')) OR -
$SETG('VTBL',$VIEW('LVTBL')) OR -
$SETG('QTBL',$VIEW('LQTBL')) OR -
$SETG('STBL',$VIEW('LSTBL')) OR -
$SETG('FSCB',$VIEW('LFSCB')) OR -
$SETG('LECHO',$VIEW('LECHO')) OR -
$SETG('NEXT','PRE-MAIN.MENU') THEN
PRINT 'GTBL FULL'
END IF
END
UTABLE LNTBL=450,LQTBL=2300,LVTBL=600,LSTBL=3300
UTABLE LFSCB=5000
RESET LECHO 0


===Main processing procedures===

Main processing procedures perform the specific tasks of the subsystem. There can be as few or as many main processing procedures as necessary for the subsystem to perform its tasks. Main processing procedures are not specified in the subsystem definition. However, each procedure must follow the procedure naming conventions and subsystem coding rules discussed on this page. 

====Example====

Here is a sample procedure:
BEGIN
MENU MAINMENU
TITLE 'AUTO INSURANCE SYSTEM (MAIN MENU)' AT 10 BRIGHT
MAX PFKEY 12
SKIP 5 LINES
PROMPT 'MAINTENANCE' AT 10 BRIGHT
SKIP 2 LINES
PROMPT 'REPORTING' AT 10 BRIGHT
SKIP 2 LINES
PROMPT 'EXIT' AT 10 BRIGHT
END MENU
%NEXT = 'X'
REPEAT WHILE %NEXT = 'X'
READ MAINMENU
IF %MAINMENU:SELECTION = '1' THEN
%NEXT = 'PRE-MAINT.PGM'
ELSEIF %MAINMENU:SELECTION = '2' THEN
%NEXT = 'PRE-RPT.PGM'
ELSE %NEXT = 'NON-FINISH'
END IF
END REPEAT
CHK.GTAB: IF $SETG('NEXT',%NEXT) THEN
AUDIT 'GLOBAL TABLE FULL - "NEXT"'
END IF
END


===Error procedure===

An error procedure, which is optional, performs error handling. This procedure is invoked when a condition occurs that cannot be trapped by the executing procedure (for example, a compiler error or an attention with no ON ATTENTION unit coded). An error procedure tests for different error conditions and determines the next procedure to execute, based on the error code value stored in the error global variable. Terminal I/O in a subsystem error procedure following a BUMP or inactive thread timeout results in cancellation of the procedure. 

====Example====

The following error procedure assumes that the error global variable name is ERRCLASS, the communication global variable name is NEXT, and the exit value of the communication global variable is EXIT.
PROCEDURE SYS-ERROR
BEGIN
*
* GET THE VALUE OF THE ERROR CLASS GLOBAL VARIABLE
*
GET.VALUE: %ERRORCODE = $GETG('ERRCLASS')
*
* IF THE USER HIT ATTENTION, INCLUDE THE MAIN MENU SCREEN
*
IF.ERROR: IF %ERRORCODE = 'ATN' THEN
%NEXT = 'SYS-MAIN-MENU'
*
* IF PHONE WAS HUNG UP, OR ANY KIND OF RESTART, THEN AUDIT
* MESSAGE AND EXIT. DO NOT ATTEMPT ANY TERMINAL I/O
* SINCE USER IS NO LONGER CONNECTED.
*
ELSEIF %ERRORCODE = 'HNG' OR -
%ERRORCODE = 'SFT' OR -
%ERRORCODE = 'HRD' THEN
AUDIT 'SUBSYSTEM ERROR CODE: ' -
WITH %ERRORCODE
%NEXT = 'EXIT'
*
* CHECK FOR BROKEN FILE
*
ELSEIF %ERRORCODE = 'FIL - BROKEN' THEN
PRINT ' SUBSYSTEM FILE IS BROKEN'
PRINT ' CONTACT YOUR FILE MANAGER '
%NEXT = 'EXIT'
*
* SOME UNACCOUNTABLE ERROR HAS OCCURRED, SET EXIT
* ROUTINE, AND EXIT WITHOUT DOING ANY TERMINAL I/O.
*
ELSE
AUDIT 'NOT ACCOUNTED FOR SUBSYSTEM ERROR CODE: ' -
WITH %ERRORCODE
%NEXT = 'EXIT'
END IF IF.ERROR
*
* SET COMMUNICATIONS VARIABLE TO EXIT VALUE
*
COMM.VAR: IF $SETG('NEXT',%NEXT) THEN
AUDIT 'GTBL full in SYS-ERROR trying to set NEXT to ' WITH %NEXT
PRINT 'GTBL FULL'
END IF
END.REQUEST: *
END
END PROCEDURE


==Security options==

During subsystem definition, various options are specified for a subsystem. Security options determine subsystem command and file and group privileges assigned to a user. 

You can also specify system operation options during subsystem definition. System operation options are discussed in the [[#Operating options|Operating options]] section.
For a detailed discussion of subsystem definition options, refer to [[System requirements for Application Subsystems]]. 

===Status of subsystem===

The status of the subsystem affects the type of subsystem security that is implemented. The subsystem can have one of three status settings: 
<table>
<tr class="head">
<th>Status setting </th>
<th>Allows access to...</th>
</tr>

<tr>
<td>Public </td>
<td>All users. All users who enter a public subsystem are assigned to the single subsystem user class and have the same set of privileges. </td>
</tr>

<tr>
<td>Semipublic </td>
<td>All users but permits different privileges to be assigned for each user. In a semipublic subsystem, one subsystem user class can be defined as the default class for all users not specifically assigned to another subsystem user class. </td>
</tr>

<tr>
<td>Private </td>
<td>Only to specified users. Using a private subsystem prevents any unauthorized entry into the subsystem. All users who are allowed access must be assigned to one of the defined user classes. Unlike a semipublic subsystem, a private subsystem has no default user class. </td>
</tr>
</table>

===User class===

The set of privileges assigned to a user is based on the user's subsystem user class or SCLASS. The SCLASS is used by <var class="product">Model 204</var> to determine the privileges assigned for each file and group in the subsystem when files are opened for the user. File and group privileges must be specified in the subsystem definition because <var class="product">Model 204</var> bypasses <var>OPENCTL</var> parameter settings and file passwords when opening subsystem files and groups for each user. Whenever the user invokes the subsystem, he/she is assigned the file and group privileges of that subsystem user class. 

The SCLASS also determines whether or not the user can issue any of the subsystem control commands listed below. If <var class="product">Model 204</var> discovers that the user does not have the correct privileges to issue a command, an error message is displayed.
<table>
<tr class="head">
<th>Subsystem control commands </th>
<th>Directs Model 204 to...</th>
</tr>

<tr>
<td><var>DEBUG SUBSYSTEM</var> </td>
<td>Establish a test environment for a multiuser version of the <var>TEST</var> command extension. The subsystem does not have to be stopped to issue the <var>DEBUG</var> command.

When a user enters a subsystem in <var>TEST</var> or <var>DEBUG</var> mode, the user's MSGCTL parameter setting is not changed. All error and informational messages that are not suppressed by the user's <var>MSGCTL</var> setting are displayed on the user's terminal. 
</td>
</tr>

<tr>
<td><var>START SUBSYSTEM</var> </td>
<td>Activate the subsystem and make it available for use. If the subsystem is inactive when the <var>START</var> command is issued, <var class="product">Model 204</var> opens all the subsystem files and includes the subsystem initialization procedure. </td>
</tr>

<tr>
<td><var>STOP SUBSYSTEM</var> </td>
<td>Stop the subsystem and make it unavailable for use. Once a subsystem is stopped and all users have exited, then all locking and storage resources held by the subsystem are released and all the subsystem files and groups are closed. </td>
</tr>

<tr>
<td><var>TEST</var> </td>
<td>Establish a single user test environment. The <var>TEST</var> command is extended to <var>TEST DEBUG SUBSYSTEM</var>. The subsystem must be stopped to enter <var>TEST</var> mode.</td></tr>
</table>

Note: Several aspects of <var>START SUBSYSTEM</var> and <var>STOP SUBSYSTEM</var> processing are unique to distributed applications. For a discussion, see [[PQO: Scattered APSY subsystems#Subsystem command processing|Subsystem command processing]].

===Processing of security violations===

The application subsystem traps security violations that occur while a user is running in a subsystem. File read and update security violations, procedure security violations, and field level security violations are interpreted as compilation or evaluation errors in the error global variable. The audit trail messages produced when the error occurred can be examined in order to identify a compilation or evaluation error as a security violation. 

===Compiling procedures with a different SCLASS===

In the following situation, <var class="product">Model 204</var> saves User 1's compilation:
<ol>
<li>There are multiple SCLASSes for a subsystem.</li>
<li>User 1 saves a procedure under SCLASS 1.</li>
<li>User 2, under SCLASS 2, recompiles the procedure.</li>
<li>User 2's global variables contain different information from User 1's so User 2 tries to open different files or groups than User 1. </li>
</ol>

However, User 2's compilation is not saved: User 2 receives an error message:
M204.0468: COMPILATION NOT SAVED - reason


==Operating options==

Operating options affect certain aspects of the overall behavior of a subsystem. Operating options are distinct from security options, which are discussed in [[#Security options|Security options]].
Subsystem options are also discussed in [[System requirements for Application Subsystems]]. 

The following table lists the operating options and what they determine.
<table>
<tr class="head">
<th>Operating option </th>
<th>Determines whether...</th>
</tr>

<tr>
<td>Automatic start </td>
<td>Subsystem automatically starts for the first user entering the subsystem. </td>
</tr>

<tr>
<td>Locking files and groups for subsystem use </td>
<td>Users from outside the subsystem can open and update subsystem files while the subsystem is active. </td>
</tr>

<tr>
<td>Automatic login </td>
<td>Users are automatically logged into <var class="product">Model 204</var> upon entering a subsystem. </td>
</tr>

<tr>
<td>Automatic logout </td>
<td>Users are automatically logged out of <var class="product">Model 204</var> upon exiting a subsystem. </td>
</tr>

<tr>
<td>Automatic COMMIT </td>
<td>Any outstanding updates are committed automatically whenever a subsystem procedure ends and transfers control using the communications global variable. </td>
</tr>

<tr>
<td>Message displays </td>
<td>Disconnect, informational, and error messages are displayed for subsystem users. </td>
</tr>

<tr>
<td>File usage </td>
<td>Subsystem can run when one or more files used by the subsystem are unavailable for use. </td>
</tr>
</table>

===Automatic start===

If the automatic start option is selected, <var class="product">Model 204</var> invokes subsystem initialization when the first user attempts to enter the subsystem. The subsystem can be used without a privileged user first issuing the START SUBSYSTEM command.

If the automatic start option is not selected, subsystem initialization occurs only when the START SUBSYSTEM command is issued. The subsystem is then available for use. 

===Locking files and groups for subsystem use===

If the locking files and groups option is selected, <var class="product">Model 204</var> prevents users that are not running in the subsystem from opening any of the subsystem files or groups while the subsystem is active. 

If the locking files and groups option is not selected, users from outside the subsystem can retrieve, modify, or delete records in a subsystem file while the subsystem is active. 

===Automatic login===

If the automatic login option is selected, <var class="product">Model 204</var> logs on the user when the user enters a subsystem. The user is logged in using the subsystem name as the <var class="product">Model 204</var> user ID. If the user already has logged into <var class="product">Model 204</var> before entering the subsystem, <var class="product">Model 204</var> first closes all the user's files and logs out the user. 

The LOGOUT operations that occur as a result of Automatic Login (both at subsystem Login and Disconnect) ignore the SYSOPT=8 (DISCONNECT on LOGOUT) option.

If the login option is not selected, the user's <var class="product">Model 204</var> user ID is used during subsystem processing. 

===Automatic logout===

If the automatic logout option is selected, the user is logged out of <var class="product">Model 204</var> upon exiting the subsystem. This option is particularly useful when combined with the automatic disconnect feature of <var class="product">Model 204</var>. 

The START SUBSYSTEM command ignores the SYSOPT=8 option for the Automatic Logout subsystem.

If the automatic logout option is not selected, <var class="product">Model 204</var> logs the user out of the subsystem in one of three ways:
<ul>
<li>If the user was previously logged into <var class="product">Model 204</var>, <var class="product">Model 204</var> restores the user's original user ID and returns the user to the <var class="product">Model 204</var> command environment.</li>

<li>If the user was not previously logged into <var class="product">Model 204</var>, the user is logged out of <var class="product">Model 204</var>.</li>

<li>The SYSOPT=8 option causes the user to be disconnected from <var class="product">Model 204</var>.
</li>
</ul>

===Automatic COMMIT===

If the automatic COMMIT option is selected, <var class="product">Model 204</var> automatically issues a COMMIT statement for any outstanding updates whenever a subsystem procedure terminates and transfers control using the communication global variable. If the COMMIT option is not selected, the application must issue the COMMIT statement to commit any pending updates. 
===Commit exits===
Note: This feature is available as of Model 204 release 7.8.
A commit exit enables you to set up SOUL code to run at commit time, as in: "on commit run <var class="term">xxx</var>".

When the user executes a commit (or an implied commit), the APSY specified by <var>COMMITX</var> is driven on a transactional daemon.

The APSY follows standard APSY rules. The commit exit is only driven once; that is, subsequent commits do not call the APSY. The commit exit is only driven for TBO transactions.

A commit/backout coded inside the commit exit commits/backs out the active transaction. Any new transaction within the exit causes a new update unit to begin.

====COMMITX parameter====
The commit exit runs within the APSY defined by the <var>COMMITX</var> parameter and uses normal APSY processing.

The new parameter <var>COMMITX</var> is settable from User 0's parameter line or by the system manager. It can be reset at any time by the system manager.

Setting/Resetting the parameter sends a DYRWT message to the issuer and requires a Yes or No response (unless set/reset by user0).

If <var>COMMITX</var> is specified, all APSY subsystems participate by default but any can be exempted.

====Activating the commit exit APSY====
<ul>
<li>To activate the commit exit APSY, issue:
Reset COMMITX <var class="term">apsyname</var>
where <var class="term">apsyname</var> is the APSY where you are running the commit exit.
Enter <code>Yes</code> at the confirmation prompt.</li>
<li>To exempt any APSY subsystem:
<ol>
<li>Pull up the SUBSYSMGMT <var>Operational Parameters</var> screen for that subsystem.</li>
<li>At the 'Subsystem supports commit exit' item, enter <code>N</code>.</li>
</ol>
</li>

<li>To deactivate the commit exit APSY, issue:
Reset COMMITX
Enter <code>Yes</code> at the confirmation prompt.
</li>
</ul>

====Examples====

The following are examples of login exits which print all changed records.
=====Example 1=====
b
%d object xmldoc auto new
%rec object xmldoc auto new
%d:loadchangedrecords
%f string len 8
%r float
%c float initial(1)
repeat %d:selectcount('//Record') times
%f = %d:value('//Record[' %c ']/@file')
%r = %d:value('//Record[' %c ']/@number')
%c = %c + 1
%rec:loadfromrecord(FILE=%f,RECORDNUMBER=%r)
%rec:print
%rec = new
end repeat
if $SETG('NEXT','EXIT') then
audit 'gtbl full'
end if
end 

=====Example 2=====
b
%d object xmldoc auto new
%d:loadchangedrecords(fields=true)
%d:print
if $SETG('NEXT','EXIT') then
audit 'gtbl full'
end if
end 

=====Example 3=====
b
%d object xmldoc auto new
%recs object xmldoc auto new
%n object xmlnode
%d:loadchangedrecords
%f string len 8
%r float
%c float initial(1)
%n = %recs:AddElement('ChangedRecords')
repeat %d:selectcount('//Record') times
%f = %d:value('//Record[' %c ']/@file')
%r = %d:value('//Record[' %c ']/@number')
%c = %c + 1
%n:loadfromrecord(FILE=%f,RECORDNUMBER=%r,HEADER=TRUE)
end repeat
%recs:print
if $SETG('NEXT','EXIT') then
audit 'gtbl full'
end if
end 

There are new parameters for several of the methods (as demonstrated above):
LoadChangedRecords:
Fields=boolean (default=false)

If true, each individual changed record is loaded into the XMLDOC similar to LoadFromRecord.

LoadFromRecord:
File=name
RecordNumber=number 

LoadFrom Record must normally be issued within a FOR record context. However, if both of these name required parameters are specified, the LoadFromRecord statement need not be within a FOR record context.

If either of these name required parameters is specified from within a FOR record context, an error message will be issued: <code>ERROR 1081: %C inside record loop: Recordnumber/File parameters not allowed</code>

LoadFromRecord:
Header=Boolean (default=false)

If true, the header line of the method will be included for each item. This may be useful when LoadFromRecord is issued in order to load an XMLNODE.

The header will separate each record and designate the file and record number.

====Error handling====

=====Current behavior without commit exits=====

Without commit exits, an APSY does not commit automatically unless AUTOCOMMIT=Y is specified in the APSY definition.
<ul>
<li>If a transactional daemon is created:
Commit/backout must be explicitly specified within a daemon in order to effect the master’s transaction.
Implicit commit on the daemon is never done. Normal end of the daemon does not affect the master.
If the daemon procedure is cancelled, the master transaction is backed out.
If the daemon procedure is abended, the master transaction is backed out and the APSY error proc is run on the master.</li>

<li>If a non-transactional daemon is created:
The master transaction is unaffected by the daemon.
Both implicit and explicit commit affect the daemon transaction only.
If the daemon procedure is cancelled, only the daemon transaction is backed out.
If the daemon procedure is abended, both the daemon and master transaction are backed out and the APSY error proc is run on the master.</li>
</ul>

Each time that an APSY loads a new procedure, the various KSERRC flags are always cleared. So when an error procedure is called, the error flags are always zero.

=====With commit exits=====

With the commit exits feature, the commit exit essentially runs as a transactional daemon with the original user being a pseudo master. Lower level daemons follow normal daemon behavior.
If a commit exit is running, and the APSY fails, the APSY error exit is scheduled to run. If the APSY error exit exists, the original transaction unit will be unaffected, unless the exit specifically designates a commit/backout. If there is no APSY error exit, the original transaction unit is aborted with <code>ERROR 2971: Action disabled by commit exit</code> and the user is restarted.

===Message displays===

<var class="product">Model 204</var> provides these message display options for subsystem users: 
<ul>
<li>Disconnect message display</li>

<li><var class="product">Model 204</var> informational message display</li>

<li><var class="product">Model 204</var> error message display
</li>
</ul>

When a message display option is selected, messages of that type are displayed on the user's terminal. If a message display option is not selected, all messages of that type are not displayed on the user's terminal. Note that if the display of any <var class="product">Model 204</var> type message is suppressed, messages for the corresponding type are not displayed on the user's terminal, but are written to the audit trail file (CCAAUDIT).

Typically, subsystem applications are written so that all messages displayed on the user's terminal are produced by the subsystem and <var class="product">Model 204</var> messages are suppressed. 

===File usage===
====Mandatory vs. optional members====

Files and permanent groups contained within the subsystem definition can be designated as mandatory (the default) or optional members of the subsystem: 
<ul>
<li>Mandatory members

Mandatory files or groups are automatically opened by <var class="product">Model 204</var> when a user logs into a subsystem and automatically closed when the user leaves the subsystem. Subsystem requests can assume that all mandatory files are open and that they are physically consistent. The user's file privileges are those defined in the subsystem definition for the current user's SCLASS. The opening of a mandatory member cannot be prevented by the subsystem administrator with the <var>STOP FILE</var> command when the subsystem is active. A mandatory member cannot be accessed by another copy of <var class="product">Model 204</var> until the entire subsystem is stopped.

If a subsystem procedure issues an <var>OPEN</var> or <var>CLOSE</var> command for a mandatory member, the command is ignored by <var class="product">Model 204</var> and the user's current privileges are not changed.</li>

<li>Optional members

Optional files or groups provide the ability for a file or group to be stopped by a subsystem administrator (using the <var>STOP FILE</var> command) without stopping the entire subsystem. If a member is defined as optional, it is not automatically opened during the subsystem login. It must be opened by the application by using an OPEN/OPENC statement or command. The file privileges assigned are those specified in the subsystem definition for the current user's SCLASS. The member is closed (for that user only) when the user leaves the subsystem if a <var>CLOSE</var> command has not been issued.

When an optional member is not in use, it can be processed by another copy of <var class="product">Model 204</var>. </li>
</ul>

Requests that reference mandatory or optional members can be precompiled. Files not contained in the subsystem definition can be opened and referenced within a subsystem application, but the requests that reference those files cannot be precompiled. 

====Automatic vs. manual members====

Subsystem files and permanent group members can also be designated automatic or manual:
<ul>
<li>An automatic member is a subsystem group or file that is opened automatically when the subsystem is started or when a user enters the subsystem. </li>

<li>A manual member is a group or file that must be opened explicitly by the OPEN or OPENC command.
</li>
</ul>

Mandatory files cannot be designated manual. Optional files can be designated either automatic or manual.

====Permanent vs. temporary groups in subsystem definitions====

The GROUP parameter of the subsystem definition applies only to permanent groups. Temporary group names cannot be used. To include temporary group members in a subsystem definition, and thus to enable their use in precompiled code, the members of the temporary group should be individually specified in the subsystem definition.

====Summary of file definition options====

[[#Summary of file definition options|Subsystem file definition options]] summarizes the subsystem file definition options. 
<table>
<caption>Subsystem file definition options</caption>
<tr class="head">
<th>Subsystem definition option</th>
<th>Automatic
open and close?</th>
<th>
Pre-compiled code?</th>
<th>Start/stop file command allowed?</th>
<th>File privileges assigned</th>
</tr>

<tr>
<td>Mandatory</td>
<td>Must be automatic</td>
<td>Yes</td>
<td>No</td>
<td>SCLASS</td>
</tr>

<tr>
<td>Optional</td>
<td>Can be automatic or manual</td>
<td>Yes</td>
<td>Yes</td>
<td>SCLASS</td>
</tr>

<tr>
<td>None</td>
<td>Cannot be
automatic</td>
<td>No</td>
<td>Yes</td>
<td>File Password</td>
</tr>
</table>

==Subsystem processing flow==

To design a subsystem, you must be familiar with the flow of control that occurs during subsystem processing. Subsystem processing typically involves the following phases:
<table>
<tr class="head">
<th>Type of processing </th>
<th>During this processing...</th>
</tr>

<tr>
<td>Initialization </td>
<td>Subsystem is started and an optional initialization procedure is included. </td>
</tr>

<tr>
<td>Login </td>
<td>User is logged into the subsystem; the user's privileges are determined by the subsystem definition. The appropriate required files and groups are opened for access. </td>
</tr>

<tr>
<td>Driver </td>
<td>Procedures that make up the main body of the application are included. </td>
</tr>

<tr>
<td>Disconnect </td>
<td>All files and groups are closed for the user, who is then logged out of the subsystem. </td>
</tr>

<tr>
<td>Error </td>
<td>An optional error procedure is included. The type of error that occurred is available to the error procedure. For many types of errors, the error procedure can resume normal driver processing. </td>
</tr>
</table>

===Initialization processing===

Initialization processing is invoked when the subsystem is started. A subsystem is started by the START SUBSYSTEM command, or, if the start option is indicated in the subsystem definition, when the first user enters the subsystem. 

During subsystem initialization, <var class="product">Model 204</var> finds the subsystem definition and opens only required subsystem files and groups. If a required file or group cannot be opened, the subsystem initialization procedure terminates and the user is returned to command level.

One of the subsystem components opened during initialization is the procedure file (or group, if a multiple-procedure group has been specified). The procedure file or group must contain all of the subsystem procedures that are included by the subsystem through the communication global variable. <var class="product">Model 204</var> scans the subsystem procedure file or group for all procedures whose names begin with either of the subsystem procedure prefixes. 

The subsystem initialization procedure is included at this time. This is the only time during subsystem processing that the initialization procedure is executed.

If no error occurs, <var class="product">Model 204</var> adds the subsystem name to the list of active subsystems. At this point, the subsystem is initialized and ready for use. 

===Login processing===

Login processing is invoked when a user enters a subsystem. If the automatic login option is indicated in the subsystem definition, <var class="product">Model 204</var> logs on the user using the subsystem name as the user ID. If the automatic login option is not indicated, the user's <var class="product">Model 204</var> user ID remains in use. 

<var class="product">Model 204</var> next finds the user's subsystem user class definition in CCASYS and opens only the required subsystem files and groups with the privileges that are found for that user class. The MSGCTL parameter automatically is set for the user according to the subsystem definition. 

<var class="product">Model 204</var> sets the communication global variable to the name of subsystem login procedure and proceeds into driver processing. 

===Driver processing===

<var class="product">Model 204</var> determines which procedure to include next by examining the value of the communication global variable. The procedure name must be one of the names located by the scan of the procedure file during subsystem initialization. 

If either the global variable or the procedure name cannot be found, the subsystem's error procedure is included. If an error procedure is not specified in the subsystem definition, the user is disconnected from the subsystem. 

If the procedure name is found, <var class="product">Model 204</var> determines which prefix begins the procedure name. Processing then occurs as follows:
<ul>
<li>If the procedure name begins with the non-precompiled prefix, <var class="product">Model 204</var> includes the procedure for compilation and evaluation. </li>

<li>If the procedure name begins with the precompiled prefix, <var class="product">Model 204</var> verifies whether the procedure was compiled previously with the set of privileges defined by the user's subsystem user class.

Once the compilation status of the procedure is determined, processing is as follows: 
<ul>
<li>If the procedure was not previously compiled successfully for the set of privileges defined by the user's subsystem user class, <var class="product">Model 204</var> includes the procedure for compilation and evaluation. If compilation is successful and no previous compilation was saved for the procedure, the contents of the compiler tables are saved in the system file CCATEMP.</li>

<li>If the procedure was previously compiled successfully for the user's privilege set, <var class="product">Model 204</var> loads the contents of the compiler tables from CCATEMP and evaluates the request.</li>
</ul></li>
</ul>

<var class="product">Model 204</var> repeats driver processing until the value of the communication global variable is set to the exit value specified in the subsystem definition. When the communication global variable is set to the exit value, <var class="product">Model 204</var> proceeds into disconnect processing. 

===Disconnect processing===

Disconnect processing is invoked when the subsystem application sets the communication variable to the exit value, when an error occurs with no subsystem error procedure, or when a subsystem user is restarted by <var class="product">Model 204</var>. During disconnect processing, <var class="product">Model 204</var> closes all required subsystem files and groups for the user, as well as any optional files and groups that have not been closed by the application. 

Depending upon whether the automatic logout option is indicated, the user is then either logged out of <var class="product">Model 204</var> or returned to the <var class="product">Model 204</var> command environment. 

===Error processing===

Error processing is invoked whenever a <var class="product">Model 204</var> error occurs that cannot be handled by the procedure being executed at the time. When an error is detected, <var class="product">Model 204</var> sets the value of the error global variable. 

If the subsystem has a defined error procedure, the error procedure is included at this time. If the subsystem does not have a defined error procedure, <var class="product">Model 204</var> proceeds into disconnect processing. 

If the error trapped by the subsystem is a soft restart, a hard restart, or a terminal disconnect condition, the error procedure is invoked. The communication global variable is ignored when the error procedure completes and <var class="product">Model 204</var> proceeds with subsystem disconnect processing. 

==Parallel Query Option/204 (PQO) considerations==

This section introduces several terms and concepts which are unique to subsystems that reference remote files and scattered groups. These concepts, and related design considerations, are discussed in greater detail in [[PQO: Scattered APSY subsystems]]. 

===Remote file access===

Parallel Query Option/204 provides access to remote files under the Subsystem Management facility by allowing the system manager to define client and service subsystems:
<ul>
<li>A client subsystem is the subsystem a user is running in when requesting access to remote data. </li>

<li>A service subsystem is the subsystem on a server node that a client user's service thread is logged into.
</li>
</ul>

A service subsystem definition is stored in the CCASYS file on each node that the client subsystem accesses. The name of a subsystem must be the same at each node. The location of the client node is included in the subsystem name to uniquely identify it to the server node.

===Node availability===

A server node can be available or unavailable to a client subsystem.
<ul>
<li>A node is available if the service subsystem has been successfully started. </li>

<li>If the service subsystem has not been started, it does not have a subsystem definition structure accessible to the client and is therefore unavailable.
</li>
</ul>

A node can only be marked unavailable during start processing if there are mandatory members on a server node and the service subsystem cannot be started. If this happens, start processing also fails on the client node.

Client subsystems attempting to access service subsystems that are not started receive an error message from the server node. 

A previously available node can become unavailable when: 
<ul>
<li>Resumption of communication fails after recovering from a system failure.</li>

<li>A user attempts to log into the service subsystem by logging into the client subsystem, the service subsystem definition is not found, and at least one mandatory member resides on that node.</li>

<li>A user attempts to open a file on a node where the user was not previously logged in. </li>
</ul>

The user is automatically logged into all associated service subsystems when entering a subsystem that contains remote files. If the service subsystem is unavailable on a node, the user cannot be logged in. 

===File and group availability===

The members of a subsystem are files and permanent groups. With Parallel Query Option/204, members can be either automatic or manual: 
<ul>
<li>An automatic member is a subsystem group or file that is opened automatically when the subsystem is started or when a user enters the subsystem. </li>

<li>A manual member is a group or file that must be opened explicitly by the OPEN or OPENC command.
</li>
</ul>

Members can also be either mandatory or optional:
<ul>
<li>A mandatory member must be open in order to access a subsystem. Mandatory members cannot be manual.</li>

<li>An optional member is not required for subsystem access (start and login processing can succeed without it).
</li>
</ul>

At any given time a member can be open or closed to a subsystem or to a user within a subsystem. The following sections explain the conditions under which the different kinds of members are accessible to APSY subsystems and their users.

====Member availability to subsystems====

Automatic members of subsystems are always opened by the START SUBSYSTEM command or by SUBSYSTEM LOGIN. At the end of START processing, each automatic member is open unless either the START or OPEN failed. 

Manual members of subsystems are in the closed state at the completion of START SUBSYSTEM processing and must be explicitly opened by the user. Manual members become open to the subsystem if an OPEN operation succeeds. If OPEN fails due to node unavailability or for user-specific reasons (for example, if the user's line goes down) the member remains closed to the subsystem.

If a node becomes unavailable to a subsystem, all automatic subsystem members and all open manual subsystem members residing on the unavailable node are marked disabled.

If a STOP FILE/GROUP command is issued for a manual member on the client subsystem's node, the member is closed to the client subsystem when the last user closes it. If the member is located on the service subsystem node, the file is closed to the service subsystem when the STOP is complete or the last user closes the file.

====Member availability to subsystem users====

When a user enters a subsystem, automatic subsystem members are opened.

If a user LOGIN or OPEN operation fails for an optional member, the member is left closed for the user but remains available to the subsystem. If a mandatory member cannot be opened, the user is denied access to the subsystem.

If a user LOGIN or OPEN operation fails for an already open member, the member is left disabled for the user but remains open to the subsystem. 

If an automatic mandatory member is closed to the subsystem, new users are not allowed to enter the subsystem.

Manual members of subsystems are closed for a user within a subsystem until the user issues an OPEN command or statement. In this case it does not matter whether the member is open or closed to the subsystem.

If compilation and/or loading of a request fails due to a communications failure, previously opened members on the failing node become disabled to the user. 

A user can close optional members at any time by issuing the CLOSE command.

====Enabling disabled subsystem files====

In the event that a subsystem file or group is marked disabled, you can enable it (after correcting the problem) without having to bring the subsystem down. To do this, use the ENABLE SUBSYSTEM command:

====Syntax====
ENABLE SUBSYSTEM subsysname
[FILE name AT location | GROUP name]

Where:
<ul>
<li><var class="term">subsysname</var> is the name of the client subsystem</li>

<li><var class="term">location</var> is the name of the remote node where the file is stored. Note that the location must be explicitly specified; you cannot reference local files with the ENABLE SUBSYSTEM command.
</li>
</ul>

====Intentionally disabling a subsystem file====

You can make a subsystem file or group (or an entire subsystem, if a file is mandatory) temporarily inaccessible without having to bring the subsystem down, using the DISABLE SUBSYSTEM command:
DISABLE SUBSYSTEM subsysname
[FILE name AT location | GROUP name]


When a file or group is intentionally disabled with the DISABLE SUBSYSTEM command, subsystem behavior is exactly the same as when a communications failure causes the disabling. This behavior is described in [[#File and group availability|File and group availability]].

===Trust===

As an alternative to the privilege settings normally available through the Subsystem Management facility, the system manager at a service node can control client subsystem access by creating a trust definition for the client subsystem. If a client subsystem is fully or partially trusted, the trust definition is sufficient for maintaining the relationship with the client; the system manager at the service node does not have to create and maintain a separate set of file and SCLASS definitions for the client subsystem.

For example, suppose a subsystem located on a node named DETROIT (the client node) includes in its definition files located on a node named CLEVELAND (the service node). Further, suppose the subsystem is fully or partially trusted by CLEVELAND. In this case, the file and SCLASS definitions are maintained only on the client node (DETROIT), and the service node (CLEVELAND) needs only to maintain the trust definition.

The four levels of trust available with Parallel Query Option/204 are:
<ul>
<li>Full trust

Only the subsystem name and location appear on the service node's definition, which you create on the Subsystem Trust screen.</li>

<li>Partial trust

Along with the subsystem name and location, you can specify maximum file privileges. In this case, the client subsystem is trusted, but the maximum file privileges and field level security levels specified on the Subsystem Trust screen cannot be exceeded.
<ul>
<li>If a user requests file privileges that would exceed the maximum, the service node does not open the file to that user.</li>
<li>If a user requests a field level security status that would exceed the maximum, <var class="product">Model 204</var> automatically resets the request to the allowed level (that is, the maximum) and opens the file to that user.</li>
</ul></li>

<li>Restricted trust

For a subsystem that has a restricted trust definition, you make no entries on the Subsystem Trust screen. A restricted trust definition is based solely on entries you make on these five screens:
<ul>
<li>Subsystem Activity</li>
<li>Subsystem File Use</li>
<li>Operational Parameters</li>
<li>Subsystem Classes</li>
<li>Subsystem Class Users</li>
</ul>

The accessibility of service node files to a client subsystem is determined by the SCLASS, user, and file privileges that you specify on these screens. 
</li>

<li>No trust

No subsystem service definition exists for the subsystem. The client subsystem cannot access any files on the service node as subsystem files. The files on the service node can, however, be accessed from within a client subsystem as individual, non-subsystem files if the following criteria are met:
<ul>
<li>Parallel Query Option/204 is installed at both sites.</li>
<li>Horizon is installed at both sites, and there are link, processgroup, and process definitions connecting the client node to the service node.</li>
<li>For any given file, the value of the <var>[[OPENCTL parameter|OPENCTL]]</var> parameter allows remote access (X'02', X'04', or X'08'). </li>
</ul>
</li>
</ul>

See the
<var class="book">Rocket Parallel Query Option/204 User's Guide</var> for detailed information on creating and managing trust definitions.

==Subsystem design considerations==

This section presents coding considerations for subsystem procedures. Some of the guidelines listed below also appear in earlier sections. They are consolidated here for the convenience of the application developer. 

===Coding considerations===
<ul>
<li>Procedures should be small and modular.</li>

<li>Procedures to which control is passed via the communication global variable must be stored in a designated procedure file. The procedure file is the default file for a subsystem application unless the default file is explicitly changed by a DEFAULT command or overridden by an IN clause.</li>

<li>Each procedure must set the communication global variable to indicate the next procedure to be included. If this variable is not set, an error or loop occurs.</li>

<li>The communication global variable must be set to the exit value in order to exit the subsystem. Server table sizes and other parameters should be reset to the values existing prior to entering the subsystem so that the user is returned to his/her normal operating environment. Parameter values are restored automatically when the automatic login option is used.</li>

<li>Included procedures normally are included by using the INCLUDE command. Included procedures cannot be precompiled.</li>

<li>Non-subsystem files can be opened and referenced only by non-precompiled procedures.</li>

<li>Precompiled procedures cannot reference PERM groups that are not members of the same subsystem.</li>

<li>Compiler table sizes must be the same each time a precompiled procedure is invoked. The UTABLE command should be used carefully.</li>

<li>The contents of the command line global variable are not deleted by UTABLE commands which normally delete the contents of GTBL, as long as the UTABLE command is issued from within a subsystem. </li>

<li>Distinct group numbers are assigned to optional groups at START SUBSYSTEM time. Those numbers cannot be used by non-subsystem members opened within the subsystem. Thus the NGROUP limit used for earlier releases might be exceeded during either START or OPEN processing inside the subsystem.</li>

<li>To prevent you from having the wrong file or group privileges in a subsystem, <var class="product">Model 204</var> closes optional files and groups before entering a subsystem. In earlier releases, optional files and groups were only closed when you left the subsystem.
</li>
</ul>

Users should be aware of the following conditions when coding applications to run under the Subsystem Management facility:
<ul>
<li>Dummy strings (??, ?$, ?&) in precompiled procedures are resolved only during compilation for the first user.</li>

<li>If a subsystem file is referenced by a precompiled procedure, no user can RESTORE or INITIALIZE the file, or RENAME, DELETE, or REDEFINE a field while the subsystem is active.</li>

<li>A subsystem procedure cannot issue the CREATE command for a subsystem file.</li>

<li>LXTBL and LFTBL cannot be reset from within a subsystem procedure.</li>

<li>All DO YOU REALLY WANT TO messages are suppressed and the default action is assumed.

The default action for each type of message is listed in [[M204.1076]]. 

If you do not wish the default action to be executed, you need to add a message handler routine to the procedure containing the statement that invokes the message. 
</li>
</ul>

====Keeping track of the number of files referenced====

To keep track of the files referenced in a subsystem procedure, which cannot exceed 6,043 files — a CCATEMP page, use the following formula:
NFILE + NRFILE + 1 (for CCAGRP) + 1 (for CCASYS)


==Record locking considerations==

Depending upon the subsystem definition, <var class="product">Model 204</var> might place a share lock on one or more subsystem procedure names or group names. 

If the subsystem is defined with permanent groups, <var class="product">Model 204</var> locks the group names to ensure that the group definitions do not change while the subsystem is running. A share lock is maintained for each group while the subsystem is active. 

===If subsystem files are defined as unlocked===

If the subsystem definition specifies that subsystem files are unlocked, <var class="product">Model 204</var> locks in share mode each of the subsystem procedures to ensure that the procedures do not change or move. This prevents any user from:
<ul>
<li>Issuing the DELETE PROCEDURE command</li>

<li>Issuing the RENAME PROCEDURE command</li>

<li>Updating the procedure while the subsystem is active.
</li>
</ul>

==Subsystem procedure control functions==

The User Language functions, [[$Sclass#$Sclass|$Sclass]] and [[$Subsys#$Subsys|$Subsys]] can be useful in determining subsystem program control.

===$Sclass function===

The $Sclass function returns the Sclass name of the current user. $Sclass is useful when the transfer of control is dependent upon a user's privileges. For example:
 BRANCH: JUMP TO (ADD.REC, VIEW.REC, UPD.REC) -
%MAIN.MENU:SELECTION
.
.
.
UPD.REC: IF $sclass = 'READ' THEN
IF $SETG('NEXT','PRE-RPT.PGM') THEN
PRINT 'GLOBAL TABLE FULL'
END IF
ELSEIF $sclass = 'UPDATE' THEN
IF $setg('NEXT','PRE-MAINT.PGM') THEN
PRINT 'GLOBAL TABLE FULL'
END IF
.
.
.


===$Subsys function===

The $Subsys function returns a numeric value indicating the status of a subsystem, or the name of the current subsystem (if no argument is specified). $Subsys often is used to determine whether a subsystem is active before a transfer is attempted. 

==Subsystem development tools==

This section describes three <var class="product">Model 204</var> features that are useful in developing, testing and debugging subsystem procedures:
<ul>
<li>The <var>[[DEBUG command|DEBUG]]</var> and <var>[[TEST command|TEST]]</var> commands, which assist subsystem debugging by allowing you to display the global communications variable and specify the next procedure to be INCLUDEd.</li>

<li>Multiple procedure file groups, which allow users to change procedures without stopping the subsystem or interfering with other users.</li>

<li>The Cross-Reference facility, which produces reports on the variable names, global dummy strings, and other language elements used in a specified set of User Language procedures. </li>
</ul>

===Debugging and testing facilities===

The <var class="product">Model 204</var> DEBUG and TEST SUBSYSTEM commands assist you in debugging subsystem code while it is being developed. Both commands display the value of the communication global variable, prompt you for changes, and display since-last statistics. 

DEBUG differs from TEST SUBSYSTEM in the following ways:
<ul>
<li>DEBUG can be executed by more than one user in the same subsystem at the same time; TEST SUBSYSTEM can only be executed by a single user.</li>

<li>To execute TEST SUBSYSTEM, the user must stop the subsystem, which will be restarted in single user mode as a result of issuing the TEST command. To execute DEBUG, the user does not have to stop the subsystem. The DEBUG command can be issued for any subsystem that has been started, or for any subsystem that has the AUTOSTART feature.</li>

<li>Since-last statistics are provided automatically with DEBUG; they are optional with TEST.
</li>
</ul>

In general, the DEBUG command is more convenient for subsystem developers in a multiuser environment.

To execute the DEBUG command, the user must be named to an SCLASS which has been granted either the TEST or DEBUG privilege. The DEBUG privilege does not entitle the user to execute the TEST command.

====Syntax====

The format of the DEBUG command is: 
DEBUG SUBSYSTEM subsystemname [parameters]


The extended format of the TEST command is:
TEST [DEBUG] [STATS] [SUBSYSTEM] subsystemname parameters

Where:
<ul>
<li>DEBUG specifies that the communication global variable is displayed on the user's terminal before the next procedure is included. The user then has the option of specifying a different procedure to be included next. If the user presses <var>ENTER</var> without specifying a different procedure, the procedure whose name is currently displayed is included next. </li>

<li>STATS specifies that since-last statistics are displayed on the user's terminal after each procedure is evaluated. Since-last statistics are described in [[Using system statistics#User since-last statistics|User since-last statistics]]. </li>

<li>SUBSYSTEM specifies that the word following the keyword is the name of a subsystem and that parameters follow the subsystem name. This keyword can be used to eliminate confusion when DEBUG or STATS is the name of a subsystem or subsystem parameter. </li>

<li>parameters specifies the parameters to be stored in the command line global variable. The parameter information can be as many as 255 characters in length.
</li>
</ul>

===Multiple procedure files===

If <code>PROCFILE=*</code> is specified when a group is created, then several files in a group can contain procedures. When the <var>INCLUDE</var> command is executed in the context of a multiple procedure file group, files are searched, left to right, in the order they were defined in the original <var>CREATE GROUP</var> command.

Multiple procedure file groups make it possible to change subsystem procedures without having to stop the subsystem. This is accomplished by setting GROUP to <code>Y</code> for the subsystem's procedure file in the subsystem definition, and by specifying a number value for Procs NUMLK that is less than the number of files in the group. The application subsystem locks the procedures in the last (or rightmost) NUMLK number of files, as determined by the right-to-left order they were specified in the <var>CREATE GROUP</var> command that defined the procedure group. For an example, see [[System requirements for Application Subsystems#Subsystem File Use screen|Subsystem File Use screen]].

The multiple procedure file option also allows different users to make changes to procedures in the same subsystem without interfering with each other. The procedure group specified in the subsystem definition must have a corresponding <var>CREATE PERM GROUP</var> definition. However, any individual user can create or open a temporary group with the same name as the subsystem's permanent procedure group. If a user has such a temporary group open and enters a subsystem, the subsystem uses the temporary group instead of the subsystem's permanent group. 

The following restrictions apply to the use of temporary groups to store subsystem procedure files:
<ul>
<li>The user's SCLASS must have the <var>TEST</var> or <var>DEBUG</var> privilege.</li>

<li>The last n files of the <var>CREATE PERM GROUP</var> command (where n is set by the <code>NUMLK</code> parameter) must correspond exactly to the last n files of the <var>CREATE TEMP GROUP</var> command. </li>
</ul>

===Cross-Reference facility===

The Cross-Reference facility is a Dictionary facility that can be invoked from both the Dictionary Main Menu and <var class="product">Model 204</var> command level. It produces reports for users who develop and maintain <var class="product">Model 204</var> User Language procedures.

The output reports show the line numbers where language elements such as labels, functions, images and variable names occur in a specified set of procedures. Elements within subroutines and nested INCLUDEs can also be cross-referenced.

The Cross-Reference Report is produced in batch mode (by a batch job in OS and DOS, by a service machine in CMS). Prior to submitting a cross-reference job, the user can specify:
<ul>
<li>A set of procedures in a procedure file or group</li>

<li>A set of language elements to be cross referenced</li>

<li>Substitute values for User Language global dummy strings</li>

<li>Job-related parameters such as output destination and lines per page
</li>
</ul>

The Cross-Reference facility also includes Preview and Browse functions, which inform the user about the procedures selected for processing.

For a complete description of the Cross-Reference facility, refer to the [[:Category:Dictionary/204#Dictionary/204 topics|Dictionary/204 topics]].

[[Category:SOUL]]

Release notes for Model 204 version 7.8

2019-12-18T21:58:22Z

ELowell: /* SIRTERM */

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus and TN3270 debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>When execution pauses, the debuggers now [[#Subroutine or method display|display the subroutine or method]] being executed.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumeration values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string will determine truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in Julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same <var>SNAPCTL</var> settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter <var>CUSTOM=11</var> setting no longer requires that a <var>*LOWER</var> command be issued prior to a <var>LOGCTL</var> command (to add or change a password) to preserve mixed case input. Prior to this release, with <var>CUSTOM=11</var> in place, *LOWER had to be issued before a <var>LOGCTL</var> command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname (the owning id for the ONLINE job) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed (previously such a LOGON would have failed). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL. This in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new <var>WEBSOCKET</var> parameter. The WEBSOCKET option can be specified on either the port definition or the JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the <var>WEBSOCKET</var> and <var>NOWEBSOCKET</var> parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value is enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up a maximum of 1024 such requests before dropping any. This increased backlog reduces, or in most cases eliminates, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change is enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of <var>[[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]]</var> input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client was freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of <var>[[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]]</var> has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use <var>[[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]]</var>.

This change is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the <var>NLDAPBUF</var> parameter in CCAIN. See below for details on <var>[[#NLDAPBUF|NLDAPBUF]]</var>.

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==
These enhancements apply to the Janus and TN3270 debuggers.

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. This feature is enabled in V7.7 with the application of zap 77z363.

===Subroutine or method display===
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
The above improvements are enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change is enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

<code>D ECF M</code> displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

<code>D ECF N</code> displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

<code>D ECF U</code> displays details of users currently accessing ECF modules. This is also the default option, and so <code>D ECF</code> will display the same output as <code>D ECF U</code>. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

<code>D ECF <var class="term">function</var> LIKE <var class="term">?</var> </code> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>[[REGENERATE command|REGENERATE]]</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>[[SETGRC command|SETGRC]]</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. <var>ENQTIME</var> can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of <var>ENQTIME</var> is 3000 (3 seconds).

For example, with <code>ENQTIME = 100</code> and <code>ENQRETRY = 7</code>, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The <var>ENQTIME</var> parameter may also be reset with $ResetN.

This new parameter is enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
<var>LFSCB</var>, the length of the full screen buffer, now has a new minimum value of 8 (the previous minimum was 0). This change is enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If <var>SERV4G</var> is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.
===SIRTERM===
The <var>[[SIRTERM parameter|SIRTERM]]</var> (Sirius terminal options) parameter settings have changed.
The changes to <var>SIRTERM</var> allow a user to preclude a reset to a Model that is not supported by the terminal emulator in use.

The X'01' setting (MODEL 6 support) is no longer used.

The X'02' setting (Write Structured Field Query Support) now supports MODEL 6 terminals by default.

The new X'08' setting always issues a Write Structured Field Query for Terminal Model Resets for terminals connected to Model 204 through VTAM or TELNET, provided that X'02' has been set. This precludes Terminal Model RESETs to Models that are not supported by the terminal emulator in use.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. This new parameter is enabled in V7.7 with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need <var>WEBDFLT=1</var>, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use <var>[[MONITOR_command|MONITOR]] SYSTEM STATISTICS</var> to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The <var>[[CUSTOM parameter|CUSTOM=38]]</var> parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the <var>RESET</var> command. This <var>CUSTOM</var> setting is now restricted to the <var>RESET</var> of the <var>LAUDIT</var> parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change is enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the <var>PAGESZ</var> parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of <var>ECPRIV</var>, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The <var>ECPRIV</var> 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the <var>ECPRIV</var> 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the <var>ECFPRIV</var> 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resettable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the <var>ZHPF</var> command without being logged on. From this release onwards, a user must be logged on with system manager privileges in order to issue this command.

Additionally, the command output will now only display results for currently open files.

This change is enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal <var>MODEL</var> parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of <var>LOUTPB</var> necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-18T00:21:43Z

ELowell: minor formatting changes

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus and TN3270 debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>When execution pauses, the debuggers now [[#Subroutine or method display|display the subroutine or method]] being executed.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumeration values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string will determine truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in Julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same <var>SNAPCTL</var> settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter <var>CUSTOM=11</var> setting no longer requires that a <var>*LOWER</var> command be issued prior to a <var>LOGCTL</var> command (to add or change a password) to preserve mixed case input. Prior to this release, with <var>CUSTOM=11</var> in place, *LOWER had to be issued before a <var>LOGCTL</var> command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname (the owning id for the ONLINE job) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed (previously such a LOGON would have failed). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL. This in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new <var>WEBSOCKET</var> parameter. The WEBSOCKET option can be specified on either the port definition or the JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the <var>WEBSOCKET</var> and <var>NOWEBSOCKET</var> parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value is enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up a maximum of 1024 such requests before dropping any. This increased backlog reduces, or in most cases eliminates, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change is enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of <var>[[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]]</var> input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client was freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of <var>[[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]]</var> has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use <var>[[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]]</var>.

This change is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the <var>NLDAPBUF</var> parameter in CCAIN. See below for details on <var>[[#NLDAPBUF|NLDAPBUF]]</var>.

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==
These enhancements apply to the Janus and TN3270 debuggers.

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. This feature is enabled in V7.7 with the application of zap 77z363.

===Subroutine or method display===
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
The above improvements are enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change is enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

<code>D ECF M</code> displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

<code>D ECF N</code> displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

<code>D ECF U</code> displays details of users currently accessing ECF modules. This is also the default option, and so <code>D ECF</code> will display the same output as <code>D ECF U</code>. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

<code>D ECF <var class="term">function</var> LIKE <var class="term">?</var> </code> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>[[REGENERATE command|REGENERATE]]</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>[[SETGRC command|SETGRC]]</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. <var>ENQTIME</var> can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of <var>ENQTIME</var> is 3000 (3 seconds).

For example, with <code>ENQTIME = 100</code> and <code>ENQRETRY = 7</code>, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The <var>ENQTIME</var> parameter may also be reset with $ResetN.

This new parameter is enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
<var>LFSCB</var>, the length of the full screen buffer, now has a new minimum value of 8 (the previous minimum was 0). This change is enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If <var>SERV4G</var> is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.
===SIRTERM===
The <var>[[SIRTERM parameter|SIRTERM]]</var> (Sirius terminal options) parameter settings have changed.
The changes to <var>SIRTERM</var> allow a user to preclude a reset to a Model that is not supported by the terminal emulator in use.

The X'01' setting (MODEL 6 support) is no longer used.

The X'02' setting (Write Structured Field Query Support) now supports MODEL 6 terminals by default.

The new X'08' setting always issues a Write Structured Field Query for Terminal Model Resets for terminals connected to Model 204 through VTAM or TELNET. This precludes Terminal Model RESETs to Models that are not supported by the terminal emulator in use.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. This new parameter is enabled in V7.7 with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need <var>WEBDFLT=1</var>, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use <var>[[MONITOR_command|MONITOR]] SYSTEM STATISTICS</var> to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The <var>[[CUSTOM parameter|CUSTOM=38]]</var> parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the <var>RESET</var> command. This <var>CUSTOM</var> setting is now restricted to the <var>RESET</var> of the <var>LAUDIT</var> parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change is enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the <var>PAGESZ</var> parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of <var>ECPRIV</var>, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The <var>ECPRIV</var> 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the <var>ECPRIV</var> 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the <var>ECFPRIV</var> 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resettable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the <var>ZHPF</var> command without being logged on. From this release onwards, a user must be logged on with system manager privileges in order to issue this command.

Additionally, the command output will now only display results for currently open files.

This change is enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal <var>MODEL</var> parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of <var>LOUTPB</var> necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-17T23:49:08Z

ELowell: minor formatting and wordsmithing

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus and TN3270 debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>When execution pauses, the debuggers now [[#Subroutine or method display|display the subroutine or method]] being executed.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter <var>CUSTOM=11</var> setting no longer requires that a <var>*LOWER</var> command be issued prior to a <var>LOGCTL</var> command (to add or change a password) to preserve mixed case input. Prior to this release, with <var>CUSTOM=11</var> in place, *LOWER had to be issued before a <var>LOGCTL</var> command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname (the owning id for the ONLINE job) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed (previously such a LOGON would have failed). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL. This in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new <var>WEBSOCKET</var> parameter. The WEBSOCKET option can be specified on either the port definition or the JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the <var>WEBSOCKET</var> and <var>NOWEBSOCKET</var> parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value is enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up a maximum of 1024 such requests before dropping any. This increased backlog reduces, or in most cases eliminates, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change is enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of <var>[[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]]</var> input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client was freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of <var>[[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]]</var> has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use <var>[[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]]</var>.

This change is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the <var>NLDAPBUF</var> parameter in CCAIN. See below for details on <var>[[#NLDAPBUF|NLDAPBUF]]</var>.

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==
These enhancements apply to the Janus and TN3270 debuggers.

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. This feature is enabled in V7.7 with the application of zap 77z363.

===Subroutine or method display===
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
The above improvements are enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change is enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

<code>D ECF M</code> displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

<code>D ECF N</code> displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

<code>D ECF U</code> displays details of users currently accessing ECF modules. This is also the default option, and so <code>D ECF</code> will display the same output as <code>D ECF U</code>. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

<code>D ECF <var class="term">function</var> LIKE <var class="term">?</var> </code> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>[[REGENERATE command|REGENERATE]]</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>[[SETGRC command|SETGRC]]</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. <var>ENQTIME</var> can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of <var>ENQTIME</var> is 3000 (3 seconds).

For example, with <code>ENQTIME = 100</code> and <code>ENQRETRY = 7</code>, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The <var>ENQTIME</var> parameter may also be reset with $ResetN.

This new parameter is enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
<var>LFSCB</var>, the length of the full screen buffer, now has a new minimum value of 8 (the previous minimum was 0). This change is enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If <var>SERV4G</var> is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.
===SIRTERM===
The <var>[[SIRTERM parameter|SIRTERM]]</var> (Sirius terminal options) parameter settings have changed.
The changes to <var>SIRTERM</var> allow a user to preclude a reset to a Model that is not supported by the terminal emulator in use.

The X'01' setting (MODEL 6 support) is no longer used.

The X'02' setting (Write Structured Field Query Support) now supports MODEL 6 terminals by default.

The new X'08' setting always issues a Write Structured Field Query for Terminal Model Resets for terminals connected to Model 204 through VTAM or TELNET. This precludes Terminal Model RESETs to Models that are not supported by the terminal emulator in use.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. This new parameter is enabled in V7.7 with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need <var>WEBDFLT=1</var>, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use <var>[[MONITOR_command|MONITOR]] SYSTEM STATISTICS</var> to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The <var>[[CUSTOM parameter|CUSTOM=38]]</var> parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the <var>RESET</var> command. This <var>CUSTOM</var> setting is now restricted to the <var>RESET</var> of the <var>LAUDIT</var> parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change is enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the <var>PAGESZ</var> parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an <code>M204.1149</code> message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of <var>ECPRIV</var>, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The <var>ECPRIV</var> 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the <var>ECPRIV</var> 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the <var>ECFPRIV</var> 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resettable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the <var>ZHPF</var> command without being logged on. From this release onwards, a user must be logged on with system manager privileges in order to issue this command.

Additionally, the command output will now only display results for currently open files.

This change is enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal <var>MODEL</var> parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of <var>LOUTPB</var> necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-17T20:54:37Z

ELowell: formatting/run-on sentence cleanup

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus and TN3270 debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>When execution pauses, the debuggers now [[#Subroutine or method display|display the subroutine or method]] being executed.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter <var>CUSTOM=11</var> setting no longer requires that a <var>*LOWER</var> command be issued prior to a <var>LOGCTL</var> command (to add or change a password) to preserve mixed case input. Prior to this release, with <var>CUSTOM=11</var> in place, *LOWER had to be issued before a <var>LOGCTL</var> command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname (the owning id for the ONLINE job) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed (previously such a LOGON would have failed). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL. This in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new <var>WEBSOCKET</var> parameter. The WEBSOCKET option can be specified on either the port definition or the JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the <var>WEBSOCKET</var> and <var>NOWEBSOCKET</var> parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value is enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up a maximum of 1024 such requests before dropping any. This increased backlog reduces, or in most cases eliminates, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change is enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of <var>[[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]]</var> input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client was freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of <var>[[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]]</var> has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use <var>[[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]]</var>.

This change is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the <var>NLDAPBUF</var> parameter in CCAIN. See below for details on <var>[[#NLDAPBUF|NLDAPBUF]]</var>.

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==
These enhancements apply to the Janus and TN3270 debuggers.

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. This feature is enabled in V7.7 with the application of zap 77z363.

===Subroutine or method display===
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
The above improvements are enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change is enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

<code>D ECF M</code> displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

<code>D ECF N</code> displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

<code>D ECF U</code> displays details of users currently accessing ECF modules. This is also the default option, and so <code>D ECF</code> will display the same output as <code>D ECF U</code>. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

<code>D ECF <var class="term">function</var> LIKE <var class="term">?</var> </code> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>[[REGENERATE command|REGENERATE]]</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>[[SETGRC command|SETGRC]]</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter is enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 (the previous minimum was 0). This change is enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.
===SIRTERM===
The <var>[[SIRTERM parameter|SIRTERM]]</var> (Sirius terminal options) parameter settings have changed.
The changes to <var>SIRTERM</var> allow a user to preclude a reset to a Model that is not supported by the terminal emulator in use.

The X'01' setting (MODEL 6 support) is no longer used.

The X'02' setting (Write Structured Field Query Support) now supports MODEL 6 terminals by default.

The new X'08' setting always issues a Write Structured Field Query for Terminal Model Resets for terminals connected to Model 204 through VTAM or TELNET. This precludes Terminal Model RESETs to Models that are not supported by the terminal emulator in use.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. This new parameter is enabled in V7.7 with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The <var>[[CUSTOM parameter|CUSTOM=38]]</var> parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change is enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This change is enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-17T00:03:41Z

ELowell: /* SIRTERM */

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus and TN3270 debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>When execution pauses, the debuggers now [[#Subroutine or method display|display the subroutine or method]] being executed.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value is enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change is enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This change is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==
These enhancements apply to the Janus and TN3270 debuggers.

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. This feature is enabled in V7.7 with the application of zap 77z363.

===Subroutine or method display===
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
The above improvements are enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change is enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter is enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change is enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.
===SIRTERM===
The <var>[[SIRTERM parameter|SIRTERM]]</var> (Sirius terminal options) parameter settings have changed.
The changes to <var>SIRTERM</var> allow a user to preclude a reset to a Model that is not supported by the terminal emulator in use.

The X'01' setting (MODEL 6 support) is no longer used.

The X'02' setting (Write Structured Field Query Support) now supports MODEL 6 terminals by default.

The new X'08' setting always issues a Write Structured Field Query for Terminal Model Resets for terminals connected to Model 204 through VTAM or TELNET. This precludes Terminal Model RESETs to Models that are not supported by the terminal emulator in use.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. This new parameter is enabled in V7.7 with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change is enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This change is enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

New and updated messages in Model 204 version 7.8

2019-12-14T00:20:12Z

ELowell: /* M204.2971 Unable to reset Model: reason */ deleted

[[Release notes for Model 204 version 7.8|Back to release notes]]

<div class="noautonum">__TOC__</div>
This topic lists messages that were added or changed for Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

==M204 messages==
===M204.0141: Bug .. duplicate file name in checkpoint record===

A duplicate file name was encountered while attempting to add a deferred update data set to the file directory during recovery. This indicates a potential bug in the Model 204 software. 

System manager response: Contact [[Contacting Rocket Software Technical Support|Technical Support]] with the following documentation: 
<ul>
<li>Audit trail from the previous run </li>
<li>Journal from the previous run </li>
</ul>

Operator response: Notify the system manager. 
{{Template:M204.0141 footer}}

===M204.0143: No files changed after last checkpoint, RESTART bypassed===
This message indicates that no updates were detected while scanning the checkpoint data set beyond the last checkpoint or the specified checkpoint. 
{{Template:M204.0143 footer}}

===M204.0165: Missing an update unit from ICL (InComplete List)===

While scanning the CCARF data set, Model 204 has detected the end of an update unit for which no corresponding start of update unit was found. Possible explanations for this error are: 
<ul>
<li>A utility program was used to copy the original journal to data set being used as CCARF, and a portion of the original data set was not copied. </li>
<li>A copy was not done. </li>
</ul>

System manager response: If the original journal was a multi-volume data set and was copied to another data set for input to this run, verify that all volumes were in fact copied, and rerun the job. If CCARF was the original data set, contact [[Contacting Rocket Software Technical Support|Technical Support]]. Have the following documentation available: 
<ul>
<li>Audit trail of the original run </li>
<li>Snap </li>
<li>UTILJ of the CCARF data set or a copy of this data set on tape </li>
<li>UTILC of the restart data set or a copy of this data set on tape </li>
</ul>
{{Template:M204.0165 footer}}

===M204.0352: IODEV=nn, Ok uuuuuuuuuu aaaaaaaaaa llllll yy.ddd mmm dd hh.mm.ss ccc nnnnnnnn===

The layout of this message has been reformatted to accommodate five digit user numbers.

{{Template:M204.0352 footer}}

===M204.0479: process group not found: processgroupname===

A <var>[[Statement syntax#TRANSFER|TRANSFER]]</var> statement was evaluated, resulting in an attempt to perform a VTAM trusted logon in another Online (the target Online). The <var>PARTNER</var> processgroup, identified in the <var>[[DEFINE PROCESS command: Transfer Control partner|DEFINE PROCESS]]</var> command in the transferring Online, was not found in the target Online. As a result, the TRANSFER fails and the user remains in the transferring online.

System manager response: The <code>PARTNER=</code> token in the <var>DEFINE PROCESS</var> command of the transferring Online has an incorrect value for <var class="term">processgroupName</var>. Check the spelling to ensure that it is the correct name of the intended processgroup in the target Online.

Return codes: I 0 0 AUDITMS
----

===M204.0480: Invalid backpage request: backPage===

A backpage command of the form <var>P -n</var> or <var>P +n</var> was issued, but <var>[[NBKPG parameter|NBKPG]]</var> is 0, or the value of <var class="term">n</var> is invalid. The command is echoed in hex, so you can see exactly what was entered. For example, if <code>P -99</code> was issued but <var>NBKPG</var> is 50, then the following message would be issued:
M204.0480: Invalid backpage request: P -99(X'D74060F9F9')

Response: Correct the backpage command, or set <var>NBKPG</var> greater than 0.

{{Template:M204.0480 footer}}

===M204.0481: Procedure procName in subsysName could not be made resident; increase RESPAGE or RESSIZE ===

The named procedure in the named subsystem could not be made resident in resident request storage.


Response: Increase the size of resident request storage with a <var>[[RESSIZE parameter|RESSIZE]]</var> or <var>[[RESPAGE parameter|RESPAGE]]</var> parameter in CCAIN. <var>RESSIZE</var> (below-the-bar storage) can be dynamically reset, but <var>RESPAGE</var> (above-the-bar storage) cannot.

{{Template:M204.0481 footer}}

===M204.0541:Procedure is in use: procedure===
The procedure named in the message is currently in use by another user. The command entered cannot be processed until the procedure is no longer in use. 
Response: Retry the command when the procedure is no longer in use. 
{{Template:M204.0541 footer}}

===M204.0569: File filename?,? Find: Table B records to be searched ?=? number===
The message test now includes the filename, to help track down the cause of the direct search. This change has been enabled within v7.7 with the application of zap 77z032, and within V7.6 with the application of zap 76z386.
{{Template:M204.0569 footer}}

===M204.1070: ALLOCATE ddName failed - reason===
This message has been changed to add the ddname of the failing dataset to the message text.
{{Template:M204.1070 footer}}

===M204.1500: token ===
Message M204.1500: <var class="term">token</var> has a new form relevant to the [https://m204wiki.rocketsoftware.com/index.php/CA-ACF2_MVS_interface CA-ACF2 MVS], [https://m204wiki.rocketsoftware.com/index.php/CA-ACF2_VM_interface CA-ACF2 VM], [https://m204wiki.rocketsoftware.com/index.php/Security_Server_(formerly_RACF)_interface Security Server (formerly RACF)], and [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface CA-Top Secret] Model 204 security interfaces.

When the default user fails to log in, the security interface is operational but CCASTAT logons are not allowed. The following error message is displayed:
M204.1500: CCASTAT logons not allowed
{{Template:M204.1500 footer}}

----

===M204.1899 Transfer statement from sourceVtamName to targetVtamName complete, User userId disconnected===
The message, issued when a VTAM Transfer statement completes, now contains the source and target VTAM names for the transfer process.

The change in message text is enabled within V7.7 with the application of zap 77z310.
{{Template:M204.1899 footer}}

===M204.1900 User userId transferred to targetVtamName from sourceVtamName===
This message, issued on the target ONLINE when a user has transferred to that ONLINE, now displays the source and target VTAM names involved in the VTAM Transfer.

The change in message text is enabled within V7.7 with the application of zap 77z310.
{{Template:M204.1900 footer}}

===M204.2020 File fileName; condition?,? OPEN command rejected===
The first change to this message is that the filename of the affected file is now displayed at the beginning of the message text.

The second change is that a second error type affecting file opens is now support. The original error type of "Unsupported device for Model 204 database %F" was reported for all condition,s even where the device type wasn't the underlying issue. Whilst this error type has been retained for conditions where it is valid, a new error type of "DDNAME not found" is now available for the message. Thus, in a situation where one thread is attempting to allocate a ddname, and another thread in parallel is trying to open a file with the same ddname, the following message variant may be produced

M204.2020: File filename; DDNAME not found, OPEN command rejected

{{Template:M204.2020 footer}}

===M204.2700 CHECKPOINT command ignored: sub-transaction checkpoint in progress===

A <code>[[CHECKPOINT_command|CHECKPOINT]] (TRAN | SUBTRAN | ABORT)</code> command was issued while the system was taking a sub-transaction checkpoint. The command is ignored. If this message was issued in response to a <code>CHECKPOINT ABORT</code> command, the
sub-transaction in progress has passed that phase of its processing during which it can be aborted.

{{Template:M204.2700 footer}}

===M204.2964 Password missing or too long===

A password string within an IFSTRTN call has not been delimited with a semicolon.


Response:
Ensure that the password string is delimited by a semicolon, as in the following example

CALL IFSTRTN(RC,'logonid;password;'...)
Version introduced:
7.8

Return codes: E 00 04 AUDITMS NOCOUNT

===M204.2965 Unable to cleanly close log file(s)===
Introduced in zap 77z243.
This message causes a snap/dump if the log file (such as a journal, jlog, or checkpoint) cannot be cleanly quiesced when bringing down an Online. The problem with the log file is rare but caused a hang further along in processing. This message causes a snap/dump much closer to the time of error, making it easier to diagnose the problem.
Response: Use the snap/dump generated by the message to diagnose the cause of the error.
Return codes: E 88 88 DUMP SNAP AUDITAD NOTERM OPR
----

===M204.2966 what line number?,? procedure proc in file file===

This message provides diagnostic information following various types of error messages. 

The first M204.2966 message after an error has <var class="term">what</var> set to <code>Error at</code>. Subsequent M204.2966 messages (if any) have <var class="term">what</var> set to <code>Called from</code>. 

<var class="term">number</var>, <var class="term">proc</var>, and <var class="term">file</var> indicate the line number, procedure, and file where the error occurred or from where the previous M204.2966 entry was called. Essentially, this provides a call stack trace to aid in diagnosing problems. No more than 20 levels of calls are shown for an error. 

Response: Use the M204.2966 messages after an error to try to diagnose the cause of the error.

{{Template:M204.2966 footer}}
----
===M204.2967 what line number of command level program===

This message provides diagnostic information after various types of error messages. 

The first M204.2967 message after an error has <var class="term">what</var> set to <code>Error at</code> and subsequent M204.2967 messages (if any) have <var class="term">what</var> set to <code>Called from</code>. 

<var class="term">number</var> indicates the line number for a command line program (counting from the <var>Begin</var>) where the error occurred, or where the previous [[M204.2966]] entry was called from. Essentially, this provides a call stack trace to aid in diagnosing problems. No more than 20 levels of calls are shown for an error. 

Response: Use the M204.2967 (and M204.2966, if any) after an error to try to diagnose the cause of the error.

{{Template:M204.2967 footer}}
----
===M204.2968 what: no debug info===

An error message (immediately preceding M204.2968) was issued, but insufficient compile-time information was collected to provide the diagnostic information provided in the [[M204.2966]] and [[M204.2967]] messages.
To get that additional information to help diagnose the problem, set the [[SIRFACT parameter|SIRFCAT X'01']] bit if authorized for [[SirFact]], or set the [[DEBUGUL parameter]] to a non-zero value. The latter requires no product authorization, but it does increase QTBL requirements. 

Response: If you are unable to diagnose the problem, consider setting one of the parameters described above to aid in problem diagnosis.

{{Template:M204.2968 footer}}
----
===M204.2969 MBSCAN (mbscan) exceeded?,? records to be searched ?=? number===

A Table B scan would exceed the setting of <var>[[MBSCAN parameter|MBSCAN]]</var>, so the request is cancelled. 

Response: Correct the <var>Find</var> statement at the line indicated by the following [[M204.2966]] message (hopefully available), or increase <var>MBSCAN</var> to tolerate the number of scanned records, if reasonable.

{{Template:M204.2969 footer}}
----
===M204.2970 Maximum call stack limit (limit) reached===

The number of messages describing the call stack reached the maximum allowed for such messages (currently 20). This message is largely informational; it is more useful to focus on the preceding [[M204.2966]] messages. 

Response: Examine the preceding M204.2966 messages.

{{Template:M204.2970 footer}}
==MSIR messages==
===MSIR.0942 Debugger token0 port defaulted to token2===
This message has been changed from an error message to an informational message
{{Template:MSIR.0942 footer}}

Release notes for Model 204 version 7.8

2019-12-14T00:06:43Z

ELowell: /* SERV4G */

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus and TN3270 debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>When execution pauses, the debuggers now [[#Subroutine or method display|display the subroutine or method]] being executed.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value is enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change is enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This change is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==
These enhancements apply to the Janus and TN3270 debuggers.

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. This feature is enabled in V7.7 with the application of zap 77z363.

===Subroutine or method display===
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
The above improvements are enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change is enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter is enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change is enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.
===SIRTERM===
The <var>[[SIRTERM parameter|SIRTERM]]</var> (Sirius terminal options) parameter settings have changed.
The changes to <var>SIRTERM</var> allow a user to preclude a reset to a Model that is not supported by the terminal emulator in use.

The X'01' setting (MODEL 6 support) is no longer used.

The X'02' setting (Write Structured Field Query Support) now supports MODEL 6 terminals by default.
X'02' also now issues a Write Structured Field Query for the TELNET interface as well as for VTAM.

The new X'08' setting always issues a Write Structured Field Query for Terminal Model Resets for terminals connected to Model 204 through VTAM or TELNET. This precludes Terminal Model RESETs to Models that are not supported by the terminal emulator in use.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. This new parameter is enabled in V7.7 with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change is enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This change is enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

New and updated messages in Model 204 version 7.8

2019-12-12T20:40:41Z

ELowell: /* M204.2970 Maximum call stack limit (limit) reached */

[[Release notes for Model 204 version 7.8|Back to release notes]]

<div class="noautonum">__TOC__</div>
This topic lists messages that were added or changed for Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

==M204 messages==
===M204.0141: Bug .. duplicate file name in checkpoint record===

A duplicate file name was encountered while attempting to add a deferred update data set to the file directory during recovery. This indicates a potential bug in the Model 204 software. 

System manager response: Contact [[Contacting Rocket Software Technical Support|Technical Support]] with the following documentation: 
<ul>
<li>Audit trail from the previous run </li>
<li>Journal from the previous run </li>
</ul>

Operator response: Notify the system manager. 
{{Template:M204.0141 footer}}

===M204.0143: No files changed after last checkpoint, RESTART bypassed===
This message indicates that no updates were detected while scanning the checkpoint data set beyond the last checkpoint or the specified checkpoint. 
{{Template:M204.0143 footer}}

===M204.0165: Missing an update unit from ICL (InComplete List)===

While scanning the CCARF data set, Model 204 has detected the end of an update unit for which no corresponding start of update unit was found. Possible explanations for this error are: 
<ul>
<li>A utility program was used to copy the original journal to data set being used as CCARF, and a portion of the original data set was not copied. </li>
<li>A copy was not done. </li>
</ul>

System manager response: If the original journal was a multi-volume data set and was copied to another data set for input to this run, verify that all volumes were in fact copied, and rerun the job. If CCARF was the original data set, contact [[Contacting Rocket Software Technical Support|Technical Support]]. Have the following documentation available: 
<ul>
<li>Audit trail of the original run </li>
<li>Snap </li>
<li>UTILJ of the CCARF data set or a copy of this data set on tape </li>
<li>UTILC of the restart data set or a copy of this data set on tape </li>
</ul>
{{Template:M204.0165 footer}}

===M204.0352: IODEV=nn, Ok uuuuuuuuuu aaaaaaaaaa llllll yy.ddd mmm dd hh.mm.ss ccc nnnnnnnn===

The layout of this message has been reformatted to accommodate five digit user numbers.

{{Template:M204.0352 footer}}

===M204.0479: process group not found: processgroupname===

A <var>[[Statement syntax#TRANSFER|TRANSFER]]</var> statement was evaluated, resulting in an attempt to perform a VTAM trusted logon in another Online (the target Online). The <var>PARTNER</var> processgroup, identified in the <var>[[DEFINE PROCESS command: Transfer Control partner|DEFINE PROCESS]]</var> command in the transferring Online, was not found in the target Online. As a result, the TRANSFER fails and the user remains in the transferring online.

System manager response: The <code>PARTNER=</code> token in the <var>DEFINE PROCESS</var> command of the transferring Online has an incorrect value for <var class="term">processgroupName</var>. Check the spelling to ensure that it is the correct name of the intended processgroup in the target Online.

Return codes: I 0 0 AUDITMS
----

===M204.0480: Invalid backpage request: backPage===

A backpage command of the form <var>P -n</var> or <var>P +n</var> was issued, but <var>[[NBKPG parameter|NBKPG]]</var> is 0, or the value of <var class="term">n</var> is invalid. The command is echoed in hex, so you can see exactly what was entered. For example, if <code>P -99</code> was issued but <var>NBKPG</var> is 50, then the following message would be issued:
M204.0480: Invalid backpage request: P -99(X'D74060F9F9')

Response: Correct the backpage command, or set <var>NBKPG</var> greater than 0.

{{Template:M204.0480 footer}}

===M204.0481: Procedure procName in subsysName could not be made resident; increase RESPAGE or RESSIZE ===

The named procedure in the named subsystem could not be made resident in resident request storage.


Response: Increase the size of resident request storage with a <var>[[RESSIZE parameter|RESSIZE]]</var> or <var>[[RESPAGE parameter|RESPAGE]]</var> parameter in CCAIN. <var>RESSIZE</var> (below-the-bar storage) can be dynamically reset, but <var>RESPAGE</var> (above-the-bar storage) cannot.

{{Template:M204.0481 footer}}

===M204.0541:Procedure is in use: procedure===
The procedure named in the message is currently in use by another user. The command entered cannot be processed until the procedure is no longer in use. 
Response: Retry the command when the procedure is no longer in use. 
{{Template:M204.0541 footer}}

===M204.0569: File filename?,? Find: Table B records to be searched ?=? number===
The message test now includes the filename, to help track down the cause of the direct search. This change has been enabled within v7.7 with the application of zap 77z032, and within V7.6 with the application of zap 76z386.
{{Template:M204.0569 footer}}

===M204.1070: ALLOCATE ddName failed - reason===
This message has been changed to add the ddname of the failing dataset to the message text.
{{Template:M204.1070 footer}}

===M204.1500: token ===
Message M204.1500: <var class="term">token</var> has a new form relevant to the [https://m204wiki.rocketsoftware.com/index.php/CA-ACF2_MVS_interface CA-ACF2 MVS], [https://m204wiki.rocketsoftware.com/index.php/CA-ACF2_VM_interface CA-ACF2 VM], [https://m204wiki.rocketsoftware.com/index.php/Security_Server_(formerly_RACF)_interface Security Server (formerly RACF)], and [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface CA-Top Secret] Model 204 security interfaces.

When the default user fails to log in, the security interface is operational but CCASTAT logons are not allowed. The following error message is displayed:
M204.1500: CCASTAT logons not allowed
{{Template:M204.1500 footer}}

----

===M204.1899 Transfer statement from sourceVtamName to targetVtamName complete, User userId disconnected===
The message, issued when a VTAM Transfer statement completes, now contains the source and target VTAM names for the transfer process.

The change in message text is enabled within V7.7 with the application of zap 77z310.
{{Template:M204.1899 footer}}

===M204.1900 User userId transferred to targetVtamName from sourceVtamName===
This message, issued on the target ONLINE when a user has transferred to that ONLINE, now displays the source and target VTAM names involved in the VTAM Transfer.

The change in message text is enabled within V7.7 with the application of zap 77z310.
{{Template:M204.1900 footer}}

===M204.2020 File fileName; condition?,? OPEN command rejected===
The first change to this message is that the filename of the affected file is now displayed at the beginning of the message text.

The second change is that a second error type affecting file opens is now support. The original error type of "Unsupported device for Model 204 database %F" was reported for all condition,s even where the device type wasn't the underlying issue. Whilst this error type has been retained for conditions where it is valid, a new error type of "DDNAME not found" is now available for the message. Thus, in a situation where one thread is attempting to allocate a ddname, and another thread in parallel is trying to open a file with the same ddname, the following message variant may be produced

M204.2020: File filename; DDNAME not found, OPEN command rejected

{{Template:M204.2020 footer}}

===M204.2700 CHECKPOINT command ignored: sub-transaction checkpoint in progress===

A <code>[[CHECKPOINT_command|CHECKPOINT]] (TRAN | SUBTRAN | ABORT)</code> command was issued while the system was taking a sub-transaction checkpoint. The command is ignored. If this message was issued in response to a <code>CHECKPOINT ABORT</code> command, the
sub-transaction in progress has passed that phase of its processing during which it can be aborted.

{{Template:M204.2700 footer}}

===M204.2964 Password missing or too long===

A password string within an IFSTRTN call has not been delimited with a semicolon.


Response:
Ensure that the password string is delimited by a semicolon, as in the following example

CALL IFSTRTN(RC,'logonid;password;'...)
Version introduced:
7.8

Return codes: E 00 04 AUDITMS NOCOUNT

===M204.2965 Unable to cleanly close log file(s)===
Introduced in zap 77z243.
This message causes a snap/dump if the log file (such as a journal, jlog, or checkpoint) cannot be cleanly quiesced when bringing down an Online. The problem with the log file is rare but caused a hang further along in processing. This message causes a snap/dump much closer to the time of error, making it easier to diagnose the problem.
Response: Use the snap/dump generated by the message to diagnose the cause of the error.
Return codes: E 88 88 DUMP SNAP AUDITAD NOTERM OPR
----

===M204.2966 what line number?,? procedure proc in file file===

This message provides diagnostic information following various types of error messages. 

The first M204.2966 message after an error has <var class="term">what</var> set to <code>Error at</code>. Subsequent M204.2966 messages (if any) have <var class="term">what</var> set to <code>Called from</code>. 

<var class="term">number</var>, <var class="term">proc</var>, and <var class="term">file</var> indicate the line number, procedure, and file where the error occurred or from where the previous M204.2966 entry was called. Essentially, this provides a call stack trace to aid in diagnosing problems. No more than 20 levels of calls are shown for an error. 

Response: Use the M204.2966 messages after an error to try to diagnose the cause of the error.

{{Template:M204.2966 footer}}
----
===M204.2967 what line number of command level program===

This message provides diagnostic information after various types of error messages. 

The first M204.2967 message after an error has <var class="term">what</var> set to <code>Error at</code> and subsequent M204.2967 messages (if any) have <var class="term">what</var> set to <code>Called from</code>. 

<var class="term">number</var> indicates the line number for a command line program (counting from the <var>Begin</var>) where the error occurred, or where the previous [[M204.2966]] entry was called from. Essentially, this provides a call stack trace to aid in diagnosing problems. No more than 20 levels of calls are shown for an error. 

Response: Use the M204.2967 (and M204.2966, if any) after an error to try to diagnose the cause of the error.

{{Template:M204.2967 footer}}
----
===M204.2968 what: no debug info===

An error message (immediately preceding M204.2968) was issued, but insufficient compile-time information was collected to provide the diagnostic information provided in the [[M204.2966]] and [[M204.2967]] messages.
To get that additional information to help diagnose the problem, set the [[SIRFACT parameter|SIRFCAT X'01']] bit if authorized for [[SirFact]], or set the [[DEBUGUL parameter]] to a non-zero value. The latter requires no product authorization, but it does increase QTBL requirements. 

Response: If you are unable to diagnose the problem, consider setting one of the parameters described above to aid in problem diagnosis.

{{Template:M204.2968 footer}}
----
===M204.2969 MBSCAN (mbscan) exceeded?,? records to be searched ?=? number===

A Table B scan would exceed the setting of <var>[[MBSCAN parameter|MBSCAN]]</var>, so the request is cancelled. 

Response: Correct the <var>Find</var> statement at the line indicated by the following [[M204.2966]] message (hopefully available), or increase <var>MBSCAN</var> to tolerate the number of scanned records, if reasonable.

{{Template:M204.2969 footer}}
----
===M204.2970 Maximum call stack limit (limit) reached===

The number of messages describing the call stack reached the maximum allowed for such messages (currently 20). This message is largely informational; it is more useful to focus on the preceding [[M204.2966]] messages. 

Response: Examine the preceding M204.2966 messages.

{{Template:M204.2970 footer}}
===M204.2971 Unable to reset Model: reason===
This message appears when the terminal Model is unable to be reset due to the specified reason. For example, <var>SIRTERM '08'</var> attempts a Write Structure Field Query for VTAM full screen. If the user attempts a reset to a Model that is not supported by the terminal emulator in use, the WSFQ fails. The following message is displayed:
Unable to reset Model: Write Structured Field not supported
and the reset fails.

Response: Correct the problem indicated by the reason, and retry the command. 
Message attributes:
<table class="thJustBold">
<tr><th>RETCODEO=0</th><td>Sets online return code</td></tr>
<tr><th>RETCODEB=4</th><td>Sets batch (single user) return code</td></tr>
<tr><th>CLASS=E</th><td>Error class; the message can be suppressed with the X'04' bit setting of the <var>[[MSGCTL parameter|MSGCTL]]</var> parameter</td></tr>
<tr><th>AUDITER</th><td>Writes the message with line type ER to the audit trail</td></tr>
<tr><th>NOCOUNT</th><td>Does not increment the error count (<var>[[ERCNT parameter|ERCNT]]</var>) parameter</td></tr>
</table>
[[List of Model 204 messages#M204.2971|Back to list of messages]]
<includeonly>[[Category:M204.nnnn messages]]</includeonly>
<includeonly>[[Category:M204.2800 - M204.2999]]</includeonly>
{{Template:M204.2971 footer}}

==MSIR messages==
===MSIR.0942 Debugger token0 port defaulted to token2===
This message has been changed from an error message to an informational message
{{Template:MSIR.0942 footer}}

Release notes for Model 204 version 7.8

2019-12-12T18:17:17Z

ELowell:

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus and TN3270 debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>When execution pauses, the debuggers now [[#Subroutine or method display|display the subroutine or method]] being executed.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value is enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change is enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This change is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==
These enhancements apply to the Janus and TN3270 debuggers.

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. This feature is enabled in V7.7 with the application of zap 77z363.

===Subroutine or method display===
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
The above improvements are enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change is enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This change is enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter is enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change is enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. This new parameter is enabled in V7.7 with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change is enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This change is enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

New and updated messages in Model 204 version 7.8

2019-12-12T18:07:50Z

ELowell:

Release notes for Model 204 version 7.8

2019-12-11T22:46:05Z

ELowell: /* New in this release */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus and TN3270 debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>When execution pauses, the debuggers now [[#Subroutine or method display|display the subroutine or method]] being executed.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==
These enhancements apply to the Janus and TN3270 debuggers.

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

===Subroutine or method display===
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-11T22:42:07Z

ELowell: /* Debugger enhancements */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>At breakpoints, the debuggers now [[#Subroutine or method display|display the subroutine or method]] where execution stopped.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==
These enhancements apply to the Janus and TN3270 debuggers.

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

===Subroutine or method display===
When execution pauses for a break point or runtime error, the subroutine or method being executed is indicated in the status area. In addition, the source code line information available by right-clicking on a source line now also indicates the subroutine or method.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-11T22:17:51Z

ELowell: /* New in this release */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li>The new <var>DISPLAY ECF</var> command and <var>EXTERNAL REMOVE</var> statement enable more efficient management of [[#Managing ECF tables more efficiently|ECF tables]].</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the <var>[[#FORMAT command|FORMAT]]</var> command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>At breakpoints, the debuggers now [[#Subroutine or method display|display the subroutine or method]] where execution stopped.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

===Subroutine or method display===
When execution stops, as at breakpoints, the debuggers now display in the title bar the subroutine or method where execution stopped.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-11T18:59:00Z

ELowell: /* New in this release */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent method|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li><var>DISPLAY ECF</var> displays details from [[#Managing ECF tables more efficiently|ECF tables]], or the current status of users accessing ECF modules.</li>
<li>The EXTERNAL REMOVE statement statement causes the entry for the named module to be removed from the module table.</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li>File Records In/On</li>
<li>Remember</li>
<li>Position</li>
<li>Sort Values</li>
<li>Reset Header/Trailer</li>
<li>Find and Print Count</li>
<li>Find All Values</li>
<li>For Each Value</li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the [[#FORMAT command|FORMAT]] command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus Web and SoftSpy debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>At breakpoints, the debuggers now [[#Subroutine or method display|display the subroutine or method]] where execution stopped.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

===Subroutine or method display===
When execution stops, as at breakpoints, the debuggers now display in the title bar the subroutine or method where execution stopped.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-10T21:45:28Z

ELowell: /* Debugger enhancements */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li><var>DISPLAY ECF</var> displays details from [[#Managing ECF tables more efficiently|ECF tables]], or the current status of users accessing ECF modules.</li>
<li>EXTERNAL REMOVE statement</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li>File Records In/On</li>
<li>Remember</li>
<li>Position</li>
<li>Sort Values</li>
<li>Reset Header/Trailer</li>
<li>Find and Print Count</li>
<li>Find All Values</li>
<li>For Each Value</li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the [[#FORMAT command|FORMAT]] command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus Web and SoftSpy debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>At breakpoints, the debuggers now [[#Subroutine or method display|display the subroutine or method]] where execution stopped.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

===Subroutine or method display===
When execution stops, as at breakpoints, the debuggers now display in the title bar the subroutine or method where execution stopped.

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-10T21:33:08Z

ELowell: /* New in this release */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new [[#AmIndependent|AmIndependent]] method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the [[#Support for copying Object class objects|copy and deepCopy methods]].
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>[[#Web Sockets|Janus Web Sockets]] are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits are now supported. The commit exit runs within the APSY, which is defined by the <var>COMMITX</var> parameter and uses normal APSY processing. </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li><var>DISPLAY ECF</var> displays details from [[#Managing ECF tables more efficiently|ECF tables]], or the current status of users accessing ECF modules.</li>
<li>EXTERNAL REMOVE statement</li>
</ul>
</td></tr>
<tr>
<td>Performance</td>
<td>
<ul>
<li>[[#MP/204 offload improvements|MP/204 offload improvements]] -- application code for these SOUL statements is now fully offloadable:
<ul>
<li>File Records In/On</li>
<li>Remember</li>
<li>Position</li>
<li>Sort Values</li>
<li>Reset Header/Trailer</li>
<li>Find and Print Count</li>
<li>Find All Values</li>
<li>For Each Value</li>
</ul>
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can [[#CA-Top Secret can disallow CCASTAT logins|disallow CCASTAT logins]].</li>
<li>[[#DEFUSER can specify a jobname not authorized to access M204|DEFUSER]] can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>The <var>MONITOR USERS</var> command output displays [[#New wait types for daemon/master waits|two new wait types]].</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>The new TIMEHH parameter on the [[#FORMAT command|FORMAT]] command of the AUDIT204 utility provides greater time stamp precision.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>[[#DISPLAY ECF|DISPLAY ECF]]</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>[[#ENQTIME|ENQTIME]]</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>[[#EVALOPT|EVALOPT]]</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>[[#MAXPRE, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and MAXSUBT]]</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>[[#NLDAPBUF|NLDAPBUF]]</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>[[#SERV4G|SERV4G]]</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>[[#WEBDFLT|WEBDFLT]]</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus Web and SoftSpy debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of [[#Access to exposed variables|variables exposed to local routines/methods]].</li>
<li>At breakpoints, the debuggers now [[#Subroutine or method display|display the subroutine or method]] where execution stopped.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li><var>[[#MPR, MBO, MCP, and RCV|MPR, MBO, MCP, and RCV]]</var> provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>[[#DKWTS and DKWTMICS|New system statistics]] DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>
</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-10T20:45:28Z

ELowell: /* Overview */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
The table below cites some highlights of Model 204 version 7.8. For a full list of features, refer to the Table of Contents.
 See also the [[#Compatibility Issues|Compatibility]] section for possible issues.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>
<tr>
<td>SOUL</td>
<td>
<ul>
<li>The new AmIndependent method returns TRUE for daemons spawned by RunIndependently.
</li>
<li>The Object class now supports the copy and deepCopy methods.
</li>
</ul>
</td></tr>

<tr>
<td>Janus Web</td>
<td>
<ul>
<li>Janus Web Sockets are now supported.</li>
</ul>
</td></tr>

<tr>
<td nowrap>Networking</td>
<td>
Note: The two-phase commit and commit exits features are licensed and purchased separately from Model 204.
<ul>
<li>Two-phase commit. A Model 204 online can now be configured to use two-phase commit (2PC). The Janus internal socket API is used for the calls to the coordinator. JANUS commands are used for all 2PC configuration. A new JANUS port type has been added, 2PC.</li>
<li>Commit exits.... </li>
</ul></td></tr>

<tr>
<td>ECF tables</td>
<td>
<ul>
<li><var>DISPLAY ECF</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
<li>EXTERNAL REMOVE statement</li>
</ul>
</td></tr>

<tr>
<td>Performance</td>
<td>
<ul>
<li>MP/204 offload improvements
- Application code for various SOUL statements is now fully offloadable: [list]
</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>CA-Top Secret can disallow CCASTAT logins.</li>
<li>DEFUSER can specify a jobname not authorized to access M204.</li>
</ul>
</td></tr>

<tr>
<td nowrap>System enhancements</td>
<td>
<ul>
<li>Two new wait types are viewable on the <var>MONITOR USERS</var> command output.</li>
</ul></td></tr>

<tr>
<td nowrap>AUDIT204 enhancements</td>
<td>
<ul>
<li>A new TIMEHH parameter on FORMAT command of the AUDIT204 utility provides more precision in time stamping.</li>
</ul></td></tr>

<tr>
<td nowrap>New commands</td>
<td>
<ul>
<li><var>DISPLAY ECF</var> displays details from ECF tables, or the current status of users accessing ECF modules.</li>
</ul></td></tr>

<tr>
<td nowrap>New parameters</td>
<td>
<ul>
<li><var>ENQTIME</var> specifies the number of milliseconds waited for each record locking retry wait.</li>
<li><var>EVALOPT</var> controls the cancellation of a request on truncation of string data.</li>
<li><var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.</li>
<li><var>NLDAPBUF</var> allows the number of LDAP buffers allocated during startup to be set in CCAIN.</li>
<li><var>SERV4G</var> allows testing of server tables that span a 4-gigabyte boundary.</li>
<li><var>WEBDFLT</var> changes the default JANUS WEB ALLOW rule back to ALLOW.</li>
</ul></td></tr>

<tr>
<td nowrap>Janus Web and SoftSpy debuggers</td>
<td>
<ul>
<li>The debuggers can now view or watch the values of variables exposed to local routines/methods.</li>
<li>At breakpoints, the debuggers now display in the title bar the subroutine or method where execution stopped.</li>
</ul></td>
</tr>

<tr>
<td nowrap>User/system statistics</td>
<td>
<ul>
<li>MPR, MBO, MCP, and RCV provide high water mark transaction information in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters.
</li>
<li>New system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.</li>
</ul></td></tr>

</table>

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-10T20:24:11Z

ELowell: /* Janus product enhancements */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Web Sockets===
Web Sockets are now supported in Janus Web Server.

The Web Socket protocol provides various advantages over the HTTP protocol:
<ul>
<li>Web Sockets allow full-duplex communication.</li>
<li>Efficient framing of payload data uses minimal overhead.</li>
<li>The Web Socket protocol is end-user extensible.</li>
<li>Most importantly, Web Sockets can be deployed completely within an existing HTTP/HTTPS framework.</li>
</ul>

To implement Web Sockets, you must enable the Janus Web port for Web Socket upgrades with the new
WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the
JANUS WEB rule for the URL.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the
WEBSOCKET and NOWEBSOCKET parameters, respectively.

For details on implementing Web Sockets, see the [[WebSocket_(Socket_function)|WebSocket]] wiki page.

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

WebSocket (Socket function)

2019-12-10T18:07:56Z

ELowell: /* Usage notes */

{{Template:Socket:WebSocket subtitle}}

This page is [[under construction]].
==Syntax==
{{Template:Socket:WebSocket syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%outSocket</th><td><var>Socket</var> object</td></tr>
<tr><th nowrap="true"><var>[%(Socket):]</var></th>
<td>The optional class name in parentheses denotes a [[Notation conventions for methods#Constructors|virtual constructor]]. See [[#Usage notes|"Usage notes"]], below, for more information about invoking a virtual constructor.</td></tr>
</table>
==Usage notes==
The HTTP protocol has been indispensible in creating the Internet as it exists today. It's still the core protocol for Web browsers and many other applications, whether on PCs, servers, laptops, or mobile devices. It has been extended over the years to accommodate demands for streaming video and sound, transfer of data files, and many other uses.

Yet HTTP still falls short in providing for efficient general purpose data transfer.

First, it is a half-duplex protocol, meaning that one side of the communication is always waiting for the other to reply. Second, the HTTP headers add considerable overhead to each interaction, wasting valuable bandwidth. Finally, each HTTP request requires its own TCP connection, which is generally closed after the server replies. This adds the overhead of connection establishment to every individual request. A typical web page requires several distinct http requests, each of which require separate TCP connections and its own set of http headers.

The Web Socket protocol was created to address these shortcomings. It is designed to allow full-duplex communication. Efficient framing of payload data uses minimal overhead. The protocol is end-user extensible. Most importantly, it can be deployed completely within an existing http/https framework. No firewall rule changes are required, and optional data masking avoids potential issues with caching proxies.

Web Sockets are supported in Janus Web Server as of Model 204 7.8.

The Janus Web implementation of Web Sockets requires some preparation before you can write your applications.

A Janus Web port is enabled for Web Socket communication with the WEBSOCKET parameter.
Likewise, an individual Janus Web rule can either allow or disallow Web Socket connections with the WEBSOCKET and NOWEBSOCKET parameters, respectively.

An http request for a Web Socket connection looks very similar to a normal http GET request. A special "upgrade" header in a request differentiates a Web Socket upgrade from all others. The upgrade request along with other unique headers advertise a request to negotiate a switch from HTTP to the Web Socket protocol.

When this negotiation completes successfully on a Janus Web Server thread, the connection immediately and irreversibly transitions to a Janus WebSocket connection.

From this point until the connection is closed, no Web method or $function calls are allowed. The server program must first call the WebSocket method to complete the transition to a Web Socket thread and thereafter may only call the Socket methods SendWebSocket, ReceiveWebSocket, and Close.

The WebSocket method will initiate acceptance of an upgrade of a Janus Web thread to a WebSocket thread. Once the WebSocket method returns, SendWebSocket, ReceiveWebSocket and Close are the only valid socket methods. No Janus Web $functions or methods are allowed and will result in request cancellation.

The Janus Web port must be enabled for Web Socket upgrades with the WEBSOCKET parameter. The WEBSOCKET option can be specified on either the port definition or the JANUS WEB rule for the URL.

Any other usage will result in request cancellation.

==Examples==
The following example sends a text message to the WebSocket client.
...

%sock = WebSocket
if %sock is null then
audittext Socket closed, status is {$STATUSD}
stop
end if

%op = %sock:ReceiveWebSocket(%wsi)
if %op eq 1 then
setText %wso = Received your text message of {%wsi:length} bytes.
%sock:SendWebSocket(%wso, %op, true)
end if

...


==See also==
{{Template:Socket:WebSocket footer}}

Release notes for Model 204 version 7.8

2019-12-10T02:33:30Z

ELowell:

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==Operating system and hardware requirements==

===Operating system requirements===

<ul>
<li>IBM z/OS versions supported:
<ul>
<li>All IBM supported releases up to and including z/OS 2.3. (For z/OS 2.2, see [[IBM z/OS 2.2 PTF requirement]].)</li>
Version 1.07 is sufficient for all functionality except for the following features:
<ul>
<li>zHPF support requires version [[IBM z/OS 2.1 compatibility issue|2.1]].</li>
<li>Large (1 MB) page support requires version 1.9.</li>
<li>Extended address volumes (EAV) requires version 1.12.</li>
</ul>
</li>
</ul>
On z/OS, Model 204 release 7.8 operates as an APF authorized load module, as required by many 7.8 features. 
To run Model 204 unauthorized, [[Contacting Rocket Software Technical Support|contact Technical Support]].

<li>IBM z/VM versions supported:
<ul>
<li>All IBM supported releases up to and including z/VM 6.4.</li>
</ul>
</li>

<li>IBM z/VSE versions supported:
<ul>
<li>All IBM supported releases up to and including z/VSE 6.1.</li>
</ul>
</li>
</ul>

===Hardware requirements===

In general, Model 204 version 7.8 requires the IBM z/890 or above processor.
However, the IBM z10 or above processor is required for the following features:
<ul>
<li>large (1 MB) page support</li>
<li>IBM's High Performance FICON (zHPF) support</li>
</ul>

===Connect★ compatibility with Model 204===

Connect★ version 7.5 or 7.7 is compatible with Model 204 version 7.8.

For more information on Connect★ installation, see the [[:Category:Connect*|Connect★ wiki pages]].

==SOUL (User Language) enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-07T00:51:30Z

ELowell:

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==SOUL enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
M204.0524: Maximum number (num) of parameter exceeded.
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if <var>SERV4G</var> is <code>X'FFFFF000'</code>, each ATB server will begin at <code>XX_FFFFF000</code>. If SERV4G is <code>X'FFFF0000'</code>, each ATB server will begin at <code>XX_FFFF0000</code>. <code>XX</code> is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the <var>[[SERVGA parameter|SERVGA]]</var> parameter.

For example, if you want VTBL to span the 4G boundary, you can use these settings: <code>SERV4G=X'FFFFF000'</code>, <code>SERVGA=X'00040000'</code>, and <code>LVTBL=200 (6400 bytes, X'1900')</code>. This will force each server's VTBL to begin at <code>XX_FFFFF000</code> and end at <code>XX+1_00000900</code>.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-07T00:10:39Z

ELowell:

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==SOUL enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
<code>M204.0524: Maximum number (num) of parameter exceeded.</code>
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if SERV4G is X'FFFFF000', each ATB server will begin at XX_FFFFF000. If SERV4G is X'FFFF0000', each ATB server will begin at XX_FFFF0000. XX is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the SERVGA parameter.

For example. if you want VTBL to span the 4G boundary, you can use these settings: SERV4G=X'FFFFF000', SERVGA=X'00040000', and LVTBL=200 (6400 bytes, X'1900'). This will force each server's VTBL to begin at XX_FFFFF000 and end at XX+1_00000900.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view-only===
In previous versions the <var>TCPOPTS</var> parameter, which identifies the type of IP addressing in use (v4 or v6), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in the following message:

 M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an undersized output page buffer, then in addition to the existing messages that inform the user of this failure:
 M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued:

 M204.1008: LOUTPB must be increased to at least <number> 

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-07T00:06:39Z

ELowell: /* Password delimiter enforced */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==SOUL enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
<code>M204.0524: Maximum number (num) of parameter exceeded.</code>
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if SERV4G is X'FFFFF000', each ATB server will begin at XX_FFFFF000. If SERV4G is X'FFFF0000', each ATB server will begin at XX_FFFF0000. XX is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the SERVGA parameter.

For example. if you want VTBL to span the 4G boundary, you can use these settings: SERV4G=X'FFFFF000', SERVGA=X'00040000', and LVTBL=200 (6400 bytes, X'1900'). This will force each server's VTBL to begin at XX_FFFFF000 and end at XX+1_00000900.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using <var>IFSTRTN</var> to log on to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon, which is the delimiter. For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued:

M204.2964: Password missing or too long 

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view only===
In previous versions the TCPOPTS parameter, which identifies the type of IP addressing in use ( v4 or v6 ), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in

M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an under sized output page buffer, then in addition to the existing messages that inform the user of this failure

M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued

M204.1008: LOUTPB must be increased to at least <number>

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-12-06T23:14:11Z

ELowell: /* New and changed messages */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==SOUL enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

===Optional output method parameters===
Prior to this release output parameters could not be optional or have default values. In this release output parameters can be specified as <var>Optional</var>, and a default value can be specified with <var>Default</var>. One related change is that if a <var>Len</var> value is specified with <var>Optional</var> or <var>Default</var> <var>Output</var>, it indicates the length of the hidden target for the output parameter if none was passed. For all other <var>Output</var> parameters, <var>Len</var> is meaningless, just as it was before Model 204 V7.8. The following is an example of the use of an optional output parameter:
function getRemote( -
%target is string len 32, %errorReason is string len 80 optional output -
) is float
...

In this example, if <code>%errorReason</code> is not specified in a call and then set to a value longer than 80 bytes it wil be truncated to 80 bytes. However, if a string of a different length is passed, the length of that string determines truncation behavior.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
<code>M204.0524: Maximum number (num) of parameter exceeded.</code>
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if SERV4G is X'FFFFF000', each ATB server will begin at XX_FFFFF000. If SERV4G is X'FFFF0000', each ATB server will begin at XX_FFFF0000. XX is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the SERVGA parameter.

For example. if you want VTBL to span the 4G boundary, you can use these settings: SERV4G=X'FFFFF000', SERVGA=X'00040000', and LVTBL=200 (6400 bytes, X'1900'). This will force each server's VTBL to begin at XX_FFFFF000 and end at XX+1_00000900.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using IFSTRTN to logon to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon - the delimiter.
For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued

M204.2964: Password missing or too long

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view only===
In previous versions the TCPOPTS parameter, which identifies the type of IP addressing in use ( v4 or v6 ), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in

M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an under sized output page buffer, then in addition to the existing messages that inform the user of this failure

M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued

M204.1008: LOUTPB must be increased to at least <number>

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==Notes for system manager and installer==
===CRAM SVC installation is deprecated===
The CRAM SVC installation has been deprecated as of version 7.5. Installation of CRAM-XDM is described as part of the [[Model 204 installation]].
===Authorization and maintenance zaps===
When you download Rocket M204 product object files, all relevant authorization keys and all current maintenance zaps are pre-applied to the object files as part of the download process.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Files, groups, and reference context

2019-11-11T17:56:21Z

ELowell: /* Two ways to open files and groups */

<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 here, Parallel Query Option/204 is described in detail in [[PQO: Overview of Parallel Query Option/204]] and the information it references. 

===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 [[PQO: Managing files and groups]].

===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==

The following "Commands for files and groups" table 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 page. For more information on the other commands in the "Commands for files and groups" table, see:
<ul>
<li>[[List of Model 204 parameters]] and [[List of Model 204 commands]]</li>

<li>[[PQO: Managing files and groups]]</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 [[CREATE command: Temporary group]] and [[CREATE command: Permanent group]]. 
<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, see [[#OPEN or OPENC statement|OPEN or OPENC statement]]. For a discussion of error handling, see [[#Error handling|Handling errors in file/group open statements]].</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>Permanent group </li>

<li>Multiple permanent group </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>System level resources</li>

<li>Application subsystems </li>
</ul>

See [[Defining the runtime environment (CCAIN)#Resource locking|Resource locking]] for information about resource locking.

====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]]. See [[Model 204 security features#File security|File security]] for details. 

===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.

<div id="openAndOpenC"></div>
<div id="OPEN statement and OPENC statement"></div>
<div id="OPEN or OPENC statement"></div> 

===Open statement and OpenC statement===



The <var>Open</var> and <var>OpenC</var> statements are useful for opening a file, either for subsequent requests, or
to allow the request to take actions based on the file parameters of the file.

The effect of executing the <var>Open</var>[<var>C</var>] statement, like any SOUL statement, takes place during evaluation of
the request. Therefore, if the file was not open during compilation, most SOUL statements, such as DML statements
(<var>Find</var>, <var>For</var>, <var>Store Record</var>, etc.) cannot refer to the file within the request.

Some SOUL operations, such as obtaining file parameters,
do not require a file to be opened during compilation.
Thus, after an <var>Open</var>[<var>C</var>] statement, the request can
obtain the status of the file by using the <var>[[$View|$View]]</var> function to return
the value of the <var>[[FISTAT parameter|FISTAT]]</var> parameter.

After a <var>Open</var>[<var>C</var>] statement, a subsequent request may access the data in the file.

The <var>Open</var> and <var>OpenC</var> statements are supported in remote context. The use of filename
synonyms is fully supported.

====Syntax====

The format of the <var>Open</var> or <var>OpenC</var> statement is:
{{Template:Open and OpenC statements syntax}}
Where:
<ul>
<li><var>Open</var> specifies that the specified file or group becomes the new default file or group context.
<var>OpenC</var> specifies that the previous default file or group is preserved when the specified file or group is opened.
Default files and groups are discussed later in this page.</li>

<li>The <var>File</var> keyword specifies that the file to be opened is a <var class="product">Model 204</var> file. </li>

<li>The <var>Perm</var> keyword specifies that the group to be opened is a <var class="product">Model 204</var> permanent group. </li>

<li>The <var>Temp</var> keyword specifies that the group to be opened is a <var class="product">Model 204</var> temporary group. </li>

<li>The <var>Group</var> keyword specifies that the file to be opened is a <var class="product">Model 204</var> group. </li>

<li>name is the name of the <var class="product">Model 204</var> file or group to be opened. The file or group name
can be provided in a %variable or as a quoted or unquoted string.</li>

<li>The <var>At</var> keyword specifies that the file to be opened is a remote file. Only individual files (or group members) can be specified using the <var>At</var> keyword. An entire group cannot be treated as a remote object. Thus none of the keywords <var>Perm</var>, <var>Temp</var>, or <var>Group</var> can be used with <var>At</var>.

A remote file can also be opened using a file synonym (without the <var>At</var> 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.

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 use the local file instead of the remote file with the same name.
</li>

<li>The <var>Password</var> clause specifies a valid password for the file or group to be opened. The password value can be provided in a %variable or as a quoted or unquoted string. </li>
</ul>

====Usage notes====
<ul>
<li>If the <var>Group</var> keyword is specified without a <var>Perm</var> or <var>Temp</var> 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.</li>

<li>The following message is produced for a <var class="product">SOUL</var> <var>Open</var>[<var>C</var>]
statement if the <var>Open</var> fails:
*** M204.1521: fileOrGroupName does not exist or requested access not authorized


Message 1521 is a counting error and when encountered during APSY processing invokes the APSY error procedure.
</ul>

===Handling errors in file/group open statements===

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 <var>[[$ErrMsg]]</var> 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 [[Horizon conversation interface]]. 

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><var>OPEN</var> command. The <var class="product">Model 204</var> file or group opened in the most recent OPEN command becomes the default.
<ul>
<li>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>If OPENC is issued instead of OPEN, a new default is not established and the previous default is preserved.</li>
</ul>
</li>
<li><var>DEFAULT</var> command. Using the DEFAULT command, you can specify either a file or a group.</li>
</li>
<li><var>IN</var> clause. The default file/group context during compilation of a request is used, throughout the request, as the file/group context for statements that do not have their own context specification. An IN clause on a <var>BEGIN</var> or <var>MORE</var> command sets a default context that remains in effect only for compilation of 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 nowrap>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 <var>Clear List</var>, <var>Find</var>, <var>For Record Number</var>, and <var>Store Record</var> 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] {filename | 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 <var>For Record Number</var> statement does not support remote files.

The location names of remote nodes are established with the DEFINE PROCESS command.
See [[PQO: Remote files and scattered groups]] 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 [[PQO: Managing files and groups]].

===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>Their IN clauses list the files in the same order.</li>

<li>Corresponding files in their IN clauses are both optional or both mandatory.</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>%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>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.
Note: The <var>For Record Number</var> option does not support remote files.</li>

<li>statement is one of the following:

:CLEAR LIST
:FIND ALL RECORDS
:FIND ALL VALUES
:For Record Number (FRN)
:STORE RECORD
</li></ul>

====Examples====

Suppose, for example, that the group <code>JANSALES</code> 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 <var>For Record Number</var> (<var>FRN</var>) 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 <code>A.CAT</code> statement finds a set of records from the default group <code>FISCAL</code>. 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 <code>HIST.MATCH</code> statement, all statements refer to <code>FISCAL</code>. 

The <code>HIST.MATCH</code> statement uses the account number from the current record in <code>FISCAL</code> to search the single file <code>HISTORY</code>. The <code>HIST.MATCH</code> through <code>HIST.CT</code> statements refer to the <code>HISTORY</code> 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><var>Find</var> statement</li>
<li>Sorted files</li>
<li><var>Sort</var> statement</li>
<li>Lists</li>
<li>Record numbers</li>
<li><var>For Each Value</var> statements</li>
<li>Field type variations within a group</li>
<li><var>For Each Record</var> 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 <var>For Each Record</var> 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 <var>For Each Record</var> 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 <var>For Each Record</var> 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 <var>For Record Number</var> 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 <code>For Each Record In Order By</code> form of the <var>For Each Record</var> 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 <var>BEGIN</var> 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 <var>For Each Record</var> 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.

The previous example 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 [[PQO: Remote files and scattered groups]] 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:
<ul>
<li>File is in group context </li>

<li>File is an optional group member</li>

<li>MAXFAIL parameter setting in CREATE GROUP is not exceeded</li>

<li>Node to which the file belongs has no uncommitted updates</li>
</ul></li>

<li>Invokes one of two ON units:

<ul>
<li>ON MISSING MEMBER </li>
<li>ON MISSING FILE </li>
</ul></li>

<li>Invokes the ON ERROR unit (if present) and cancels the request. </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>The member was not previously unavailable to the request. </li>

<li>The MISSING FILE condition is not raised. </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>The group member is considered disabled. </li>

<li>Subsequent references to the group in the same request for files at that server do not invoke ON MISSING MEMBER. </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 <var>For Each Record</var> 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>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>
</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>An operation in group context fails against a remote mandatory member.</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>
</ul>

When ON MISSING FILE is invoked, these consequences follow: 
<ul>
<li>The file or group is made unavailable to the request. </li>

<li>The file or group is disabled for the user. </li>

<li>All future references to the file or group in the same request cause the request to be canceled.
</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 <var>For Each Record</var> 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>If a subscripted field reference is used in a FOR loop, all occurrences of the field are transmitted from the server node.</li>
</ul>

A CODED field is decoded before being transmitted from the server node.

====OPTIMIZING FNV option====

Use the OPTIMIZING FNV option with the <var>For Each Record</var> 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>At the end of the FOR statement when the WHERE or WITH option is not present</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 <var>For Record Number</var> statement are supported in remote file and scattered group context, although <var>For Record Number</var> and <var>For Record Number In label</var> might have different results if you are working with records that are not locked. 

<var>For Record Number In label</var> refers to a preceding <var>For Each Record</var> statement. In Parallel Query Option/204, the records retrieved for the <var>For Each Record</var> loop are copied and sent to the client when the <var>For Each Record</var> statement is evaluated. If the records are not locked after the retrieval, by the time the <var>For Record Number In label</var> statement is executed, the record copy to which you are referring might no longer match the record at the server.

However, if you use <var>For Record Number</var> without <var>In label</var>, <var class="product">Model 204</var> locks the record to which you are referring and sends a copy to the client during <var>For Record Number</var> execution. Only the fields referred to by <var>For Record Number</var> are sent.

You can also use the OPTIMIZING FNV option with the <var>For Each Record Number</var> 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 <var>Opt FNV</var> option at the end of the statement.

===Using the FOR EACH VALUE statement===

All forms of the <var>For Each value</var> 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>Literal remote file specifications or file synonyms following dummy strings </li>

<li>The equality symbol (=) to point to the node on which the request is running</li>
</ul>

Invalid FILE$ argument formats for remote files are:
<ul>
<li>%Variables</li>

<li>Remote file specifications enclosed entirely in quotes ('STUDENTS AT NYC' is not valid) </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 [[PQO: Defining a PQO network]]). 

Valid LOCATION$ argument formats are: 
<ul>
<li>Literal location names</li>

<li>Literal location names following dummy strings </li>

<li>The equality symbol (=) to point to the node on which the request is running</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 <var>Find</var> statement to retrieve a set of records from a service node file. A client <var>For Each Record</var> 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 <var>For Each Record</var> 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 <var>For Each Record</var> 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 <var>For Record Number</var>. 
<blockquote class="note">
Note: Always lock a record before updating it. If an unlocked record set or list is being processed, use the <var>For Record Number</var> statement to lock the record, as shown below: 
%X = $CURREC
FOR RECORD NUMBER %X 
</blockquote>

<var>For Record Number</var> locks, copies, and sends the record to the client when the <var>For Record Number</var> statement is executed. Using <var>For Record Number In label</var> 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>$UPDFILE</li>

<li>$UPDFLD</li>

<li>$UUPDOVAL</li>

<li>$UPDREC</li>

<li>$UPDSTAT</li>

<li>$UPDSTMT</li>

<li>$UPDVAL</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>The group found set to which either statement applies is restricted to a single node — the found set was created by:
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 <var>Find</var> or <var>For Record Number</var> 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>IN $CURFILE, in temporary or permanent scattered group context</li>

<li>IN GROUP groupname (where the group update file is the implied storage file), in temporary scattered group context </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 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 (<var class="term">filename</var> At <var class="term">location</var>). Each of these functions returns the string:
filename At location

Where:

<var class="term">location</var> 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 <var class="term">name</var> 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 <var class="term">name</var> 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]]

Files, groups, and reference context

2019-11-11T17:52:07Z

ELowell: /* Two ways to open files and groups */

<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 here, Parallel Query Option/204 is described in detail in [[PQO: Overview of Parallel Query Option/204]] and the information it references. 

===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 [[PQO: Managing files and groups]].

===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==

The following "Commands for files and groups" table 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 page. For more information on the other commands in the "Commands for files and groups" table, see:
<ul>
<li>[[List of Model 204 parameters]] and [[List of Model 204 commands]]</li>

<li>[[PQO: Managing files and groups]]</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 [[CREATE command: Temporary group]] and [[CREATE command: Permanent group]]. 
<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, see [[#OPEN or OPENC statement|OPEN or OPENC statement]]. For a discussiong of error handling, see [[#Error handling|Handling errors in file/group open statements]].</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>Permanent group </li>

<li>Multiple permanent group </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>System level resources</li>

<li>Application subsystems </li>
</ul>

See [[Defining the runtime environment (CCAIN)#Resource locking|Resource locking]] for information about resource locking.

====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]]. See [[Model 204 security features#File security|File security]] for details. 

===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.

<div id="openAndOpenC"></div>
<div id="OPEN statement and OPENC statement"></div>
<div id="OPEN or OPENC statement"></div> 

===Open statement and OpenC statement===



The <var>Open</var> and <var>OpenC</var> statements are useful for opening a file, either for subsequent requests, or
to allow the request to take actions based on the file parameters of the file.

The effect of executing the <var>Open</var>[<var>C</var>] statement, like any SOUL statement, takes place during evaluation of
the request. Therefore, if the file was not open during compilation, most SOUL statements, such as DML statements
(<var>Find</var>, <var>For</var>, <var>Store Record</var>, etc.) cannot refer to the file within the request.

Some SOUL operations, such as obtaining file parameters,
do not require a file to be opened during compilation.
Thus, after an <var>Open</var>[<var>C</var>] statement, the request can
obtain the status of the file by using the <var>[[$View|$View]]</var> function to return
the value of the <var>[[FISTAT parameter|FISTAT]]</var> parameter.

After a <var>Open</var>[<var>C</var>] statement, a subsequent request may access the data in the file.

The <var>Open</var> and <var>OpenC</var> statements are supported in remote context. The use of filename
synonyms is fully supported.

====Syntax====

The format of the <var>Open</var> or <var>OpenC</var> statement is:
{{Template:Open and OpenC statements syntax}}
Where:
<ul>
<li><var>Open</var> specifies that the specified file or group becomes the new default file or group context.
<var>OpenC</var> specifies that the previous default file or group is preserved when the specified file or group is opened.
Default files and groups are discussed later in this page.</li>

<li>The <var>File</var> keyword specifies that the file to be opened is a <var class="product">Model 204</var> file. </li>

<li>The <var>Perm</var> keyword specifies that the group to be opened is a <var class="product">Model 204</var> permanent group. </li>

<li>The <var>Temp</var> keyword specifies that the group to be opened is a <var class="product">Model 204</var> temporary group. </li>

<li>The <var>Group</var> keyword specifies that the file to be opened is a <var class="product">Model 204</var> group. </li>

<li>name is the name of the <var class="product">Model 204</var> file or group to be opened. The file or group name
can be provided in a %variable or as a quoted or unquoted string.</li>

<li>The <var>At</var> keyword specifies that the file to be opened is a remote file. Only individual files (or group members) can be specified using the <var>At</var> keyword. An entire group cannot be treated as a remote object. Thus none of the keywords <var>Perm</var>, <var>Temp</var>, or <var>Group</var> can be used with <var>At</var>.

A remote file can also be opened using a file synonym (without the <var>At</var> 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.

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 use the local file instead of the remote file with the same name.
</li>

<li>The <var>Password</var> clause specifies a valid password for the file or group to be opened. The password value can be provided in a %variable or as a quoted or unquoted string. </li>
</ul>

====Usage notes====
<ul>
<li>If the <var>Group</var> keyword is specified without a <var>Perm</var> or <var>Temp</var> 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.</li>

<li>The following message is produced for a <var class="product">SOUL</var> <var>Open</var>[<var>C</var>]
statement if the <var>Open</var> fails:
*** M204.1521: fileOrGroupName does not exist or requested access not authorized


Message 1521 is a counting error and when encountered during APSY processing invokes the APSY error procedure.
</ul>

===Handling errors in file/group open statements===

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 <var>[[$ErrMsg]]</var> 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 [[Horizon conversation interface]]. 

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><var>OPEN</var> command. The <var class="product">Model 204</var> file or group opened in the most recent OPEN command becomes the default.
<ul>
<li>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>If OPENC is issued instead of OPEN, a new default is not established and the previous default is preserved.</li>
</ul>
</li>
<li><var>DEFAULT</var> command. Using the DEFAULT command, you can specify either a file or a group.</li>
</li>
<li><var>IN</var> clause. The default file/group context during compilation of a request is used, throughout the request, as the file/group context for statements that do not have their own context specification. An IN clause on a <var>BEGIN</var> or <var>MORE</var> command sets a default context that remains in effect only for compilation of 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 nowrap>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 <var>Clear List</var>, <var>Find</var>, <var>For Record Number</var>, and <var>Store Record</var> 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] {filename | 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 <var>For Record Number</var> statement does not support remote files.

The location names of remote nodes are established with the DEFINE PROCESS command.
See [[PQO: Remote files and scattered groups]] 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 [[PQO: Managing files and groups]].

===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>Their IN clauses list the files in the same order.</li>

<li>Corresponding files in their IN clauses are both optional or both mandatory.</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>%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>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.
Note: The <var>For Record Number</var> option does not support remote files.</li>

<li>statement is one of the following:

:CLEAR LIST
:FIND ALL RECORDS
:FIND ALL VALUES
:For Record Number (FRN)
:STORE RECORD
</li></ul>

====Examples====

Suppose, for example, that the group <code>JANSALES</code> 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 <var>For Record Number</var> (<var>FRN</var>) 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 <code>A.CAT</code> statement finds a set of records from the default group <code>FISCAL</code>. 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 <code>HIST.MATCH</code> statement, all statements refer to <code>FISCAL</code>. 

The <code>HIST.MATCH</code> statement uses the account number from the current record in <code>FISCAL</code> to search the single file <code>HISTORY</code>. The <code>HIST.MATCH</code> through <code>HIST.CT</code> statements refer to the <code>HISTORY</code> 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><var>Find</var> statement</li>
<li>Sorted files</li>
<li><var>Sort</var> statement</li>
<li>Lists</li>
<li>Record numbers</li>
<li><var>For Each Value</var> statements</li>
<li>Field type variations within a group</li>
<li><var>For Each Record</var> 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 <var>For Each Record</var> 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 <var>For Each Record</var> 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 <var>For Each Record</var> 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 <var>For Record Number</var> 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 <code>For Each Record In Order By</code> form of the <var>For Each Record</var> 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 <var>BEGIN</var> 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 <var>For Each Record</var> 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.

The previous example 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 [[PQO: Remote files and scattered groups]] 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:
<ul>
<li>File is in group context </li>

<li>File is an optional group member</li>

<li>MAXFAIL parameter setting in CREATE GROUP is not exceeded</li>

<li>Node to which the file belongs has no uncommitted updates</li>
</ul></li>

<li>Invokes one of two ON units:

<ul>
<li>ON MISSING MEMBER </li>
<li>ON MISSING FILE </li>
</ul></li>

<li>Invokes the ON ERROR unit (if present) and cancels the request. </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>The member was not previously unavailable to the request. </li>

<li>The MISSING FILE condition is not raised. </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>The group member is considered disabled. </li>

<li>Subsequent references to the group in the same request for files at that server do not invoke ON MISSING MEMBER. </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 <var>For Each Record</var> 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>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>
</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>An operation in group context fails against a remote mandatory member.</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>
</ul>

When ON MISSING FILE is invoked, these consequences follow: 
<ul>
<li>The file or group is made unavailable to the request. </li>

<li>The file or group is disabled for the user. </li>

<li>All future references to the file or group in the same request cause the request to be canceled.
</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 <var>For Each Record</var> 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>If a subscripted field reference is used in a FOR loop, all occurrences of the field are transmitted from the server node.</li>
</ul>

A CODED field is decoded before being transmitted from the server node.

====OPTIMIZING FNV option====

Use the OPTIMIZING FNV option with the <var>For Each Record</var> 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>At the end of the FOR statement when the WHERE or WITH option is not present</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 <var>For Record Number</var> statement are supported in remote file and scattered group context, although <var>For Record Number</var> and <var>For Record Number In label</var> might have different results if you are working with records that are not locked. 

<var>For Record Number In label</var> refers to a preceding <var>For Each Record</var> statement. In Parallel Query Option/204, the records retrieved for the <var>For Each Record</var> loop are copied and sent to the client when the <var>For Each Record</var> statement is evaluated. If the records are not locked after the retrieval, by the time the <var>For Record Number In label</var> statement is executed, the record copy to which you are referring might no longer match the record at the server.

However, if you use <var>For Record Number</var> without <var>In label</var>, <var class="product">Model 204</var> locks the record to which you are referring and sends a copy to the client during <var>For Record Number</var> execution. Only the fields referred to by <var>For Record Number</var> are sent.

You can also use the OPTIMIZING FNV option with the <var>For Each Record Number</var> 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 <var>Opt FNV</var> option at the end of the statement.

===Using the FOR EACH VALUE statement===

All forms of the <var>For Each value</var> 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>Literal remote file specifications or file synonyms following dummy strings </li>

<li>The equality symbol (=) to point to the node on which the request is running</li>
</ul>

Invalid FILE$ argument formats for remote files are:
<ul>
<li>%Variables</li>

<li>Remote file specifications enclosed entirely in quotes ('STUDENTS AT NYC' is not valid) </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 [[PQO: Defining a PQO network]]). 

Valid LOCATION$ argument formats are: 
<ul>
<li>Literal location names</li>

<li>Literal location names following dummy strings </li>

<li>The equality symbol (=) to point to the node on which the request is running</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 <var>Find</var> statement to retrieve a set of records from a service node file. A client <var>For Each Record</var> 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 <var>For Each Record</var> 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 <var>For Each Record</var> 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 <var>For Record Number</var>. 
<blockquote class="note">
Note: Always lock a record before updating it. If an unlocked record set or list is being processed, use the <var>For Record Number</var> statement to lock the record, as shown below: 
%X = $CURREC
FOR RECORD NUMBER %X 
</blockquote>

<var>For Record Number</var> locks, copies, and sends the record to the client when the <var>For Record Number</var> statement is executed. Using <var>For Record Number In label</var> 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>$UPDFILE</li>

<li>$UPDFLD</li>

<li>$UUPDOVAL</li>

<li>$UPDREC</li>

<li>$UPDSTAT</li>

<li>$UPDSTMT</li>

<li>$UPDVAL</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>The group found set to which either statement applies is restricted to a single node — the found set was created by:
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 <var>Find</var> or <var>For Record Number</var> 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>IN $CURFILE, in temporary or permanent scattered group context</li>

<li>IN GROUP groupname (where the group update file is the implied storage file), in temporary scattered group context </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 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 (<var class="term">filename</var> At <var class="term">location</var>). Each of these functions returns the string:
filename At location

Where:

<var class="term">location</var> 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 <var class="term">name</var> 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 <var class="term">name</var> 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]]

Release notes for Model 204 version 7.8

2019-11-01T22:24:29Z

ELowell: Changed https links to relative links

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==SOUL enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[[RunIndependently_(Daemon_subroutine)|RunIndependently]]</var>. (The action of <var>[[AmDaemon_(Daemon_property)|AmDaemon]]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[[$ProcOpn|$ProcOpn]]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[[MONITOR_command|MONITOR]] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [[CA-Top_Secret_interface|CA-Top Secret]] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [[CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN|TOPSPARM]]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[[CUSTOM_parameter|CUSTOM]]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [[Program_Communication_facilities#LISTEN_call|TCP listen]] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [[XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters)|XMLSCREEN]] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [[$Web_Input_Content|$Web_Input_Content]] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [[Full-screen_feature#DEBLANK_or_NODEBLANK_option|DEBLANK]] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [[SSLIBSIZE_(JANUS_DEFINE_parameter)|SSLIBSIZE]] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [[CUSTOM_parameter#Using_CUSTOM.3D.2818.29|CUSTOM=18]].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [[Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29|X3270OUT]] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
<code>M204.0524: Maximum number (num) of parameter exceeded.</code>
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if SERV4G is X'FFFFF000', each ATB server will begin at XX_FFFFF000. If SERV4G is X'FFFF0000', each ATB server will begin at XX_FFFF0000. XX is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the SERVGA parameter.

For example. if you want VTBL to span the 4G boundary, you can use these settings: SERV4G=X'FFFFF000', SERVGA=X'00040000', and LVTBL=200 (6400 bytes, X'1900'). This will force each server's VTBL to begin at XX_FFFFF000 and end at XX+1_00000900.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[[WEBDFLT_parameter|WEBDFLT]]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [[System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints|RESTART and RESTARTS]].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [[MONITOR_command|MONITOR]] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using IFSTRTN to logon to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon - the delimiter.
For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued

M204.2964: Password missing or too long

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view only===
In previous versions the TCPOPTS parameter, which identifies the type of IP addressing in use ( v4 or v6 ), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in

M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an under sized output page buffer, then in addition to the existing messages that inform the user of this failure

M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued

M204.1008: LOUTPB must be increased to at least <number>

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-11-01T21:34:24Z

ELowell: /* Managing ECF tables more efficiently */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==SOUL enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[http://m204wiki.rocketsoftware.com/index.php/RunIndependently_(Daemon_subroutine) RunIndependently]</var>. (The action of <var>[https://m204wiki.rocketsoftware.com/index.php/AmDaemon_(Daemon_property) AmDaemon]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[https://m204wiki.rocketsoftware.com/index.php/$ProcOpn $ProcOpn]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$statusd</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$statusd</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[https://m204wiki.rocketsoftware.com/index.php/MONITOR_command MONITOR] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface CA-Top Secret] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN TOPSPARM]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[https://m204wiki.rocketsoftware.com/index.php/CUSTOM_parameter CUSTOM]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [https://m204wiki.rocketsoftware.com/index.php/Program_Communication_facilities#LISTEN_call TCP_listen] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [https://m204wiki.rocketsoftware.com/index.php/XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters) XMLSCREEN] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [https://m204wiki.rocketsoftware.com/index.php/$Web_Input_Content $Web_Input_Content] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [https://m204wiki.rocketsoftware.com/index.php/Full-screen_feature#DEBLANK_or_NODEBLANK_option DEBLANK] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [https://m204wiki.rocketsoftware.com/index.php/SSLIBSIZE_(JANUS_DEFINE_parameter) SSLIBSIZE] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [https://m204wiki.rocketsoftware.com/index.php/CUSTOM_parameter#Using_CUSTOM.3D.2818.29 CUSTOM=18].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [https://m204wiki.rocketsoftware.com/index.php/Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29 X3270OUT] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
<code>M204.0524: Maximum number (num) of parameter exceeded.</code>
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if SERV4G is X'FFFFF000', each ATB server will begin at XX_FFFFF000. If SERV4G is X'FFFF0000', each ATB server will begin at XX_FFFF0000. XX is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the SERVGA parameter.

For example. if you want VTBL to span the 4G boundary, you can use these settings: SERV4G=X'FFFFF000', SERVGA=X'00040000', and LVTBL=200 (6400 bytes, X'1900'). This will force each server's VTBL to begin at XX_FFFFF000 and end at XX+1_00000900.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[https://m204wiki.rocketsoftware.com/index.php/WEBDFLT_parameter WEBDFLT]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [https://m204wiki.rocketsoftware.com/index.php/System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints RESTART and RESTARTS].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [https://m204wiki.rocketsoftware.com/index.php/MONITOR_command MONITOR] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[https://m204wiki.rocketsoftware.com/index.php/Using_variables_and_values_in_computation#Declare_statements_for_.25variables declaration statement].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using IFSTRTN to logon to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon - the delimiter.
For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued

M204.2964: Password missing or too long

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view only===
In previous versions the TCPOPTS parameter, which identifies the type of IP addressing in use ( v4 or v6 ), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in

M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an under sized output page buffer, then in addition to the existing messages that inform the user of this failure

M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued

M204.1008: LOUTPB must be increased to at least <number>

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-11-01T21:18:30Z

ELowell: small cleanup for formatting, consistency

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==SOUL enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[http://m204wiki.rocketsoftware.com/index.php/RunIndependently_(Daemon_subroutine) RunIndependently]</var>. (The action of <var>[https://m204wiki.rocketsoftware.com/index.php/AmDaemon_(Daemon_property) AmDaemon]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[https://m204wiki.rocketsoftware.com/index.php/$ProcOpn $ProcOpn]</var> now supports the opening of a procedure with an all-numeric name, and including a leading zero, such as:

%result = $procOpn('0123', 'MYFILE')

Support for such procedure names was initially introduced at V7.7, and this feature of <var>$ProcOpn</var> is also enabled in V7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, an Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the <var>EXTERNAL MODULE</var> statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An <var>EXTERNAL REMOVE</var> statement will return <code>$status/$status</code> values of <code>0/0</code>, and most other status values that can be returned by the <var>EXTERNAL REMOVE</var> statement are already documented in the ECF return codes table. If an <var>EXTERNAL REMOVE</var> is attempted against a module that is currently being called (in use), then <code>$status/$status</code> will return the values <code>20/1</code> (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[https://m204wiki.rocketsoftware.com/index.php/MONITOR_command MONITOR] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous versions. So in the following example, a particular snap header under v7.7 or previous versions would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous versions, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface CA-Top Secret] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN TOPSPARM]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[https://m204wiki.rocketsoftware.com/index.php/CUSTOM_parameter CUSTOM]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled in V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled in V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [https://m204wiki.rocketsoftware.com/index.php/Program_Communication_facilities#LISTEN_call TCP_listen] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled in V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [https://m204wiki.rocketsoftware.com/index.php/XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters) XMLSCREEN] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [https://m204wiki.rocketsoftware.com/index.php/$Web_Input_Content $Web_Input_Content] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [https://m204wiki.rocketsoftware.com/index.php/Full-screen_feature#DEBLANK_or_NODEBLANK_option DEBLANK] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [https://m204wiki.rocketsoftware.com/index.php/SSLIBSIZE_(JANUS_DEFINE_parameter) SSLIBSIZE] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [https://m204wiki.rocketsoftware.com/index.php/CUSTOM_parameter#Using_CUSTOM.3D.2818.29 CUSTOM=18].

This changed is enabled in V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled in V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled in V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled in V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled in V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [https://m204wiki.rocketsoftware.com/index.php/Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29 X3270OUT] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled in V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled in v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
<code>M204.0524: Maximum number (num) of parameter exceeded.</code>
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if SERV4G is X'FFFFF000', each ATB server will begin at XX_FFFFF000. If SERV4G is X'FFFF0000', each ATB server will begin at XX_FFFF0000. XX is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the SERVGA parameter.

For example. if you want VTBL to span the 4G boundary, you can use these settings: SERV4G=X'FFFFF000', SERVGA=X'00040000', and LVTBL=200 (6400 bytes, X'1900'). This will force each server's VTBL to begin at XX_FFFFF000 and end at XX+1_00000900.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[https://m204wiki.rocketsoftware.com/index.php/WEBDFLT_parameter WEBDFLT]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [https://m204wiki.rocketsoftware.com/index.php/System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints RESTART and RESTARTS].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [https://m204wiki.rocketsoftware.com/index.php/MONITOR_command MONITOR] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[https://m204wiki.rocketsoftware.com/index.php/Using_variables_and_values_in_computation#Declare_statements_for_.25variables declaration statement].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using IFSTRTN to logon to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon - the delimiter.
For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued

M204.2964: Password missing or too long

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled in V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view only===
In previous versions the TCPOPTS parameter, which identifies the type of IP addressing in use ( v4 or v6 ), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in

M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous versions it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled in v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an under sized output page buffer, then in addition to the existing messages that inform the user of this failure

M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued

M204.1008: LOUTPB must be increased to at least <number>

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-11-01T18:26:20Z

ELowell:

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==SOUL enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[http://m204wiki.rocketsoftware.com/index.php/RunIndependently_(Daemon_subroutine) RunIndependently]</var>. (The action of <var>[https://m204wiki.rocketsoftware.com/index.php/AmDaemon_(Daemon_property) AmDaemon]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[https://m204wiki.rocketsoftware.com/index.php/$ProcOpn $ProcOpn]</var> now supports the opening of a procedure with an all numeric name, and including a leading zero, e.g.

%result = $procOpn('0123', 'MYFILE')

Support for such procedures names was initially introduced at v7.7, and this feature of <var>$ProcOpn</var> is also enabled within v7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code:
 begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end 

will now compile and run successfully, since this syntax:

if (%isValid) then 

is logically equivalent to this:

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, and Object object can be copied as follows:
 begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end 

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration. So, for example, the following code:
 begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end 

will produce this result:

 %(Local):(%func)=red 

whereas previously this line:

 %func = (colour):red 

would have been rejected with this message:

MSIR.0993: Assignment invalid: mismatch between method and method variable 

This change is enabled in V7.7 with the application of zap 77z128.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the following syntax:

EXTERNAL REMOVE modulename

This statement causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the EXTERNAL MODULE statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

An EXTERNAL REMOVE statement will return $status/$statusd values of 0/0, and most other status values that can be returned by the EXTERNAL REMOVE statement are already documented in the ECF return codes table. If an EXTERNAL REMOVE is attempted against a module that is currently being called (in use), then $status/$statusd will return the values 20/1 (module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[https://m204wiki.rocketsoftware.com/index.php/MONITOR_command MONITOR] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown in normal format, rather than in julian format as in previous releases. So in the following example, a particular snap header under v7.7 or previous releases would show as:

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1 

whereas the same snap header under v7.8 would show as:

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1 

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous releases, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface CA-Top Secret] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN TOPSPARM]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[https://m204wiki.rocketsoftware.com/index.php/CUSTOM_parameter CUSTOM]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled within V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled within V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [https://m204wiki.rocketsoftware.com/index.php/Program_Communication_facilities#LISTEN_call TCP_listen] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled within V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [https://m204wiki.rocketsoftware.com/index.php/XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters) XMLSCREEN] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [https://m204wiki.rocketsoftware.com/index.php/$Web_Input_Content $Web_Input_Content] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [https://m204wiki.rocketsoftware.com/index.php/Full-screen_feature#DEBLANK_or_NODEBLANK_option DEBLANK] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [https://m204wiki.rocketsoftware.com/index.php/SSLIBSIZE_(JANUS_DEFINE_parameter) SSLIBSIZE] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [https://m204wiki.rocketsoftware.com/index.php/CUSTOM_parameter#Using_CUSTOM.3D.2818.29 CUSTOM=18].

This changed is enabled within V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled within V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled within V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled within V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled within V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [https://m204wiki.rocketsoftware.com/index.php/Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29 X3270OUT] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77Z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled within V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled within v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77Z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
<code>M204.0524: Maximum number (num) of parameter exceeded.</code>
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if SERV4G is X'FFFFF000', each ATB server will begin at XX_FFFFF000. If SERV4G is X'FFFF0000', each ATB server will begin at XX_FFFF0000. XX is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the SERVGA parameter.

For example. if you want VTBL to span the 4G boundary, you can use these settings: SERV4G=X'FFFFF000', SERVGA=X'00040000', and LVTBL=200 (6400 bytes, X'1900'). This will force each server's VTBL to begin at XX_FFFFF000 and end at XX+1_00000900.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[https://m204wiki.rocketsoftware.com/index.php/WEBDFLT_parameter WEBDFLT]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77Z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [https://m204wiki.rocketsoftware.com/index.php/System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints RESTART and RESTARTS].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [https://m204wiki.rocketsoftware.com/index.php/MONITOR_command MONITOR] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[https://m204wiki.rocketsoftware.com/index.php/Using_variables_and_values_in_computation#Declare_statements_for_.25variables declaration statement].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77Z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using IFSTRTN to logon to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon - the delimiter.
For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued

M204.2964: Password missing or too long

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled within V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view only===
In previous releases the TCPOPTS parameter, which identifies the type of IP addressing in use ( v4 or v6 ), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in

M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous releases it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled within v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an under sized output page buffer, then in addition to the existing messages that inform the user of this failure

M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued

M204.1008: LOUTPB must be increased to at least <number>

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-10-16T16:36:06Z

ELowell: /* DISPLAY ECF */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==SOUL enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[http://m204wiki.rocketsoftware.com/index.php/RunIndependently_(Daemon_subroutine) RunIndependently]</var>. (The action of <var>[https://m204wiki.rocketsoftware.com/index.php/AmDaemon_(Daemon_property) AmDaemon]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[https://m204wiki.rocketsoftware.com/index.php/$ProcOpn $ProcOpn]</var> now supports the opening of a procedure with an all numeric name, and including a leading zero, e.g.

%result = $procOpn('0123', 'MYFILE')

Support for such procedures names was initially introduced at v7.7, and this feature of <var>$ProcOpn</var> is also enabled within v7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code

begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end

will now compile and run successfully, as

if (%isValid) then 

is logically equivalent to

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, and Object object can be copied as follows

begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration.So for example the following code

begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end

will produce the result

%(Local):(%func)=red

whereas previously the line

%func = (colour):red

would have been rejected with the message

MSIR.0993: Assignment invalid: mismatch between method and method variable

This change is enabled in V7.7 with the application of zap 77z128.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the syntax

EXTERNAL REMOVE modulename

This causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the EXTERNAL MODULE statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

A EXTERNAL REMOVE statement will return $status/$statusd values of 0/0, and most other status values that can be returned by the EXTERNAL REMOVE statement are already documented in the ECF return codes table. If an EXTERNAL REMOVE is attempted against a module that is currently being called ( in use ), then $status/$statusd will return the values 20/1 ( module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[https://m204wiki.rocketsoftware.com/index.php/MONITOR_command MONITOR] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown normal format, rather than in julian format as in previous releases. Thus in the following example a particular snap header under v7.7 or previous releases would show as

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1

whereas the same snap header under v7.8 would show as

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous releases, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface CA-Top Secret] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN TOPSPARM]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[https://m204wiki.rocketsoftware.com/index.php/CUSTOM_parameter CUSTOM]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled within V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled within V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [https://m204wiki.rocketsoftware.com/index.php/Program_Communication_facilities#LISTEN_call TCP_listen] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled within V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [https://m204wiki.rocketsoftware.com/index.php/XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters) XMLSCREEN] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [https://m204wiki.rocketsoftware.com/index.php/$Web_Input_Content $Web_Input_Content] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [https://m204wiki.rocketsoftware.com/index.php/Full-screen_feature#DEBLANK_or_NODEBLANK_option DEBLANK] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [https://m204wiki.rocketsoftware.com/index.php/SSLIBSIZE_(JANUS_DEFINE_parameter) SSLIBSIZE] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [https://m204wiki.rocketsoftware.com/index.php/CUSTOM_parameter#Using_CUSTOM.3D.2818.29 CUSTOM=18].

This changed is enabled within V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled within V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled within V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled within V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled within V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [https://m204wiki.rocketsoftware.com/index.php/Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29 X3270OUT] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77Z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF <var class="term">function</var> LIKE <var class="term">?</var> (where <var class="term">?</var> is a valid pattern) displays details for entities that match the specified pattern. The function is either M (modules), N (names), or U (users), and it defaults to U. So for example:

D ECF U L A
or
D ECF U L A*

displays details of ECF users whose names begin with A.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled within V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled within v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77Z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
<code>M204.0524: Maximum number (num) of parameter exceeded.</code>
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if SERV4G is X'FFFFF000', each ATB server will begin at XX_FFFFF000. If SERV4G is X'FFFF0000', each ATB server will begin at XX_FFFF0000. XX is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the SERVGA parameter.

For example. if you want VTBL to span the 4G boundary, you can use these settings: SERV4G=X'FFFFF000', SERVGA=X'00040000', and LVTBL=200 (6400 bytes, X'1900'). This will force each server's VTBL to begin at XX_FFFFF000 and end at XX+1_00000900.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[https://m204wiki.rocketsoftware.com/index.php/WEBDFLT_parameter WEBDFLT]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77Z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [https://m204wiki.rocketsoftware.com/index.php/System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints RESTART and RESTARTS].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [https://m204wiki.rocketsoftware.com/index.php/MONITOR_command MONITOR] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[https://m204wiki.rocketsoftware.com/index.php/Using_variables_and_values_in_computation#Declare_statements_for_.25variables declaration statement].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77Z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using IFSTRTN to logon to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon - the delimiter.
For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued

M204.2964: Password missing or too long

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled within V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view only===
In previous releases the TCPOPTS parameter, which identifies the type of IP addressing in use ( v4 or v6 ), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in

M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous releases it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled within v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an under sized output page buffer, then in addition to the existing messages that inform the user of this failure

M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued

M204.1008: LOUTPB must be increased to at least <number>

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]

Release notes for Model 204 version 7.8

2019-09-25T15:58:04Z

ELowell: /* Maximum RBSIZE setting increased */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

******THIS IS A DRAFT DOCUMENT.******

These release notes list the enhancements and other changes contained in Model 204 version 7.8, which is still in development. Until the commercial release of the software, Rocket reserves the right to add to, remove, or change anything described herein.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.8 release.
Before beginning your installation, please read through this information about product installation and changes.

==SOUL enhancements==
===AmIndependent method===
The <var>AmIndependent</var> method returns TRUE for daemons spawned by <var>[http://m204wiki.rocketsoftware.com/index.php/RunIndependently_(Daemon_subroutine) RunIndependently]</var>. (The action of <var>[https://m204wiki.rocketsoftware.com/index.php/AmDaemon_(Daemon_property) AmDaemon]</var> remains unchanged.)

The following table shows the values returned by <var>AmIndependent</var> versus <var>AmDaemon</var> for different daemon types:
<table>
<th>Type</th>
<th>AmDaemon</th>
<th>AmIndependent</th>
<tr>
<td>$COMBG</td>
<td>False</td>
<td>False</td>
</tr>
<tr>
<td>Independent daemon</td>
<td>False</td>
<td>True</td></tr>
<tr>
<td>Other daemon</td>
<td>True</td>
<td>False</td>
</tr>
<tr>
<td>Web, etc.</td>
<td>False</td>
<td>False</td>
</tr></table>

===$ProcOpn===
<var>[https://m204wiki.rocketsoftware.com/index.php/$ProcOpn $ProcOpn]</var> now supports the opening of a procedure with an all numeric name, and including a leading zero, e.g.

%result = $procOpn('0123', 'MYFILE')

Support for such procedures names was initially introduced at v7.7, and this feature of <var>$ProcOpn</var> is also enabled within v7.7 with the application of zap 77z054.

===Allow parentheses to surround a boolean enumeration object===
The following sample code

begin
variables are undefined
%isValid is boolean initial (True)
if (%isValid) then
print 'in IF'
end if
end

will now compile and run successfully, as

if (%isValid) then 

is logically equivalent to

if %isValid then 

Prior to V7.8 the presence of parentheses surrounding the boolean enumeration object would have caused a compilation error. This change is enabled in V7.7 with the application of zap 77z370.

===Support for copying Object class objects===
The Object class now supports the copy and deepCopy methods. For example, and Object object can be copied as follows

begin
%x is object object
%y is object object
%y = new
%x = %y:copy
end

This change is enabled in v7.7 with the application of zap 77z076, and within V7.6 with the application of zap 76z412.

===Assignment of enumeration values to method variables===
Enumerations values can now be assigned to method variables whose result is an enumeration.So for example the following code

begin
enumeration colour
public
value red
value white
value blue
end public
end enumeration
%func is function getColour is enumeration colour
local function getColour is enumeration colour
return blue
end function
%func = getColour
%func = (colour):red
printText {~=%(Local):(%func)}
end

will produce the result

%(Local):(%func)=red

whereas previously the line

%func = (colour):red

would have been rejected with the message

MSIR.0993: Assignment invalid: mismatch between method and method variable

This change is enabled in V7.7 with the application of zap 77z128.

==External Call Facility enhancements==
===Managing ECF tables more efficiently===
The are two new features to help manage ECF tables more efficiently, avoid conditions where the table can fill, and prevent the definition of further entities.

The first feature is the new <var>DISPLAY ECF</var> command, which displays the contents of ECF tables and also the current status of users accessing ECF modules. See more details of the <var>[[#DISPLAY ECF|DISPLAY ECF]]</var> command below.

The second feature is a new <var>EXTERNAL REMOVE</var> statement with the syntax

EXTERNAL REMOVE modulename

This causes the entry for the named module to be removed from the module table. The table entry is then placed on a free chain of entries and can be reused by issuing the EXTERNAL MODULE statement. This allows the module table to be managed with redundant entries removed, without having to recycle the ONLINE.

A EXTERNAL REMOVE statement will return $status/$statusd values of 0/0, and most other status values that can be returned by the EXTERNAL REMOVE statement are already documented in the ECF return codes table. If an EXTERNAL REMOVE is attempted against a module that is currently being called ( in use ), then $status/$statusd will return the values 20/1 ( module unavailable).

==System enhancements==

===New wait types for daemon/master waits===

Two new wait types, viewable on the <var>[https://m204wiki.rocketsoftware.com/index.php/MONITOR_command MONITOR] USERS</var> command output, have been implemented as follows:

<code>57</code> - Means a daemon thread waiting for its master thread 
<code>58</code> - Means a master thread waiting for one of its daemon threads

This change is enabled in V7.7 with the application of zap 77z410.

===Snap formatting changes===
Date/time stamps in the page headers of snaps will now be shown normal format, rather than in julian format as in previous releases. Thus in the following example a particular snap header under v7.7 or previous releases would show as

SNAPID 1 19226.060155 M204.0022: Bug .. nnnnn PAGE 1

whereas the same snap header under v7.8 would show as

SNAPID 1 2019/08/14 06:01:06 M204.0022: Bug .. nnnnn PAGE 1

Also, due to improvements in handling trailing blanks in snap output, a snap generated under v7.8 should be marginally smaller than the same snap generated under previous releases, assuming the same SNAPCTL settings.

===Call stack trace for problem diagnosis===
A call stack trace is now provided to help diagnose and resolve common errors. To enable the stack trace, do either of the following:
<ul>
<li>Set the <var>[[SIRFACT parameter|SIRFACT]] X'01'</var> bit.</li>
<li>Set the <var>[[DEBUGUL parameter|DEBUGL]]</var> parameter. Note that the <var>DEBUGUL</var> approach will introduce extra QTBL overhead. (<var>DEBUGUL</var> provides a similar facility with an include trace of procedures leading to the error, but this might not be potentially as useful as the call trace.)
</li>
</ul>

The call stack trace can assist in diagnosing run-time errors that might occur, as illustrated by the following "Variable too small for result" and "MBSCAN exceeded" examples.

====Variable too small for result====
When the stack trace is enabled, a "variable too small" error results in the following message:

M204.2966: Error at line n, procedure ''procname'' in file ''procfile''

which identifies the line within a procedure where the error is occurring, in addition to the usual message:

M204.0552: Variable too small for result

Any subsequent M204.2966 messages indicate the point in the code from where the code in error was called. For example, a stack of three subroutine calls leading to a "variable too small" error might result in the following messaging:
 M204.0552: Variable too small for result
M204.2966: Error at line 9, procedure MYPROC.LEVEL4 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL3 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL2 in file MYPROC
M204.2966: Called from line 5, procedure MYPROC.LEVEL1 in file MYPROC 

This information should help in diagnosing the problem.

If the error occurs within a command level program rather than a procedure, then the M204.2966 message is replaced by an M204.2967 message, and a similar error condition to the above with a preceding call stack might be audited as follows:
 M204.0552: Variable too small for result
M204.2967: Error at line 14 of command level program
M204.2967: Called from line 5 of command level program
M204.2967: Called from line 3 of command level program 

If neither <var>SIRFACT X'01'</var> nor <var>DEBUGUL</var> is set, then the "variable too small" error produces the following messages:
 M204.0552: Variable too small for result
M204.2968: Error: no debug info 

====MBSCAN exceeded====
Similarly to the handling of the "variable too small for result" error, the call stack can also be used to diagnose errors where the value of <var>[[MBSCAN parameter|MBSCAN]]</var> is exceeded as a result of a direct search of Table B records.
Again, under V7.8, with either the <var>SIRFACT X'01'</var> bit set or <var>DEBUGUL</var> set, if a long request occurs as a result of exceeding <var>MBSCAN</var>, then initially the following message is produced, as before:
M204.0569: File ''filename'', Find: Table B records to be searched = ''nnnn''
followed by a DYRWT prompt message. If the user replies 'N' to the prompt, or if the request is run in an environment (such as a batch job) where the default response is 'N', the following message is produced after the M204.0569 message:
Cancelling request: M204.2969: MBSCAN (''mm'') exceeded, records to be searched = ''nnnn''

where ''mm'' is the current setting of <var>MBSCAN</var>. The M204.2969 message is followed by M204.2966 messages displaying the call stack trace. Thus, if the following code is run from procedure MYPROC.MBSCAN against the demo database, with an <var>MBSCAN</var> setting of 10:
 b
call sub1
sub1: subroutine
fd1:
in clients fd city = ONTARIO
end find
fr fd1
pai
print
end for
end subroutine
end 

then the following messages are produced, assuming any prompts are responded to with an 'N':
 M204.0569: File CLIENTS, Find: Table B records to be searched = 3415
Cancelling request: M204.2969: MBSCAN (10) exceeded, records to be searched = 3415
M204.2966: Error at line 6, procedure MYPROC.MBSCAN in file MYPROC
M204.2966: Called from line 3, procedure MYPROC.MBSCAN in file MYPROC 

===appendJournalData===
The <var>[[AppendJournalData_(Stringlist_function)|AppendJournalData]]</var> function is now more tolerant of an outstanding BUMP request. Previously, if <var>AppendJournalData</var> was called to inadvertently retrieve a large amount of journal data, typically when called implicitly from within SirScan, then any outstanding BUMP request wouldn't be honored until all of the data had been retrieved, at which point the BUMP request would be completed, and all data would be lost.

Now, the <var>AppendJournalData</var> process checks for outstanding BUMP requests before each track I/O is executed, thus avoiding excessive I/Os against the journal and long waits for the BUMP of such a process to complete.

==AUDIT204 enhancements==
===FORMAT command===
TIMEHH is a new parameter used with the FORMAT command of the [[Tracking_system_activity_(CCAJRNL,_CCAAUDIT,_CCAJLOG)#AUDIT204_utility|AUDIT204]] utility. It indicates that timestamps, printed at the beginning of each line of output, should include hundredths of a second. Requires no other arguments.
NOTE: This parameter and the 78 version (or later) of AUDIT204 may be used against a 77 (or later) CCAJRNL.
For example:
//CCAIN DD *
FORMAT YEARFORM 4
TIMEHH
TYPE ER MS LI

==Recovery enhancements==
===Media Recovery in a multi-user environment===
It is now possible to perform media recovery by issuing the <var>REGENERATE</var> command to roll forward selected files in a multi-user environment, with the media recovery being carried out by different users with system manager privileges. The new USING option allows for the specification of a ddname for the input journal stream to be used by the <var>REGENERATE</var> command. Previously media recovery was restricted to single user batch jobs, using the CCAGEN ddname for the input journal. For more details, see the <var>[[#REGENERATE|REGENERATE]]</var> command below.

==Security enhancements==
===CA-Top Secret can disallow CCASTAT logins===
The [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface CA-Top Secret] interface now recognizes the <code>DEFACID=</code>, setting and does not allow CCASTAT logins in the online if <code>DEFACID</code> is set to null. (There is no attempt to log on M204USR.) Therefore, to disallow CCASTAT logons, set DEFACID=, in [https://m204wiki.rocketsoftware.com/index.php/CA-Top_Secret_interface#Preparing_a_TOPSPARM_parameter_module_with_TOPSGEN TOPSPARM]. CCASTAT will be opened because it contains file and group passwords, but it will not be used for logons if CCASTAT logons are not allowed.

===CUSTOM=11 and mixed cased input===
The <var>[https://m204wiki.rocketsoftware.com/index.php/CUSTOM_parameter CUSTOM]</var> parameter CUSTOM=11 setting no longer requires that a *LOWER command be issued prior to a LOGCTL command (to add or change a password) to preserve mixed case input. Prior to this release, with CUSTOM=11 in place, *LOWER had to be issued before a LOGCTL command, otherwise any mixed case password strings would automatically be translated into uppercase. This change is enabled within V7.7 with the application of zap 77z108.

===DEFUSER can specify a jobname not authorized to access M204===
When specifying DEFUSER=JOBNAME and VALIDAT=LOGON in the RACFGEN parms for an ONLINE, if the specified jobname ( the owning id for the ONLINE job ) isn't authorized to use Model 204 via RACF, any LOGIN commands specifying no userid will now succeed ( previously such a LOGON would have failed ). This enables users to submit jobs with USE $JOB, whereby the string USER=jobname will be added to the submitted JCL, and this in turn is useful if the specified jobname has dataset access privileges to datasets required by the submitted jobs, even if the jobname itself isn't authorized to use M204.

==Janus product enhancements==

===Janus Web Server access rule===
The automatic <var>[[JANUS WEB ALLOW]]</var> rule, which allowed any user to access the port without requiring a login, is changed for non-SSL ports to the following:
JANUS WEB portname DISALLOW *


This rule requires a system administrator to explicitly define <var>ALLOW</var> rules to enable users to access non-SSL ports.
The rule applies unless overridden by user-added rules.

<blockquote class="note">
Note: To revert from this change in the JANUS DEFINE default and make the default
non-SSL <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>), turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote>

===Increase in pending accepts for Janus BPX ports===
The default number of pending accepts for Janus BPX server ports has been increased from 3 to 12, thus reducing the likelihood that a pending accept may fail with the message

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

The actual number of pending accepts to be supported on the port can be set with the new parameter MAXPEND, set on the <var>[[JANUS_DEFINE|JANUS DEFINE]]</var> command, where MAXPEND can vary from 3 up to a maximum value of 32. The change to the default value was enabled within V7.7 with the application of zap 77z269.

===TCP listen backlog increased===

The [https://m204wiki.rocketsoftware.com/index.php/Program_Communication_facilities#LISTEN_call TCP_listen] backlog has been increased from 16 to 1024 under z/OS.

This update tells the TCP stack to queue up to 1024 of such requests up before dropping them, thus reducing, or in most cases eliminating, the likelihood of a connection request drop, other than in exceptional circumstances, such as a denial of service attack. This change was enabled within V7.7 with the application of zap 77z340.

===Defer the freeing of XMLSCREEN input XML===

The freeing of [https://m204wiki.rocketsoftware.com/index.php/XMLSCREEN_and_NOXMLSCREEN_(JANUS_DEFINE_parameters) XMLSCREEN] input XML is now deferred until the next Read Screen or session termination. This means that if an application error is detected, the input XML can be retrieved with [https://m204wiki.rocketsoftware.com/index.php/$Web_Input_Content $Web_Input_Content] and then logged for problem analysis.

Prior to this release the XML received from the client is freed immediately after being used to set the input data for a Read Screen, rendering it unavailable for problem determination.

This change is enabled in V7.7 with the application of zap 77z368.

===XMLSCREEN and Janus Web Legacy blank stripping===

xmlScreens and Janus Web Legacy screens now adhere to the same standard as standard screen processing in terms of stripping leading blanks from input fields defined as [https://m204wiki.rocketsoftware.com/index.php/Full-screen_feature#DEBLANK_or_NODEBLANK_option DEBLANK] (either explicitly or implicitly).

This change is enabled in V7.7 with the application of zap 77z400.

===SSL input buffer size===

The default value of [https://m204wiki.rocketsoftware.com/index.php/SSLIBSIZE_(JANUS_DEFINE_parameter) SSLIBSIZE] has been increased to 16384 + 128, or 16512. This size should ensure correct communication with all TLS spec compliant applications. It is the maximum size allowed unless you use [https://m204wiki.rocketsoftware.com/index.php/CUSTOM_parameter#Using_CUSTOM.3D.2818.29 CUSTOM=18].

This changed is enabled within V7.7 with the application of zap 77z415.

===Increasing LDAP buffers===

The number of LDAP buffers allocated at startup can now be changed by setting the NLDAPBUF parameter in CCAIN. See below for details on [[#NLDAPBUF|NLDAPBUF]].

===Increase URL length returned with $web_form_action===
With this release the maximum Janus Web Server incoming URL that can be handled by <var>$web_form_action</var> is increased from 512 bytes to 1024 bytes. This change is enabled within V7.7 with the application of zap 77z424.

===Maximum RBSIZE setting increased===
The maximum value for RBSIZE, set on the <var>[[JANUS DEFINE|JANUS DEFINE]]</var> command, is now increased to 16777215 (previously the maximum was 65534). RBSIZE specifies the RPC or Request Buffer size. On a Web port, the Janus request buffer holds browser request information such as header data, cookies, and form data. On other port types, it holds RPC input and output parameters. This change is enabled within V7.7 with the application of zap 77z427.

==Debugger enhancements==

===Access to exposed variables===
The debuggers can now view or watch the values of variables exposed to local routines/methods. Previously, any attempts to access an exposed variable would have displayed "%varname has no value" in the debugger session. (This feature is enabled within V7.7 with the application of zap 77z363.)

==Performance enhancements==

===MP/204 offload improvements===
Application code issuing the following SOUL statements will now now be fully offloadable:
<ul>
<li><var>File Records In/On</var></li>
<li><var>Remember</var></li>
<li><var>Position</var></li>
<li><var>Sort Values</var></li>
<li><var>Reset Header/Trailer</var></li>
<li><var>Find and Print Count</var></li>
<li><var>Find All Values</var></li>
<li><var>For Each Value</var></li>
</ul>
the above improvements are also enabled within V7.7 with the application of zaps 77z419 and 77z420.

===X3270OUT exit offloadable===
When running MP/204 (AMPSUBS>0) and using the [https://m204wiki.rocketsoftware.com/index.php/Coding_SNA_Communications_Server_conversion_exit_routines#X3270OUT_.28convert_output_from_3270_format.29 X3270OUT] exit to convert a 3270 output data stream to the appropriate device protocol, the exit can now run in parallel mode to improve performance. This change was enabled in V7.7 with the application of zap 77Z313.

The X3270OUT exit must be written to be re-entrant.

==New and changed commands==
===DISPLAY ECF===
DISPLAY ECF {{ M | N | U } like ?} 

This new command displays details from ECF tables, or the current status of users accessing ECF modules.

D ECF M displays the contents of the module table. For example: D ECF M
Module Loadlib Address:Length Loaded@ Lastused@ #Calls Flags
QATUM13C PROGLIB 2FB91FB8:00000028 19023:121506 19023:121506 00000001
QATUM13B PROGLIB 2FE65000:00009C18 19023:121506 19023:121506 00000001
QATUM13A PROGLIB 2FE6EC18:00001CD8 19023:121506 19023:121506 00000001

(flags may be D=deleted; S=shared; H=halted; I=Idle)

D ECF N displays contents of the name table. For example: D ECF N
Module Logical-call-name
QATUM13C MOD_QATUM13C
QATUM13B MOD_QATUM13B
QATUM13A MOD_QATUM13A 

D ECF U displays details of users currently accessing ECF modules. This is also the default option, and so D ECF will display the same output as D ECF U. For example:
 D ECF U
User# Userid Module Parmlen
00002 ADMIN --none--
00003 ADMIN COBSAMP1 00000002
00004 ADMIN COBSAMP1 00000002 

D ECF LIKE ? (where <code>?</code> is a valid pattern) displays details for entities that match the specified pattern.

===REGENERATE===
The <var>REGENERATE</var> command can now be run in a multi-user environment by multiple users with system manager privileges. A new option USING is provided to specify the ddname of the input journal, so that the full syntax is now as follows:
 REGENERATE [USING ddname] FILE filename [FROM dumpname | IGNORE]
[TO {LAST UPDATE [BEFORE yy.ddd hh:mm:ss.th] | LAST CHECKPOINT [BEFORE yy.dd hh:mm:ss.th]
| UPDATE number OF yy.ddd hh:mm:ss.th | CHECKPOINT yy.ddd hh:mm:ss.th} ]

The default for the using ddname is CCAGEN, but any ddname may be used to allocate an input journal and used. For example:
 ALLOCATE REGEN1 WITH SCOPE=SYSTEM DSN=PROD1.GDGJ OLD SEQUENTIAL GEN=+2
REGENERATE USING REGEN1 FILE TEST

It is the user's responsibility to ensure that the file being regenerated is not in use, and so prior to usage, <var>BUMP FILE</var> and <var>STOP FILE</var> should be used to isolate usage against the file. If the file is in use, the REGEN will fail with these messages:
 M204.1430: Failed to open file TEST
M204.1436: Stopped processing file TEST 

$STATUS will now be set for <var>REGENERATE</var> with the following values:
<blockquote>
0 - Success 
1 - No files were processed 
2 - At least one file stopped processing 
4 - A serious error occurred, REGEN failed
</blockquote>

Similarly, <var>SETGRC</var> may be used to get the return code and error message.

==New and changed parameters==

===ECMODS===
The new minimum value for ECMODS, the allowable number of ECF modules, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECNAMES===
The new minimum value for ECNAMES, the allowable number of ECF module names, is 1. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ECPSIZE===
The new minimum value for ECPSIZE, the initial storage allocation for ECF parameters, is 1024. Prior to V7.8 the minimum value was 0. This changed was enabled in V7.7 with the application of zap 77z306.

===ENQTIME===
Millisecond duration of automatic record locking retry wait.

Prior to this change, if record locking conflicts occur frequently in a busy online, any user with a non-zero value for <var>[[ENQRETRY parameter|ENQRETRY]]</var> will wait at least 3 seconds before the conflict is dealt with. This can degrade overall system performance.

The <var>[[ENQTIME parameter|ENQTIME]]</var> parameter specifies the number of milliseconds waited for each record locking retry wait. ENQTIME can be between 1 and 60000, corresponding to a minimum of 1 millisecond and a maximum of 1 minute. The default value of ENQTIME is 3000 (3 seconds).

For example, with ENQTIME = 100 and ENQRETRY = 7, after a record locking conflict occurs the thread will retry 7 times with wait intervals of .1 seconds, and so within at most .7 seconds either the lock becomes available or the conflict triggers an On unit or cancels the request.

The ENQTIME parameter may also be reset with $ResetN.

This new parameter was enabled within V7.7 with the application of zap 77z299.

===EVALOPT===
The new <var>EVALOPT</var> parameter controls the cancellation of a request on truncation of string data. The default value is 0, and currently there is just one setting, 1, which means "cancel a request if truncation of string data occurs."

For example, with the default of 0 in place, the following code %x is string len 1
%y is string len 2
%y = 'ab'
%x = %y
printtext {~} = {%x} 

would cause silent truncation, and give the result
%x = a 

If <var>EVALOPT</var> is set to 1, then the above code produces the following message:
M204.0552: Variable too small for result 

and the request is cancelled.

===LFSCB===
LFSCB, the length of the full screen buffer, now has a new minimum value of 8 ( the previous minimum was 0 ). This change has been enabled within v7.7 with the application of zap 77z042, and within V7.6 with the application of zap 76z393.

===MAXPRE, MAXBOUT, MAXSUBT===
Introduced in zap 77Z257.
The new <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters can be used to cancel a runaway transaction and prevent it from filling the checkpoint data set.
<ul>
<li><var>MAXPRE</var>: Maximum number of pre-images per transaction. </li>
<li><var>MAXBOUT</var>: Maximum number of backout pages per transaction. </li>
<li><var>MAXSUBT</var>: Maximum number of subtransaction checkpoints that a transaction can span.</li></ul>

Each new parameter defaults to unlimited. 
If a parameter value is set, a transaction is cancelled if that value is exceeded, and the following message is displayed:
<code>M204.0524: Maximum number (num) of parameter exceeded.</code>
where num is the value set for parameter (<var>MAXPRE</var>, <var>MAXBOUT</var>, or <var>MAXSUBT</var>).

===NLDAPBUF===
This new parameter allows the number of LDAP buffers allocated during startup to be set in CCAIN. The default value is 2, and the settable value can range from 0 to 65535.

===PUPDTH (new minimum value)===
If a user sets the <var>[[PUPDTH parameter|PUPDTH]]</var> parameter to 0, it will now automatically be increased to 1, its minimum value.

===SERV4G===
This parameter allows testing of server tables that span a 4-gigabyte boundary. For example, if SERV4G is X'FFFFF000', each ATB server will begin at XX_FFFFF000. If SERV4G is X'FFFF0000', each ATB server will begin at XX_FFFF0000. XX is determined by the storage available on the system. The parameter is set in CCAIN.

The contents of the ATB server are specified by using the SERVGA parameter.

For example. if you want VTBL to span the 4G boundary, you can use these settings: SERV4G=X'FFFFF000', SERVGA=X'00040000', and LVTBL=200 (6400 bytes, X'1900'). This will force each server's VTBL to begin at XX_FFFFF000 and end at XX+1_00000900.

===WEBDFLT===
At V7.7, the default access rule for non-SSL ports was changed from ALLOW * to DISALLOW *, meaning that unless any ALLOW rules were in place resulting in a login/password prompt, the port couldn't be accessed. The new <var>[https://m204wiki.rocketsoftware.com/index.php/WEBDFLT_parameter WEBDFLT]</var> parameter may be set to 1 for reversion to the old default of ALLOW *. Under V7.7, this new parameter was enabled with the application of zap 77z090.

<var>RESET WEBDFLT</var> requires system administrator privileges. It is recommended to reset the 1 bit of <var>WEBDFLT</var> to zero after issuing a series of <var>JANUS DEFINE</var> commands which need WEBDFLT=1, as in the CCAIN input stream.

==New and changed statistics==
===MPR, MBO, MCP, and RCV===
Introduced in zap 77Z257.
These statistics provide high water mark transaction information. (Since-last values will not be available until V78 GA.)
They are useful in conjunction with the <var>MAXPRE</var>, <var>MAXBOUT</var>, and <var>MAXSUBT</var> parameters. 

User/system statistics:
<ul>
<li>MPR: High water mark of transaction pre-images. </li>
<li>MBO: High water mark of transaction backout pages. </li>
<li>MCP: High water mark of transaction chkpoint spans. </li>
</ul>
System statistics:
<ul>
<li>RCV: Number of blocks needed for subtransaction recovery </li>
</ul>
Notes: M204.0843 now displays the RCV statistic for subtransaction checkpoints.
The size of recovery checkpoint must be greater than the sum of the last RCV value plus the number of records in [https://m204wiki.rocketsoftware.com/index.php/System_and_media_recovery#RESTART_recovery_considerations_for_sub-transaction_checkpoints RESTART and RESTARTS].

===DKWTS and DKWTMICS===
Introduced in zap 77z7289.
The new system statistics DKWTS (DisK WaiTs) and DKWTMICS (DisK WaiT MICroSeconds) collect data to provide rough disk I/O service time numbers.

DKWTS shows the number of disk I/O waits. DKWTMICS shows the total wait time for those waits in microseconds. Dividing the difference in DKWTMICS by the difference in DKWTS over an interval provides the average disk I/O wait time in microseconds.

Notes:
<ul>
<li>The wait time does include internal Model 204 scheduler delays, so on a CPU bound Model 204 system, the service times calculated from DKWTS and DKWTMICS are likely to be an overestimate of actual service times.</li>

<li>DKWTS and DKWTMICS are not available in SirMon; use [https://m204wiki.rocketsoftware.com/index.php/MONITOR_command MONITOR] SYSTEM STATISTICS to view these statistics.</li></ul> 

==Compatibility issues==
===$ListNew cannot be used in Initial clause===
It is now a compilation error if <var>$ListNew</var> is attempted to be used in the <var>Initial</var> clause of a
[https://m204wiki.rocketsoftware.com/index.php/Using_variables_and_values_in_computation#Declare_statements_for_.25variables declaration statement].
This change is propagated by zap maintenance to versions 7.5 (zap 75Z487), 7.6 (zap 76Z514), and 7.7 (zap 77Z281) of Model 204.

<blockquote class="note">Note: Strictly speaking, this would not be considered a compilation error, because previously although <code>.. Initial($ListNew)</code> did not produce a compilation error, in almost all circumstances it would produce a snap if the initialized %variable were used with some other <var>$Listxxx</var> invocation.</blockquote>

===Restricting the use of the CUSTOM=38 setting===
The [[CUSTOM parameter|CUSTOM=38]] parameter setting, introduced at V7.5, inadvertently provided System Manager privileges to all users via the RESET command. This CUSTOM setting is now restricted to the RESETting of the LAUDIT parameter.

===Disabling of Closure support===
Due to a number of bugs related to Closure support, introduced at V7.7, this feature, which can best be described as exposed methods assigned to method variables, has been disabled in this release. This change was also made to V7.7 with application of zap 77z119.

===Password delimiter enforced===
When using IFSTRTN to logon to a Model 204 online from an IFAM2 application, both the logonid and password must be followed by a semicolon - the delimiter.
For example:

CALL IFSTRTN(RC,'logonid;password;'...)

If a semicolon does not follow the password string, the following message will now be issued

M204.2964: Password missing or too long

Previously, a semicolon following the password was not required and the first blank served as a password delimiter. However, as of V7.7, embedded blanks are valid password characters and a semicolon is now required to delimit the password.

This change has also been enabled within V7.7 with the application of zap 77z231.

===PAGESZ parameter validated===
Previously it was possible to set the PAGESZ parameter to any value, although Model 204 internally supports one page size of 6184, and any deviation from this value would have led to problems during file creation. The value of this parameter is now controlled, such that setting it to any value other than 6184 will generate an M204.1149 message with the parameter being reset to 6184.

===ECPRIV and the IDCAMS facility===
At V7.7 a security loophole was closed, whereby all ECF modules were run under external-authorizer profile of the calling user. Previously any ECF tasks were run under the owning job's external-authorizer profile, and in order for certain sites to retain that ability, a new setting of ECPRIV, value 4, was introduced to retain the ability to run ECF tasks using the job's security profile.

The ECPRIV 4 setting potentially introduced a security loophole when calling the IDCAMS interface, based upon what the IDCAMS utility is able to do at a system level. Consequently as of this release, the ECPRIV 4 setting will be ignored when calling the IDCAMS facility via ECF, and such IDCAMS processes will always use the calling user's security profile. Any existing jobs that use ECF to call the IDCAMS utility with the ECFPRIV 4 bit set should be checked to ensure that the calling user's security profile still satisfies the job's requirements.

===TCPOPTS is view only===
In previous releases the TCPOPTS parameter, which identifies the type of IP addressing in use ( v4 or v6 ), was resetable, although it was always documented as a view-only parameter. The parameter is now handled as a view-only parameter, and any attempts to reset the parameter will result in

M204.1123: Parameter TCPOPTS not reset

===ZHPF command can only be issued by a system manager===
In previous releases it was possible to issue the ZHPF command without being logged on. From this release onwards, a user would have to be logged on with system manager privileges to be able to issue this command.

Additionally, the command output will now only display results for currently open files.

This changes has been enabled within v7.7 with the application of zap 77z264.

===Terminal MODEL reset failure===
If a reset of the terminal MODEL parameter fails due to an under sized output page buffer, then in addition to the existing messages that inform the user of this failure

M204.1875 UNABLE TO RESET MODEL TO %C
M204.1123: Parameter MODEL not reset

the following message will now be issued

M204.1008: LOUTPB must be increased to at least <number>

where <number> is the minimum value of LOUTPB necessary to support the terminal model.

This change is enabled in V7.7 with the application of zap 77z309.

==New and changed messages==

See [[New and updated messages in Model 204 version 7.8|New and updated messages in Model 204 version 7.8]] for details.

[[Category: Release notes]]