m204wiki - User contributions [en]

SSLPROT (JANUS DEFINE parameter)

2026-04-13T20:46:38Z

Tom: /* Description */

SSLPROT xxx — Degree of SSL-like encryption

==Description==
<var>SSLPROT</var> is a parameter on the <var>[[JANUS DEFINE]]</var> command, which defines and sets characteristics of a Janus port.

This parameter lets you specify the degree of SSL-like encryption available at this port. <var class="product">[[Janus Network Security|Rocket M204 Janus Network Security]]</var> supports the Secure Socket Layer (SSL) protocol as well as the Transport Layer Security (TLS) protocol, an extension to SSL V3 but developed by the IETF Internet standards group. For the versions and levels of these protocols that are supported, see the parameter table below.

During the negotiation for a connection to or from this port, Janus will offer the most secure protocol available, then, if necessary, will fall back to the next lower one available, and so on. The <var>SSLPROT</var> parameter lets you explicitly disallow one or more protocols from the negotiation.

<var>SSLPROT</var> is a bitmask parameter whose main values are:

<table class="thJustBold">
<tr class="head"><th>Bit</th><th>Description</th></tr>

<tr><th>X'01'</th>
<td>SSL, V2 support. This is less secure than SSL V3 or TLS. Not supported in <var class="product">Model 204</var> 7.5 and later.</td></tr>

<tr><th>X'02'</th>
<td>SSL, V3 support. This is less secure than TLS.</td></tr>

<tr><th>X'04'</th>
<td>TLS, 1.0 support.</td></tr>

<tr><th>X'08'</th>
<td>TLS 1.1 support. Available as of <var class="product">Model 204</var> 7.5.</td></tr>

<tr><th>X'10'</th>
<td>TLS 1.2 support. Available as of <var class="product">Model 204</var> 7.5.</td></tr>

<tr><th>X'20'</th>
<td>TLS 1.3 support. Available as of <var class="product">Model 204</var> 8.0.</td></tr>

<tr><th>X'07'</th>
<td>The default under <var class="product">Model 204</var> 7.4 and earlier. SSL V2, SSL V3, and TLS 1.0 are available. Janus will try for them in the order: TLS 1.0, SSL V3, and SSL V2.
<tr><th>X'1E'</th>
<td>The default under <var class="product">Model 204</var> 7.5 and later. SSL V3, and TLS 1.0, TLS 1.1, and TLS1.2 are available. Janus will try for them in the order: TLS 1.2, TLS 1.1, TLS 1.0, and SSL V3.</td></tr>
</table>

A typical reason for explicitly specifying an <var>SSLPROT</var> value is to require a more secure connection for a port. If a client attempts to connect to a Janus server port using a protocol explicitly disallowed by <var>SSLPROT</var>, the connection is immediately broken, except for <var>[[JANUS DEFINE#type|WEBSERV]]</var> ports where the <var>SSLPROTOCOLERR</var> exception handler will be run if available.

Janus <var>[[JANUS DEFINE#type|CLSOCK]]</var> ports will attempt to connect under the most secure protocol available, and will fall back to the next-most secure protocol available; if less-secure protocols are disallowed by <var>SSLPROT</var>, the connection attempt will fail.

<var>SSLPROT</var> is valid for <var>[[JANUS DEFINE#type|SRVSOCK]]</var>, <var>CLSOCK</var>, <var>WEBSERV</var>, <var>[[JANUS DEFINE#type|OPENSERV]]</var>, and <var>[[JANUS DEFINE#type|SDS]]</var> port types.

==See also==

<ul>
<li>[[SSLCIPH (JANUS DEFINE parameter)]]
<li>[[List of Janus commands]]
<li>[[JANUS DEFINE#parmlist|List of JANUS DEFINE parameters]]
</ul>

[[Category:JANUS DEFINE parameters|SSLPROT]]

Release notes for Model 204 version 7.8

2024-09-18T19:39:25Z

Tom: /* Operating system and hardware requirements */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

==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 (Daemon subroutine)|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>
<ul>
<li>[[Janus_Two-Phase_Commit|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>[[Application_Subsystem_development#COMMITX parameter|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|DISPLAY ECF]]</var> command and <var>[[#Managing ECF tables more efficiently|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 command|MONITOR <var>USERS</var>]]</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, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and 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 3.1. (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 7.3.</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>

===EndsWith function===
The [[EndsWith (String function)|EndsWith String function]] determines if one string ends with the characters in another. This is analogous to the [[StartsWith and IsStartOf (String functions)|StartsWith function]] except, of course, it checks the end of a string rather than the start.

The following code snippet:
printText {~="War and Peace":endsWith("Peace")}
printText {~="War and Peace":endsWith("War")}

displays:
"War and Peace":endsWith("Peace")=True
"War and Peace":endsWith("War")=False


===$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 will 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===
There 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_Call_Facility#External_Module_statement|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 parameter|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|DEBUGUL]]</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 978, procedure DOCOOLSTUFF in file COOLFILE
M204.2966: Called from line 1215, procedure FOOBAR.CLASS in file CLASSES
M204.2966: Called from line 378, procedure SILLY.CLASS in file CLASSES
M204.2966: Called from line 187, procedure P.ROCKANDROLL in file APSYFILE


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.

==Editor enhancements==
The [[Model 204 full-screen editor#exit|Model 204 editor]] has been enhanced to not hold a lock on a procedure being edited. Instead the timestamp of the procedure on disk is compared against that of the edited procedure when it was loaded or last saved. If different, the save is not allowed. New commands <var>SSAVE</var>, <var>EEND</var>, and <var>GGO</var> are available to force the save in this situation.
In addition, the <var>GO</var> command no longer updates the procedure on disk before <var>INCLUDE</var>ing it if it has not been modified in the editor.
==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.

===MERGEJ now supports up to 99 input journals===
The MERGEJ utility, used to merge journals with overlapping timestamps prior to running Media Recovery, now supports up to 99 input SORTINnn journals to be merged. For this release it is still the case that any previously merged journal must be defined as SORTIN01 to the MERGEJ run, and thus that the MERGEJ run can not accept more than one previously merged journal as input.

This change is also enabled in V7.7 with the application of 77z487.

==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 API calls available on transactional daemons===
Transactional daemons can now use the Janus Web API, mostly $functions that begin with <var>$web</var>. The new [[$Web_Api|$web_api function]] makes it possible to test if the Janus Web API is available, whether on a Janus Web Server thread or one of its transactional daemons.

===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.

===$Web_Form_Parm_Binary===
Janus Web now defers ASCII to EBCDIC translation of form parameter values until a value is requested. This makes it possible to retrieve the exact values sent by the client rather than a translated version. This is important if a form parameter value is UTF-8 encoded and contains non-7-bit ASCII characters (for example if a form parameter contains XML). The [[$Web_Form_Parm_Binary]] function returns the exact value sent by a client for a form parameter with no character translation.

===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 1280 bytes. This change is enabled in V7.7 with the application of zaps 77z424 and 77z448.

===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.

===Limiting the production of MSIR.0019 and MSIR.0020 messages===
The production of the following messages

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

MSIR.0020 Connection request rejected for port (port), no SDAEMONS available

is now limited to a maximum of one each per time interval set by the <var>[[MAXAUSEW_parameter|MAXAUSEW]]</var> parameter ( minimum seconds between <var>[[MAXAUSER_parameter|MAXAUSER]]</var> warnings, which defaults to 10 seconds ). This avoids flooding the journal / jlog with these messages in situations where the number of connections on a port has been exceeded ( MSIR.0019 ), or the the number of available daemon threads has been exceeded ( MSIR.0020 ).

This change is available in V7.8 with the application of zap 78z011, and within V7.7 with the application of 77z466

==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 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.

Also, [[JANUS WEB|Janus Web rules]] scanning will be offloadable. In addition, the scan for persistent web sessions ([[$Web_Form_Done]] and [[Janus Web Legacy Support]]) will be offloadable. While the rendezvous with the persistent thread will still be maintask-only, stateless requests will not need to go back to the maintask to be processed and, even for persistent requests, the persistent session lookup will be offloadable. These changes should provide better scalability for MP/204 sites with heavy Janus Web activity.

===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.

===Internal performance improvements===
A number of internal performance and optimisation improvements have been made in this release. these include

<ul>
<li>Sampling buffer pool pages rather than carrying out a full scan of large buffer pools ( NUMBUFG > 200000 ) when calculating BUFFnnn stats for SirMon</li>
<li>Optimising group and file closure, in particular providing relief on exit from APSYs where a lerga number of groups may be in use, and where the groups may comprise a large number of file members</li>
<li>Improved handling of timer queues, particularly in an MP/204 environment</li>
<li>More aggressive prioritisation of journal and checkpoint I/O, in order to reduce user waits for such I/), and to reduce related waits on critical file resources
</ul>

==New and changed commands==
===MONITOR===
The MONITOR command output now contains a new column, headed LOG, that shows the logon status of each user in the system, for example

USER SVR FLS PCPU SMPLS RUNG REDY BLKI WTSV BLKO SWPG
7 0.330

USER SVR USERID P CUR SLICE LOG FUNC CNCT CPU SEQIO QUE WT FLGS
0 1 SUPERKLUGE S 56 0.031 CCA EVAL 5 0.012 221 OFFI 12 65
4 2 ADMIN S 51 0.031 CCA 1 0.000 22 RUNG
20 VT75DIED 0.000 0 0.000 0 2 20
21 VT75READ 0.000 37 0.000 0 3 00
22 VT75ERRS 0.000 0 0.000 0 2 20
23 CHKPTIMO 0.000 0 0.000 0 12 20
24 CHKPTIMR 0.000 0 0.000 0 12 20
25 CHKPPST 0.000 0 0.000 0 12 20
26 CHKPAWW 0.000 0 0.000 0 12 20
27 TC62RAPS 0.000 0 0.000 0 27 04
28 TC62SRVC 0.000 0 0.000 0 27 20
>

The LOG column replaces the AGE column in the MONITOR output, as this information was considered more relevant for this command output. Possible values that are shown in the LOG column are as follows
<ul>
<li> CCA - CCASTAT userid</li>
<li> ESM - userid validated by an External Security Manager - ACF2, RACF, or TopSecret/li>
<li> SUB - Subsystem controlled logon</li>
<li> GST - Guest - neither logged on via CCASTAT nor by an ESM</li>
<li> PDG - Logon pending due to errors (e.g. invalid password)</li>
</ul>

This change is also available with V7.7 with the application of zap 77z478.

===MONITOR IODEV===
This new command displays the total number, the current usage and the maximum number of each IODEV type. If the Model 204 parameters include telnet threads (TNDEV parameter), the specified IODEV will actually execute as a daemon thread (SDAEMDEV parameter). For that reason, both the telnet and daemon IODEVs will be incremented and the telnet IODEV will appear with an appended '*'. 
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%
21* 1 1

===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==

===COMMITX===
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.

===ECMSUBS===
This maximum value may now be reset dynamically by a system manager. If the value is raised, new tasks will be added as needed up to the value specified. If the value is lowered, idle subtasks will be detached before they are activated until the new maximum is established.

===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 parameter|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>).

===MODENAME in a Transfer Control PROCESSGROUP===
Previously the MODENAME parameter has been ignored in VTAM TRANSFER PROCESSGROUP processing.

As of V78 with 78Z029 applied, Users will be able to control the characteristics of a session (for example, Display Model, Ru size, EDS support et al.) bound at the VTAM Transfer Control Target
by means of the VTAM Transfer PROCESSGROUP's MODENAME.

A null or unspecified MODENAME in a VTAM Transfer PROCESSGROUP definition will result in the Target LU's
Default LOGMODE being used to Bind the Target Session (This is how all VTAM Transfers worked previously).

Specifying MODENAME=LOGON or MODENAME=LOGIN in a VTAM TRANSFER PROCESSGROUP definition results in the LOGMODE used
to Logon to the Source Online also being used to Bind the Session at the Transfer Target.

Otherwise, anything specified in a VTAM TRANSFER PROCESSGROUP MODENAME parameter will be assumed to be a
valid VTAM LOGMODE and will be used to Bind the Transferred session at the Target. There is a potential
for upward incompatibility in the case where a VTAM TRANSFER PROCESSGROUP definition specifies an invalid value for MODENAME:

Since the MODENAME is no longer ignored, an invalid value will now fail the Transfer.

A failed Transfer consequent to an invalid LOGMODE or a LOGMODE unknown at the Target is flagged with:
M204.2483 'unknown-modename is not a valid LOGMODE name'.

===MQMXTASK===
This maximum value may now be reset dynamically by a system manager. If the value is raised, new tasks will be added as needed up to the value specified. If the value is lowered, idle subtasks will be detached before they are activated until the new maximum is established.

===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.

===WEBOPT===
The new x'10' setting of <var>[[WEBOPT_parameter|WEBOPT]]</var> allows transaction daemon threads to access web data owned by the ancestor ( usually the parent ) thread.

==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, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and 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 non-trivial backward incompatibility issue related to Closure support, introduced in 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.

===BUF and FBMX stats removed===
Unnecessary scans of the buffer pool have been eliminated from most forms of the MONITOR command ( other than MONITOR DISKBUFF itself ), and this provides performance gain when running these commands. However, as a result of this the BUF stat on the MONITOR command output, and the FBMX stat reported in the system final stats block have been removed. These stats were of extremely limited value, and their elimination should not cause any problems for system management. This change is implemented in V7.8 via zap 78z077, and in V7.7 by zap 77z463.

==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 products==
===Janus Two-Phase Commit===
[[Janus Two-Phase Commit]] support makes it possible to create global transactions where updates on multiple Model 204 Onlines or <var>Imagine</var> can be atomically committed or backed out.

===Commit Exit===
The [[Application_Subsystem_development#Commit_exits|Commit exit]] product allows for the invocation of specified APSY code when an an APSY TBO transaction executes its first explicit or implicit COMMIT. The feature is controlled by the new COMMITX parameter.

==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.7

2024-09-18T19:38:57Z

Tom: /* Operating system requirements */

These release notes list the enhancements and other changes contained in Model 204 version 7.7.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.7 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.7. For a full list of features, refer to the Table of Contents.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>

<tr>
<td>Performance</td>
<td>
<ul>
<li>Continued expansion of 64-bit addressability. See [[#Elimination of BTB buffers|Elimination of BTB buffers]]. </li>

<li>Greater zIIP processor availability: M204 HPO and Fast/Unload HPO. See [[#zIIP exploitation|zIIP exploitation]]. </li>

<li>zIIP load tuning. See [[#MPDELAY and MPDELAYZ (new)|MPDELAYZ]], [[#SCHDOFLS (new)|SCHDOFLS]], [[#SCHDOPT (change to X'20' bit processing)|SCHDOPT]]. </li>

<li>Essential removal of application limits on the [[#Increase in request limit for number of images, screens, and menus|number of images, screens, and menus]].</li>

<li>Support for large data sets (as many as 16 million tracks) for the Model 204 Checkpoint facility [[Checkpoints: Storing before-images of changed pages#Creating the CHKPOINT.2FCHKPNT .28and CHKPNTS.29 data set|CHKPOINT or CHKPNTS data sets]]. See [[System_and_media_recovery#ROLL_BACK_processing.2C_Pass_2|ROLL BACK processing, Pass 2]].</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>Stronger cryptographic algorithms: SHA-384, SHA-512. See [[#"SSL" String methods|"SSL" String methods]], [[#New DigestAlgorithm values|New DigestAlgorithm values]], and [[#New default certificate-signing algorithm|New default certificate-signing algorithm]]. </li>

<li>Longer RSA keys (as many as 4096 bits). See [[#Janus Network Security ciphers and private keys|Janus Network Security ciphers and private keys]]. </li>

<li>Support for [[#Long password support|longer and mixed-case login passwords]]. </li>
</ul>
</td><tr>

<tr>
<td nowrap>Add-on enhancements</td>
<td>
<ul>
<li>A more versatile Fast/Unload through [[#Integration of Fast/Unload with the Online load module|integration with Model 204]]. </li>

<li>Janus products' [[#Support for IPV6|support for the IPV6 network protocol]], expanding the network address space from 32 to 128 bits. </li>
</ul>
</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 3.1. (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.7 operates as an APF authorized load module, as required by many 7.7 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 7.3.</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.7 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>

===Model 204 compatibility with operating systems===

For information on Model 204 certification with IBM operating systems, see [[Model 204 system requirements]].

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

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

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

==SOUL (User Language) enhancements==

===New and changed classes and methods===

====New exception class: WriteError====
<var>[[WriteError class|WriteError]]</var> exceptions are thrown by the <var>Close</var>, <var>WriteBlock</var>, <var>WriteRecord</var>, and <var>WriteRecords</var> methods in the [[Dataset class]] if they encounter a full output <var>Dataset</var> object.

====New default certificate-signing algorithm====
[[Janus Network Security]] as well as the <var>[[Stringlist_class|StringList]]</var> methods <var>[[AppendSignedCertificate (Stringlist function)|AppendSignedCertificate]]</var> and <var>[[AppendSignedClientCertificate (Stringlist function)|AppendSignedClientCertificate]]</var> methods have changed their default signature algorithm from SHA-1 to SHA-256.

This change is propagated by zap maintenance to versions 7.6 and 7.5 of Model 204.

===="SSL" String methods====
These new methods are added:
<table>
<tr class="head"><th>Method</th><th>Description</th></tr>
<tr><td>[[SHA384digest (String function)|SHA384digest]]</td><td>SHA-384 digest</td></tr>
<tr><td>[[SHA512digest (String function)|SHA512digest]]</td><td>SHA-512 digest</td></tr>
</table>

====New LoadMsgctl method====
The new <var>[[LoadMsgctl (XmlDoc subroutine)|LoadMsgctl]]</var> method lets you view what <var class="product">Model 204</var> messages have been affected by <var>[[MSGCTL command|MSGCTL]]</var> commands. The method also displays the current attributes of those messages. 

In addition, to better understand the effect of the <var>MSGCTL</var> command, the [[RKTools]] <code>SIRIUS</code> file will contain a procedure you can use to display the <var>MSGCTL</var> commands that have been specified in the Online session.

====New DigestAlgorithm values====
Values <var>SHA384</var> and <var>SHA512</var> are added to the [[DigestAlgorithm enumeration]].

====Method variable invocation====
[[Method variables]] can now be invoked using <code>%var()</code> or <code>%obj:var()</code>, as in JavaScript.

====X509CertificateToXmlDoc method support for unknown elements====
A certificate's <code><RelativeDistinguishedName></code> element can contain a wide variety of attributes that <var>X509CertificateToXmlDoc</var> does not understand. Under Model 204 7.6 and earlier, this results in a parse exception, but under 7.7 and later, such attributes are added as <code><unknown></code> elements with an <code><ObjectIdentifier></code> element that indicates the ASN.1 object identifier.

Note: You are advised not to refer to such an <code><unknown></code> element in your programs, since future updates to the <var>X509CertificateToXmlDoc</var> method might add support for the element, in which case the element name will change to a proper name. If such an element is of interest, [[Contacting Rocket Software Technical Support|contact Rocket Software technical support]]. 

====Resulting element length in "ToXmlDoc" String methods====
Prior to version 7.7 of Model 204, the <var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>, <var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var>, <var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var>, and
<var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var> methods failed if input to them created any element in the result <var>XmlDoc</var> with a text child whose length exceeded 650 characters.
An example of such input is a 4096-bit key (which requires 1024 hex characters).

As of version 7.7, the lengths of the created text nodes are not restricted.

====LDAP request length limit====
Prior to version 7.7 of Model 204, the SOUL [[LDAP class#limit|LDAP client buffers]] allowed a limit of 6144 bytes per request. As of 7.7, the limit is increased to 8184.

===New XHTML entities for square-bracket characters===
[ and ] are newly supported as [[XML processing in Janus SOAP#Entity references|XMHTL entities]] (notably in the [[U (String function)#brackets|U method]]). This provides a better approach to specifying square brackets (such as for [[XPath#Some notes on XPath usage|XPath]] expressions) than the formerly recommended use of <var>Static</var> %variables initialized to the correct values.

This change is propagated by zap maintenance to version 7.6 of Model 204.

For example, to produce an XPath expression equivalent to the following:
<nowiki>*/pers[@name="Hector"] </nowiki>
Code like this was recommended under version 7.5 of Model 204:
%lsq is string len 1 static initial('&#x5B;'):u
%rsq is string len 1 static initial('&#x5D;'):u
. . .
%myXmldoc:print('*/pers' %lsq '@name="Hector"' %rsq) 

Under version 7.6 and above, you can instead use the new entities and avoid the declarations, concatenations, and runtime conversions required above:
%myXmldoc:print('*/pers[@name="Hector"]':u)

===Procedure names can begin with zero===
Formerly, a procedure name was not allowed to begin with a zero or a minus sign. As of version 7.7, a procedure name can begin with a zero, and alphanumeric procedure names can begin with a minus sign (<tt>-</tt>), which is interpreted as a hyphen. For example, <code>00123</code>, <code>-1myproc</code>, and <code>-myproc</code> are valid procedure names.

See the <var>[[PROCEDURE command|PROCEDURE]]</var> command for details. 

===Assert statement support for Info expressions===
The SOUL <var>[[Assert statement|Assert]]</var> statement allows the optional parameter <var>Info</var> to provide additional output information. As of version 7.7, the <var>Info</var> phrase may contain any valid SOUL expression, including a method call or $function. The expression, which must be enclosed in parentheses, is evaluated only in the case of an <var>Assert</var> failure.

A simple example is:
assert %x gt 0, info ('abc' with 'def') 

<blockquote class="note">
Note: This enhancement introduces a slight backward incompatibility: An <var>Assert</var> statement like the following, whose <var>Info</var> value begins with an opening parenthesis but has no closing parenthesis, compiled without error prior to version 7.7: 
assert %x gt 0, info (

From 7.7 on, such a statement produces a compilation error, because the compiler expects an expression after the open parenthesis. 
</blockquote>

==Security enhancements==
===Long password support===

Logon passwords, maintained in CCASTAT, can now contain as many as 127 characters.
 Also, passwords and passphrases can now contain one or more embedded spaces. (Leading and trailing spaces are stripped.)

The long password feature includes support for: 
<ul>
<li><var>[[LOGIN or LOGON command|LOGON]]</var> command</li>
<li><var>[[LOGINCP or LOGONCP command|LOGONCP]]</var> command, used to change a password</li>

<li><var>[[LOGCTL command: Modifying user ID entries in the password table|LOGCTL C USERID]]</var> command</li>

<li><var>[[$Sir_Login]]</var> function</li>

<li>Mixed-case passwords (if the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter includes the value 11)</li>

<li>[[Storing_security_information_(CCASTAT)|CCASTAT]] data sets created with or without password expiration support</li>

<li>Long passwords (passphrases) for use with the following [[Security interfaces overview|external security interfaces]]: CA-ACF2 MVS, Security Server (formerly RACF), and CA-Top Secret</li>
</ul>
Note: This feature is available for logon passwords only; it does not apply to file passwords.

No changes to CCASTAT and no new CCAIN parameters are required to enable long password support.
In order to allow embedded blanks in passwords passed on [[IFSTRTN_(IFAM2)_(HLI_function)|IFSTRTN]] calls, a semicolon is required as the password delimiter and the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter 24 value must be set.

For additional security enhancements in version 7.7, see [[#Janus Network Security ciphers and private keys|Janus Network Security ciphers and private keys]] as well as [[#"SSL" String methods|"SSL" String methods]], [[#New DigestAlgorithm values|New DigestAlgorithm values]], and [[#New default certificate-signing algorithm|New default certificate-signing algorithm]].

==Janus product enhancements==

===Support for IPV6===
As of version 7.7, customers can use the [[Janus products]] in an IPV6 (Internet Protocol Version 6) environment. Before this release, all Janus commands and parameters were able to accommodate IPV4 addresses only. IPV6 addresses expand the network address space from 32 to 128 bits.

These parameters, commands, and functions support IPV6 under version 7.7 of Model 204:

<table>
<tr class="head"><th>Commands</th><th>System parameter</th><th>SOUL</th></tr>
<tr><td nowrap>
JANUS CLSOCK and JANUS SRVSOCK 
JANUSDEBUG and JANUS WEB DEBUG 
JANUS DEFINEIPGROUP 
JANUS DEFINE BINDADDR 
JANUS DISIPG 
JANUS DISUSG 
JANUS TRACE 
JANUS WEB ALLOW
</td>

<td nowrap>
TCPTYPE 
(see [[#tcptype|TCPTYPE (new IPV6 values)]])
</td>

<td nowrap>
$Web_IPAddr 
LocalHost (UdpSocket property)
</td></tr>
</table>

===Janus Network Security ciphers and private keys===
Support for certificates signed using [[DigestAlgorithm_enumeration|SHA-384 and SHA-512]] are added to [[Janus Network Security]]. This makes it possible to generate certificates signed with these algorithms and to accept server or client certificates signed with these algorithms.

In addition, support is added for RSA keys that are as many as 4096 bits in length. You can now generate and sign 4096-bit keys and use them in client and server certificates using <var class="product">Janus Network Security</var> application as well as its associated and related methods, including:
<table>
<tr class="head"><th>Class</th><th>Method</th></tr>
<tr><td>System</td>
<td><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var></td></tr>

<tr><td rowspan="4">Stringlist</td>
<td><var>[[AppendCertificateRequest (Stringlist function)|AppendCertificateRequest]]</var></td></tr>

<tr><td><var>[[AppendGeneratedPrivateKey (Stringlist subroutine)|AppendGeneratedPrivateKey]]</var></td></tr>

<tr><td><var>[[AppendSignedCertificate (Stringlist function)|AppendSignedCertificate]]</var></td></tr>

<tr><td><var>[[AppendSignedClientCertificate (Stringlist function)|AppendSignedClientCertificate]]</var></td></tr>

<tr><td rowspan="4">String</td>
<td><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </td></tr>

<tr><td><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </td></tr>

<tr><td><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var> </td></tr>

<tr><td><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </td></tr>
</table>

===Janus Web Server rules===
The following changes have been made in version 7.7:
<ul>
<li>Janus Web used to automatically implement [[Defining Web rules#Notes|two web server ON rules]] to set up access to the Janus Web sample home page and to demonstration application procedures. These rules were removed in version 7.6 (by zap maintenance) and are not present in version 7.7.</li>

<li>You can now substitute an HTTP method name in the command for a <var>JANUS WEB ON</var> rule. See [[#ON rules (method name substitution)|ON rules (method name substitution)]] for details.</li>

<li>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 (after zap 77Z088 in version 7.7, or after zap 76Z418 in version 7.6) unless overridden by user-added rules.

<blockquote class="note">
Note: With version 7.7 zap 77Z090 or version 7.6 zap 76Z420, you can make the default <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>). To do so, turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote></li>

<li>As described below in [[#JANUS WEB (additional rule support)|JANUS WEB (additional rule support)]], the <var>JANUS WEB</var> command <var>ALLOW</var> and <var>DISALLOW</var> rules are updated to include support for RESTful and WebDAV HTTP methods. </li>
</ul>

===Janus Web access to HTTP authorization and authentication headers===
Under version 7.7, Janus Web lets you access HTTP user authentication headers. You can capture the HTTP "Authorization" request header value, and you can set the "WWW-Authenticate" response header. See [[Janus Web Server security#Authorization and WWW-Authenticate headers|Authorization and WWW-Authenticate headers]].

==Fast/Unload enhancements==

===Integration of Fast/Unload with the Online load module ===

Previously (for all versions of <var class="product">Fast/Unload</var> through 4.7), the standalone <code>FUNLOAD</code> load module was downloaded and linked separately and independently from Model 204. Starting with version 7.7 of Model 204:
<ul>
<li><var class="product">Fast/Unload</var> is entirely linked with the Model 204 Online load module. </li>

<li>Maintenance zaps applied to the Online load module include all <var class="product">Fast/Unload</var> maintenance.</li>

<li>The version number of <var class="product">Fast/Unload</var> is the same as the version number of Model 204. </li>

<li>If you are authorized for Fast/Unload, the authorization zap for the ONLINE load module will contain authorization for Fast/Unload. The authorization zap used for previous releases of FUNLOAD should not be applied to the FUNLOAD module in 7.7.</li>
</ul>

Under 7.7, the Online load module can be linked with an ALIAS (the standard one is FUNLOAD) and an alternate ENTRY. This alias is functionally indistinguishable from the standalone <var class="product">Fast/Unload</var> FUNLOAD load module installed for all previous versions of <var class="product">Fast/Unload</var>.

The integration of Fast/Unload with the Online load module also makes additional DDnames available to PGM=FUNLOAD for possible problem diagnosis by Rocket Technical Support. These DDnames are <code>CCASNAP</code>, <code>CCAAUDIT</code>, and <code>CCAPRINT</code>, and they are described in [[Fast/Unload invocation#ccadd|Fast/Unload invocation]].

A significant benefit of running Fast/Unload integrated with Model 204 and not standalone is the ability to take advantage of zIIP processing, as described next in the "zIIP exploitation" section.

===zIIP exploitation===
If you have an authorization zap that contains both of the following, your standalone PGM=FUNLOAD jobs will run on a zIIP processor, if one is available:
<ul>
<li><var class="product">[[Performance monitoring and tuning#Offloading Model 204 work to zIIP processors|M204 HPO]]</var>, the zIIP-support product of Model 204

PGM=FUNLOAD automatically supplies the necessary Model 204 parameters to enable zIIP exploitation. </li>

<li>The <var class="product">[[Fast/Unload overview#fuhpo|Fast/Unload HPO]]</var> product </li>
</ul>

===New #VIEW204 function===
The <var>[[Fast/Unload standard functions#.23VIEW204: Value of Model 204 parameter|#VIEW204]]</var> function returns the value of the [[List of Model 204 parameters|Model 204 parameter]] you specify as an argument.

===PUT statement enhancements===


====Length prefix for PUT output values====

New <var>[[Fast/Unload PUT statement#PUT|PUT]]</var> statement syntax is added to insert a one-byte or two-byte binary integer, containing the byte length of a <var>PUT</var> value, in the output stream before the value.

For better readability and lower CPU cost than the techniques currently used to achieve the same result, the <var>AS</var> clause of a <var>PUT</var> statement will now allow the <var>COUNTED</var> keyword:
... PUT info .. AS [format] COUNTED[1|2] 

For example, <code>PUT FIRST.NAME AS COUNTED2</code> puts the first occurrence of field <code>FIRST.NAME</code> as a string value, preceded by a two-byte binary integer containing the length of that occurrence.

With this feature, you can replace FUEL code such as the following: 
%VAL = ITEM.CODE(%OCC)
%LEN = #LEN( %VAL )
PUT %LEN AS FIXED(2)
PUT %VAL 
With: 
PUT %VAL AS COUNTED2 

====#function as PUT "info" argument====

New in this version, a #function call is allowed as the <var>PUT</var> <var class="term">info</var> argument. For example, instead of FUEL code such as the following:
%VAL = #STRIP(ITEM.VALUE(%OCC), 'L', 0)
PUT %VAL 
You can use this more readable and somewhat more efficient equivalent:
PUT #STRIP(ITEM.VALUE(%OCC), 'L', 0) 

===#STRIP function enhancements===


====New #STRIP fourth argument====

The new fourth argument of <var>[[Fast/Unload standard functions##strip|#STRIP]]</var> lets you designate a <var>#STRIP</var> first-argument value to be nullified. That is, when the value of the first argument is equal to the value of the fourth argument, <var>#STRIP</var> returns a null string. You might use this optional argument for fields that have a "placeholder value" or "default value" which is not actual data.

This argument can be conveniently combined with the
new <var>[[#Length prefix for PUT output values|COUNTED]]</var> options for <var>PUT</var>, because a length-prefixed format allows a reliable, unambiguous representation of a series of null strings.

Combining the new fourth argument, the new <var>COUNTED2</var> option, and the new [[#optn|N option]] of the second argument provides a simpler alternative to FUEL code such as the following:
%VAL = ITEM.STRING(%OCC)
IF %VAL EQ '_' THEN
PUT 0 AS FIXED(2)
ELSE
%LEN = #LEN(%VAL)
PUT %LEN AS FIXED(2)
PUT %VAL
END IF


You can replace the above statements by the more readable and efficient: 
PUT #STRIP(ITEM.STRING(%OCC), 'N', , '_') AS COUNTED2


====New #STRIP type options====

<var>P</var> and <var>N</var> strip-type options are added to the <var>#STRIP</var> function:
<ul>
<li>The new <var>P</var> option strips all but one leading <var class="term">pad</var>-argument characters from the <var>#STRIP</var> first argument returned value, if that value contains a non-zero length string of only <var class="term">pad</var> characters.

<var>P</var>, together with other new Fast/Unload <var>PUT</var> features, provides a simpler alternative to FUEL code such as the following:
%VAL = ITEM.NUMBER(%OCC)
IF %VAL EQ '_' OR %VAL EQ '' THEN
PUT 0 AS FIXED(2)
ELSE
%VAL = #STRIP(%VAL, 'L', '0')
IF %VAL EQ '' THEN
%VAL = '0'
END IF
%LEN = #LEN(%VAL)
PUT %LEN AS FIXED(2)
PUT %VAL
END IF 

You can replace the above statements with the following, which outputs a numeric value with leading zeroes stripped: 
PUT #STRIP(ITEM.NUMBER(%OCC), 'P', '0', '_') AS COUNTED2

Note: A FUEL <var>IF</var> statement oddity is that the precedence of <var>AND</var> and <var>OR</var> are the same.</li>

<li id="optn">The new <var>N</var> option strips neither leading-characters nor trailing-characters.

For an example, see [[#New #STRIP fourth argument|New #STRIP fourth argument]], above.</li>
</ul>

==New and changed commands==


===AUTHCTL VIEW (additional information displayed)===
The <var>[[AUTHCTL command#Example|AUTHCTL]]</var> command output now includes a list of the available sets of control parameters for the external security interface you specify in the command.

===DISPLAY MODMAP (new parameter: <var>UEX</var>)===
The <var>[[DISPLAY MODMAP command|DISPLAY MODMAP]]</var> command now has a <var>UEX</var> parameter that displays the entry point addresses of all defined user exits.

===FREE command (new message)===
Prior to this release, a successful <var>[[FREE command#msg|FREE]]</var> command was not followed by a message indicating success. Under version 7.7, <var>FREE</var> now indicates success with the following message:
M204.0510: FREE command successful; ddname freed 

Also new in this release, a <var>FREE</var> command that takes no action because the specified file does not exist or is not allocated is now followed by an explanatory message:

M204.0509: No action taken by FREE command; ddname not allocated 

In earlier versions, no such message followed. 

===JANUS DEFINE (new parameter: <var>SSLTRUST</var>)===
The <var>[[JANUS DEFINE]]</var> command now has an <var>[[SSLTRUST (JANUS DEFINE parameter)|SSLTRUST]]</var> parameter that indicates that the certificate presented by the other side of a TLS/SSL connection is to be accepted even if it is not signed by a known certifying authority.

===JANUS WEB (additional rule support)===


====Expanded ALLOW/DISALLOW rules====
The <var>[[JANUS WEB]]</var> command <var>ALLOW</var>/<var>DISALLOW</var> rules are updated to include support for these HTTP methods:
<ul>
<li>The RESTful ([https://en.wikipedia.org/wiki/Representational_state_transfer Representational State Transfer]) methods CONNECT, DELETE, OPTIONS, PATCH, and TRACE. </li>

<li>The WebDAV ([http://www.webdav.org/specs/rfc4918.html Distributed Authoring and Versioning]) methods PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, and UNLOCK. </li>
</ul>

====ON rules (method name substitution)====
In a version 7.7 <var>[[JANUS WEB ON|JANUS WEB ON]]</var> command, you can now reference the name of the HTTP method that is associated with the incoming request. To do this, specify an <code>M</code> after the escape (<tt>"</tt>) character, as in:

JANUS WEB WEBPORT ON /TEST/* OPEN FILE TEST CMD 'I "M.*'

A GET request for URL <code>/test/foo</code> would result in the file <code>TEST</code> being opened and the command <code>I GET.FOO</code> being issued. A POST for the same URL would result in the command <code>I POST.FOO</code> being issued.

Note: This behavior is a change from past releases, when <code>"M</code> was simply converted to <code>M</code>.

===LOGINCP or LOGONCP (new)===
Because colons are now valid password characters, the <var>[[LOGINCP or LOGONCP command|LOGINCP]]</var> (LOGIN and Change Password) command replaces the former technique for changing passwords using <var>LOGIN</var>.
Before version 7.7, with <var>LOGIN</var>, you specified <var class="term">oldpassword</var><tt>:</tt><var class="term">newpassword</var> in response to the <code>M204.0347: Password</code> prompt.
With the <var>LOGINCP</var> command, you are prompted and re-prompted for the new password after successful logon:
LOGINCP USER1
M204.0347: Password
M204.0353: USER1 USER1 login 16 JUL 29 12.38
M204.2633: Enter new password
M204.2633: Re-enter new password
M204.0350: New password accepted
M204.0345: CCASTAT updated

<var>LOGONCP</var> is a synonym for <var>LOGINCP</var>.

===ZHPF (new parameters: filename and *)===
The <var>[[ZHPF command|ZHPF]]</var> command checks zHPF ability for the file currently opened by the user.

As of Model 204 7.7, you can specify parameters to <var>ZHPF</var>:
<ul>
<li><var class="term">filename</var>, to check a specific file</li>
<li>An asterisk (<tt>*</tt>), to check local files opened by all users</li>
</ul>

==New and changed parameters==


===CUSTOM (new and changed values)===
====New values====
The following values have been added to the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter in this release:
<ul>
<li>The <code>CUSTOM=23</code> value always truncates the user ID to 10 characters.</li>

<li>The <code>CUSTOM=41</code> value allows recording of data on successful RACF user logins. The login data is shown in RACFRW batch reports.</li>

<li>The <code>CUSTOM=42</code> value allows the editing of procedure names containing the following special characters: comma, equal sign, space, single quote, semicolon.</li>
</ul>

====Changed value====
<ul>
<li>The <code>CUSTOM=11</code> value also supports special-characters for RACF passwords as of version 7.7.</li>
</ul>

===LFSCB (new default/minimum value)===
The default (and minimum) value of <var>[[LFSCB parameter|LFSCB]]</var> is now 8 bytes.

===LITBL (new default/minimum value)===
The default (and minimum) value of <var>[[LITBL parameter|LITBL]]</var> is now 8 bytes.

===MINDEBCL (new)===
The new system parameter, <var>[[MINDEBCL parameter|MINDEBCL]]</var>, can be set in an Online to specify the minimum [[Debugger]] Client build number that can be used with that Online.

===MPDELAY and MPDELAYZ (new)===
For an [[Performance monitoring and tuning#Multiprocessing .28MP.2F204.29|MP/204]] Online, the <var>[[MPDELAY parameter|MPDELAY]]</var> and <var>[[MPDELAYZ parameter|MPDELAYZ]]</var> parameters are added to improve the efficiency of the MP scheduler. They reduce the cost of starting too many new subtasks for the amount of work to be done.

===NUMBUF and NUMBUFG===
As described below in [[#Elimination of BTB buffers|Elimination of BTB buffers]], setting <var>NUMBUFG</var> greater than 0 in version 7.7 forces <var>NUMBUF</var> to 0 (no buffer pool buffers reside below the bar). Not setting <var>NUMBUFG</var> or setting it to 0 (no buffers above the bar) allows the calculation of BTB buffers to remain as in previous versions.

===SCHDOFL and SCHDOFLZ (new minimum value)===
The new minimum value of <var>[[SCHDOFL parameter|SCHDOFL]]</var> and <var>[[SCHDOFLZ parameter|SCHDOFLZ]]</var> is 0. Before Model 204 7.7, their minimum allowed value was 1.

===SCHDOFLS (new)===
For z/OS system customers using <var class="product">Model 204</var> zIIP support, the new <var>[[SCHDOFLS parameter|SCHDOFLS]]</var> system parameter helps you to regulate the zIIP processor workload.

<var>SCHDOFLS</var> specifies both of the following:
<ul>
<li>The target number of threads on the zIIP offload queue before a non-SRB MP subtask is dispatched to help the zIIP subtasks. </li>

<li>If started, how aggressively non-SRB MP subtasks pick up work from the zIIP offload queue. </li>
</ul>

This parameter applies to z/OS only.

===SCHDOPT (change to X'20' bit processing)===
The <var>[[SCHDOPT parameter|SCHDOPT]]</var> X'20' bit prevents the maintask from running work that is intended to run on a zIIP subtask (when zIIP subtasks are defined and activated). As of Model 204 7.7, even when this bit is off, the maintask will run some of the zIIP work only if the zIIP subtasks appear to be saturated. Saturation is defined as a zIIP subtask queue length of at least <code>[[SCHDOFLZ parameter|SCHDOFLZ]]*[[AMPSUBZ parameter|AMPSUBZ]]</code>.

Formerly, this saturation requirement was absent, allowing the maintask to take on more (possibly too much) of the zIIP workload.

===SERVSIZE (new default/minimum value)===
The minimum value for <var>[[SERVSIZE parameter|SERVSIZE ]]</var> is changed from zero to 65536. If <var>SERVSIZE</var> is explicitly set in CCAIN and its value is less than 64K, the following message is issued:
M204.1149: SERVSIZE has been set to its minimum value: 65536


If <var>SERVSIZE</var> was not set but was [[Defining the runtime environment (CCAIN)#Sizing user server areas|calculated by the system]] to a value less than 64K, the following message is issued:
M204.0163: SERVSIZE increased to 65536


This change is propagated by zap maintenance to versions 7.6, 7.5, and 7.4 of Model 204. 

===TCPTYPE (new IPV6 values)===
As part of the version 7.7 [[#IPV6|support for IPV6]], three new optional (IPV6-address-only) values are added to the <var>[[TCPTYPE parameter|TCPTYPE]]</var> parameter:
IBMV6
BPXV6
IUCVV6


==Performance enhancements==

===Elimination of BTB buffers===
As of version 7.7, any use of above-the-bar buffer pool (as invoked by a setting of the <var>[[NUMBUFG parameter|NUMBUFG]]</var> parameter greater than 0) will force all buffer pool buffers above the bar — no below-the-bar buffers will exist. In this case, the <var>[[NUMBUF parameter|NUMBUF]]</var> and <var>[[MINBUF parameter|MINBUF]]</var> parameters will be forced to 0, and the other parameters that affect BTB storage (<var>MAXBUF</var>, <var>SPCORE</var>, <var>LDKBMWND</var>, and <var>NLRUQ</var>) will be ignored.

If you set <var>NUMBUFG</var> to 0, all buffers will be below the bar, and the settings of the BTB-related parameters will be respected and calculated as in pre-7.7 versions.

===Increase in request limit for number of images, screens, and menus===
These limits are increased to 4095 per request:
<ul>
<li>The total number of [[Images|images]] for all blocks (formerly 256)</li>

<li>The maximum number of [[Menu statement or block#Menus and screens|menus and screens]] combined (formerly 256)</li>
</ul>

===Large checkpoint data sets===
Support is added for large data sets (as many as 16 million tracks) for the Model 204 Checkpoint facility [[Checkpoints: Storing before-images of changed pages#Creating the CHKPOINT.2FCHKPNT .28and CHKPNTS.29 data set|CHKPOINT or CHKPNTS data sets]]. For details, see [[System_and_media_recovery#ROLL_BACK_processing.2C_Pass_2|ROLL BACK processing, Pass 2]].

==Statistics enhancements==

===BLKO===
The [[Using system statistics#System performance statistics|performance statistic]] BLKO now also reports invisible users that are blocked out. In previous releases, invisible users were not reported and BLKO remained virtually zero. The new BLKO value is more precise, and by summing BLKO, WTSV, BLKI, REDY, SWPG, and RUNG, you can now approximate USRS (average active users).

For the <var>MONITOR</var> command, the [[ONLINE monitoring#User information in formatted displays|QUE column]] now reports new values OFFO and OFFI instead of OFFQ for invisible users:
<ul>
<li>OFFO is invisible and blocked out. </li>
<li>OFFI is invisible and blocked in. </li>
</ul>

The BLKO QUE value continues to mean blocked out and visible (on some queue), and BLKI means blocked in and visible.

===CCATDIFF and CCATDIFH===
The [[Using system statistics#Description of statistics|CCATDIFF]] user and since-last statistic gets incremented each time a user allocates a CCATEMP page, and it gets decremented each time a user frees a page. Its value is not allowed to drop below zero. In the event of a CCATEMP page shortage, CCATDIFF gives system managers the possibility of determining a particular user that might be primarily responsible.

Note: CCATDIFF is a rough guide, not definitive: it might give false high readings for some users, but it will indicate a user whose usage is extremely extraordinary. 

[[Using system statistics#Description of statistics|CCATDIFH]] is a since-last statistic that reports a request's CCATDIFF since-last highwater mark, useful to retrospectively determine which request was responsible for a massive CCATEMP usage spike. For example, it will record a request that allocated a large number of CCATEMP pages but freed the pages before the request ended.

==Other enhancements==

===MODEL 6 screen size and back-paging===
As of Model 204 version 7.7 (and 7.5 or 7.6 with maintenance applied), a large <var>[[LOUTPB parameter|LOUTPB]]</var> value for [[Terminal MODEL 6 support|MODEL 6]] geometries is allowed, even if screen back-paging has been enabled.

In previous releases, during initialization, if back-paging was enabled for the IODEV, <var>LOUTPB</var> was automatically reset to the limit that supported back-paging.

Back-paging will now be disabled for any terminal with a <code>MODEL 6</code> screen geometry that requires more than 6142 bytes.

===ECF calls to the IBM IDCAMS utility===
The new <var>IDCAMS</var> option for the <var>[[External Call Facility#module|External Module]]</var> statement of the Model 204 [[External Call Facility]] lets a SOUL program invoke IDCAMS without using the SYSIN and SYSPRINT DD statements. Instead, the Model 204 Universal Buffer is used to pass the input lines and receive the output lines from IDCAMS.

===Running ECF requests under the invoking user’s profile===
Unless the new system parameter <var>[[ECPRIV parameter|ECPRIV]]</var> 4 bit is set, the job invoked by a privileged [[External Call Facility]] statement at a site where an external authorizer (ACF2, RACF, or Top/Secret) is used runs under the external-authorizer profile of the user that invokes the External Call, rather than under the job's external-authorizer profile.

Prior to version 7.7, such a job always ran under the job's external-authorizer profile, so this is a [[#Profile used for running ECF requests|backward compatibility]] issue.

==Debugger updates==

===SoftSpy authorization===

SoftSpy and Muse are now authorized using the standard zap AUTH mechanism.

EDIT CONFIG is no longer used to enter authorization keys, and the second (key entry) screen of SPY EDIT CONFIG no longer appears.

===SoftSpy Error message for DBCSENV===

As in previous releases, SoftSpy is not supported in a DBCS (double-byte character set) environment. As of version 7.7, if the CCAIN parameter DBCSENV is set to a non-zero value, the SPY command is rejected with the following message:
Message 207: SoftSpy may not be used in a DBCS environment.

===Debugger Client version information display on mainframe===
As of version 7.7 and Client build 64, the <var class="product">Janus/TN3270 Debugger</var> Client sends its build and tag number to the mainframe, and this information is displayed in message [[MSIR.1077]]:
MSIR.1077: Begin debug session, user 3, client: Build: 64, Tag: 2 (Janus debugger session)

This information is not sent if the Debugger Client build number is less than 64, and the mainframe side views all Client versions prior to build 64 as build 63.

The build number, which identifies Client versions, is displayed in the Client Audit Trail tab at start up:
2016 07 30 17:21:47 The Rocket Software Debugger Client
2016 07 30 17:21:47 Build: 65 (01 August 2016) Tag: 1 GA


You can also view the build number of the Client at any time by selecting Help > About. And as of Client build 65, the build number is displayed by the Client function <var>&&buildNumber()</var>.

===Enforcing use of a minimum version of the Debugger Client===
Normally, when you use the TN3270 or Janus Debugger, no restrictions are placed on which version of the Debugger workstation client is used.
As of Client build 65 and Model 204 7.7, you can force Clients to have at least a minimum build number in order to invoke a debugging session with your Online. The new Model 204 system parameter <var>[[MINDEBCL parameter|MINDEBCL]]</var> sets such a minimum.

If you set <var>MINDEBCL</var> to a positive value, use a version of the Debugger Client whose build number is less than <var>MINDEBCL</var>, and invoke a debugging session, the debugging session is rejected. An error message is shown in your browser and at the Client, calling for a Client upgrade.

You also see the following error on the Online's Audit Trail (and on the terminal if you are using <code>TN3270 DEBUG ON</code>):
MSIR.1079: Debugger Client Build: ''xx'' < MINDEBCL: ''yy'' debugger client connection refused


==Compatibility issues==

===APSYPAGE parameter cannot be non-zero===
(Applies to the IBM z/OS system.)
The <var>APSYPAGE</var> parameter was disabled (but still allowed) in version 7.6. As of version 7.7, if <var>APSYPAGE</var> is non-zero, the Online will not come up and the following error message will appear:

M204.2958: APSYPAGE is obsolete as of 7.6.
Rocket recommends using RESPAGE and/or TEMPPAGE as the alternative

See [[APSYPAGE parameter]] for information about alternatives to <var>APSYPAGE</var>.

===Unlabeled FDV statement compilation errors===
Version 7.7 introduces an edge case incompatibility by disallowing code which is very questionable or clearly wrong; that is, previously the compiler allowed pretty much any statements between the label and the FDV. Such statements are no longer allowed.

For example, the following was allowed in older versions of Model 204:
a: audit 'About to FDV'
fdv foo
b: frv in a

Inserting SOUL code between a label and an FDV statement is no longer allowed, and so the result of the above is:

M204.0311 Unacceptable statement reference

This change is propagated by zap maintenance to versions 7.6 and 7.5 of Model 204.

===KOMM addressing changes===
<ul>
<li>KU is no longer 4K addressable from KOMM. It has been relocated to KOMM+1100 and must be addressed using grande (‘G’) instructions.</li>
<li>KHEOC has been renamed to KGEOC.</li>
<li>KUUSRNO has been renamed to KBUSRNO.</li>
<li>In addition, all KUP… fields have been removed and replaced by their 64-bit equivalent KUG… fields. 
For example, before 7.7, VTBL might be addressed by using <code>L R1,KUPVT</code>. 
As of version 7.7, that reference would require <code>LG R1,KUGVT</code>.</li>
</ul>

For context, see [[Customizing functions and translation tables#Converting user-written functions|Converting user-written functions]].

===JANUS WEB ON -- "M substitution===
In the command for a <var>JANUS WEB ON</var> rule, <code>"M</code> can now be used to specify a method name.
This behavior is a change from past releases, when <code>"M</code> was simply converted to <code>M</code>. See [[#ON rules .28method name substitution.29|JANUS WEB ON rules (method name substitution)]] for details.

===Journal format compatibility===
A recovery code error unintentionally allowed recovery to be run using Model 204 7.6 against a version 7.5 journal, and vice versa. Although the error was benign because the journal formats were the same in those versions, mixing of journal versions and Model 204 versions is no longer allowed.

===Profile used for running ECF requests===
As [[#ecfprofile|described earlier]], the default external-authorizer (ACF2, RACF, or Top/Secret) profile under which a job invoked by a privileged ECF statement runs is changed in version 7.7. Instead of such a job running under the job's external-authorizer profile (as it did prior to 7.7), the job runs by default in 7.7 under the user's external-authorizer profile.

The default behavior can be changed by turning on the new system parameter <var>[[ECPRIV parameter|ECPRIV]]</var> 4 bit.
===$ListNew cannot be used in Initial clause===
<var>$ListNew</var> cannot be used in the <var>Initial</var> clause of a [[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change was introduced as zap maintenance in versions 7.5, 7.6, and 7.7 of Model 204.

==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 updated messages==

See [[New and updated messages in Model 204 version 7.7|New and updated messages in Model 204 version 7.7]] for details.

[[Category: Release notes|Model 204 version 7.7]]

Release notes for Model 204 version 7.7

2024-09-18T19:38:15Z

Tom: /* Operating system and hardware requirements */

These release notes list the enhancements and other changes contained in Model 204 version 7.7.

==Overview==
These release notes contain installation and features information for the Rocket Model 204 version 7.7 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.7. For a full list of features, refer to the Table of Contents.
<table>
<tr class="head"><th>Category</th>
<th>Feature</th></tr>

<tr>
<td>Performance</td>
<td>
<ul>
<li>Continued expansion of 64-bit addressability. See [[#Elimination of BTB buffers|Elimination of BTB buffers]]. </li>

<li>Greater zIIP processor availability: M204 HPO and Fast/Unload HPO. See [[#zIIP exploitation|zIIP exploitation]]. </li>

<li>zIIP load tuning. See [[#MPDELAY and MPDELAYZ (new)|MPDELAYZ]], [[#SCHDOFLS (new)|SCHDOFLS]], [[#SCHDOPT (change to X'20' bit processing)|SCHDOPT]]. </li>

<li>Essential removal of application limits on the [[#Increase in request limit for number of images, screens, and menus|number of images, screens, and menus]].</li>

<li>Support for large data sets (as many as 16 million tracks) for the Model 204 Checkpoint facility [[Checkpoints: Storing before-images of changed pages#Creating the CHKPOINT.2FCHKPNT .28and CHKPNTS.29 data set|CHKPOINT or CHKPNTS data sets]]. See [[System_and_media_recovery#ROLL_BACK_processing.2C_Pass_2|ROLL BACK processing, Pass 2]].</li>
</ul>
</td></tr>

<tr>
<td>Security</td>
<td>
<ul>
<li>Stronger cryptographic algorithms: SHA-384, SHA-512. See [[#"SSL" String methods|"SSL" String methods]], [[#New DigestAlgorithm values|New DigestAlgorithm values]], and [[#New default certificate-signing algorithm|New default certificate-signing algorithm]]. </li>

<li>Longer RSA keys (as many as 4096 bits). See [[#Janus Network Security ciphers and private keys|Janus Network Security ciphers and private keys]]. </li>

<li>Support for [[#Long password support|longer and mixed-case login passwords]]. </li>
</ul>
</td><tr>

<tr>
<td nowrap>Add-on enhancements</td>
<td>
<ul>
<li>A more versatile Fast/Unload through [[#Integration of Fast/Unload with the Online load module|integration with Model 204]]. </li>

<li>Janus products' [[#Support for IPV6|support for the IPV6 network protocol]], expanding the network address space from 32 to 128 bits. </li>
</ul>
</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 3.1. (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.7 operates as an APF authorized load module, as required by many 7.7 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.3.</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.7 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>

===Model 204 compatibility with operating systems===

For information on Model 204 certification with IBM operating systems, see [[Model 204 system requirements]].

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

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

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

==SOUL (User Language) enhancements==

===New and changed classes and methods===

====New exception class: WriteError====
<var>[[WriteError class|WriteError]]</var> exceptions are thrown by the <var>Close</var>, <var>WriteBlock</var>, <var>WriteRecord</var>, and <var>WriteRecords</var> methods in the [[Dataset class]] if they encounter a full output <var>Dataset</var> object.

====New default certificate-signing algorithm====
[[Janus Network Security]] as well as the <var>[[Stringlist_class|StringList]]</var> methods <var>[[AppendSignedCertificate (Stringlist function)|AppendSignedCertificate]]</var> and <var>[[AppendSignedClientCertificate (Stringlist function)|AppendSignedClientCertificate]]</var> methods have changed their default signature algorithm from SHA-1 to SHA-256.

This change is propagated by zap maintenance to versions 7.6 and 7.5 of Model 204.

===="SSL" String methods====
These new methods are added:
<table>
<tr class="head"><th>Method</th><th>Description</th></tr>
<tr><td>[[SHA384digest (String function)|SHA384digest]]</td><td>SHA-384 digest</td></tr>
<tr><td>[[SHA512digest (String function)|SHA512digest]]</td><td>SHA-512 digest</td></tr>
</table>

====New LoadMsgctl method====
The new <var>[[LoadMsgctl (XmlDoc subroutine)|LoadMsgctl]]</var> method lets you view what <var class="product">Model 204</var> messages have been affected by <var>[[MSGCTL command|MSGCTL]]</var> commands. The method also displays the current attributes of those messages. 

In addition, to better understand the effect of the <var>MSGCTL</var> command, the [[RKTools]] <code>SIRIUS</code> file will contain a procedure you can use to display the <var>MSGCTL</var> commands that have been specified in the Online session.

====New DigestAlgorithm values====
Values <var>SHA384</var> and <var>SHA512</var> are added to the [[DigestAlgorithm enumeration]].

====Method variable invocation====
[[Method variables]] can now be invoked using <code>%var()</code> or <code>%obj:var()</code>, as in JavaScript.

====X509CertificateToXmlDoc method support for unknown elements====
A certificate's <code><RelativeDistinguishedName></code> element can contain a wide variety of attributes that <var>X509CertificateToXmlDoc</var> does not understand. Under Model 204 7.6 and earlier, this results in a parse exception, but under 7.7 and later, such attributes are added as <code><unknown></code> elements with an <code><ObjectIdentifier></code> element that indicates the ASN.1 object identifier.

Note: You are advised not to refer to such an <code><unknown></code> element in your programs, since future updates to the <var>X509CertificateToXmlDoc</var> method might add support for the element, in which case the element name will change to a proper name. If such an element is of interest, [[Contacting Rocket Software Technical Support|contact Rocket Software technical support]]. 

====Resulting element length in "ToXmlDoc" String methods====
Prior to version 7.7 of Model 204, the <var>[[DerToXmlDoc (String function)|DerToXmlDoc]]</var>, <var>[[X509CertificateToXmlDoc (String function)|X509CertificateToXmlDoc]]</var>, <var>[[X509CrlToXmlDoc (String function)|X509CrlToXmlDoc]]</var>, and
<var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var> methods failed if input to them created any element in the result <var>XmlDoc</var> with a text child whose length exceeded 650 characters.
An example of such input is a 4096-bit key (which requires 1024 hex characters).

As of version 7.7, the lengths of the created text nodes are not restricted.

====LDAP request length limit====
Prior to version 7.7 of Model 204, the SOUL [[LDAP class#limit|LDAP client buffers]] allowed a limit of 6144 bytes per request. As of 7.7, the limit is increased to 8184.

===New XHTML entities for square-bracket characters===
[ and ] are newly supported as [[XML processing in Janus SOAP#Entity references|XMHTL entities]] (notably in the [[U (String function)#brackets|U method]]). This provides a better approach to specifying square brackets (such as for [[XPath#Some notes on XPath usage|XPath]] expressions) than the formerly recommended use of <var>Static</var> %variables initialized to the correct values.

This change is propagated by zap maintenance to version 7.6 of Model 204.

For example, to produce an XPath expression equivalent to the following:
<nowiki>*/pers[@name="Hector"] </nowiki>
Code like this was recommended under version 7.5 of Model 204:
%lsq is string len 1 static initial('&#x5B;'):u
%rsq is string len 1 static initial('&#x5D;'):u
. . .
%myXmldoc:print('*/pers' %lsq '@name="Hector"' %rsq) 

Under version 7.6 and above, you can instead use the new entities and avoid the declarations, concatenations, and runtime conversions required above:
%myXmldoc:print('*/pers[@name="Hector"]':u)

===Procedure names can begin with zero===
Formerly, a procedure name was not allowed to begin with a zero or a minus sign. As of version 7.7, a procedure name can begin with a zero, and alphanumeric procedure names can begin with a minus sign (<tt>-</tt>), which is interpreted as a hyphen. For example, <code>00123</code>, <code>-1myproc</code>, and <code>-myproc</code> are valid procedure names.

See the <var>[[PROCEDURE command|PROCEDURE]]</var> command for details. 

===Assert statement support for Info expressions===
The SOUL <var>[[Assert statement|Assert]]</var> statement allows the optional parameter <var>Info</var> to provide additional output information. As of version 7.7, the <var>Info</var> phrase may contain any valid SOUL expression, including a method call or $function. The expression, which must be enclosed in parentheses, is evaluated only in the case of an <var>Assert</var> failure.

A simple example is:
assert %x gt 0, info ('abc' with 'def') 

<blockquote class="note">
Note: This enhancement introduces a slight backward incompatibility: An <var>Assert</var> statement like the following, whose <var>Info</var> value begins with an opening parenthesis but has no closing parenthesis, compiled without error prior to version 7.7: 
assert %x gt 0, info (

From 7.7 on, such a statement produces a compilation error, because the compiler expects an expression after the open parenthesis. 
</blockquote>

==Security enhancements==
===Long password support===

Logon passwords, maintained in CCASTAT, can now contain as many as 127 characters.
 Also, passwords and passphrases can now contain one or more embedded spaces. (Leading and trailing spaces are stripped.)

The long password feature includes support for: 
<ul>
<li><var>[[LOGIN or LOGON command|LOGON]]</var> command</li>
<li><var>[[LOGINCP or LOGONCP command|LOGONCP]]</var> command, used to change a password</li>

<li><var>[[LOGCTL command: Modifying user ID entries in the password table|LOGCTL C USERID]]</var> command</li>

<li><var>[[$Sir_Login]]</var> function</li>

<li>Mixed-case passwords (if the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter includes the value 11)</li>

<li>[[Storing_security_information_(CCASTAT)|CCASTAT]] data sets created with or without password expiration support</li>

<li>Long passwords (passphrases) for use with the following [[Security interfaces overview|external security interfaces]]: CA-ACF2 MVS, Security Server (formerly RACF), and CA-Top Secret</li>
</ul>
Note: This feature is available for logon passwords only; it does not apply to file passwords.

No changes to CCASTAT and no new CCAIN parameters are required to enable long password support.
In order to allow embedded blanks in passwords passed on [[IFSTRTN_(IFAM2)_(HLI_function)|IFSTRTN]] calls, a semicolon is required as the password delimiter and the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter 24 value must be set.

For additional security enhancements in version 7.7, see [[#Janus Network Security ciphers and private keys|Janus Network Security ciphers and private keys]] as well as [[#"SSL" String methods|"SSL" String methods]], [[#New DigestAlgorithm values|New DigestAlgorithm values]], and [[#New default certificate-signing algorithm|New default certificate-signing algorithm]].

==Janus product enhancements==

===Support for IPV6===
As of version 7.7, customers can use the [[Janus products]] in an IPV6 (Internet Protocol Version 6) environment. Before this release, all Janus commands and parameters were able to accommodate IPV4 addresses only. IPV6 addresses expand the network address space from 32 to 128 bits.

These parameters, commands, and functions support IPV6 under version 7.7 of Model 204:

<table>
<tr class="head"><th>Commands</th><th>System parameter</th><th>SOUL</th></tr>
<tr><td nowrap>
JANUS CLSOCK and JANUS SRVSOCK 
JANUSDEBUG and JANUS WEB DEBUG 
JANUS DEFINEIPGROUP 
JANUS DEFINE BINDADDR 
JANUS DISIPG 
JANUS DISUSG 
JANUS TRACE 
JANUS WEB ALLOW
</td>

<td nowrap>
TCPTYPE 
(see [[#tcptype|TCPTYPE (new IPV6 values)]])
</td>

<td nowrap>
$Web_IPAddr 
LocalHost (UdpSocket property)
</td></tr>
</table>

===Janus Network Security ciphers and private keys===
Support for certificates signed using [[DigestAlgorithm_enumeration|SHA-384 and SHA-512]] are added to [[Janus Network Security]]. This makes it possible to generate certificates signed with these algorithms and to accept server or client certificates signed with these algorithms.

In addition, support is added for RSA keys that are as many as 4096 bits in length. You can now generate and sign 4096-bit keys and use them in client and server certificates using <var class="product">Janus Network Security</var> application as well as its associated and related methods, including:
<table>
<tr class="head"><th>Class</th><th>Method</th></tr>
<tr><td>System</td>
<td><var>[[GeneratedPrivateKey (System function)|GeneratedPrivateKey]]</var></td></tr>

<tr><td rowspan="4">Stringlist</td>
<td><var>[[AppendCertificateRequest (Stringlist function)|AppendCertificateRequest]]</var></td></tr>

<tr><td><var>[[AppendGeneratedPrivateKey (Stringlist subroutine)|AppendGeneratedPrivateKey]]</var></td></tr>

<tr><td><var>[[AppendSignedCertificate (Stringlist function)|AppendSignedCertificate]]</var></td></tr>

<tr><td><var>[[AppendSignedClientCertificate (Stringlist function)|AppendSignedClientCertificate]]</var></td></tr>

<tr><td rowspan="4">String</td>
<td><var>[[CertificateRequest (String function)|CertificateRequest]]</var> </td></tr>

<tr><td><var>[[ClientCertificateRequest (String function)|ClientCertificateRequest]]</var> </td></tr>

<tr><td><var>[[RSAPrivateKeyToXmlDoc (String function)|RSAPrivateKeyToXmlDoc]]</var> </td></tr>

<tr><td><var>[[SignedCertificate (String function)|SignedCertificate]]</var> </td></tr>
</table>

===Janus Web Server rules===
The following changes have been made in version 7.7:
<ul>
<li>Janus Web used to automatically implement [[Defining Web rules#Notes|two web server ON rules]] to set up access to the Janus Web sample home page and to demonstration application procedures. These rules were removed in version 7.6 (by zap maintenance) and are not present in version 7.7.</li>

<li>You can now substitute an HTTP method name in the command for a <var>JANUS WEB ON</var> rule. See [[#ON rules (method name substitution)|ON rules (method name substitution)]] for details.</li>

<li>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 (after zap 77Z088 in version 7.7, or after zap 76Z418 in version 7.6) unless overridden by user-added rules.

<blockquote class="note">
Note: With version 7.7 zap 77Z090 or version 7.6 zap 76Z420, you can make the default <var>ALLOW</var> rule as it was in version 7.5 and earlier (<code>ALLOW *</code>). To do so, turn on the 1 bit of the <var>[[WEBDFLT parameter|WEBDFLT]]</var> parameter: 
RESET WEBDFLT=1
</blockquote></li>

<li>As described below in [[#JANUS WEB (additional rule support)|JANUS WEB (additional rule support)]], the <var>JANUS WEB</var> command <var>ALLOW</var> and <var>DISALLOW</var> rules are updated to include support for RESTful and WebDAV HTTP methods. </li>
</ul>

===Janus Web access to HTTP authorization and authentication headers===
Under version 7.7, Janus Web lets you access HTTP user authentication headers. You can capture the HTTP "Authorization" request header value, and you can set the "WWW-Authenticate" response header. See [[Janus Web Server security#Authorization and WWW-Authenticate headers|Authorization and WWW-Authenticate headers]].

==Fast/Unload enhancements==

===Integration of Fast/Unload with the Online load module ===

Previously (for all versions of <var class="product">Fast/Unload</var> through 4.7), the standalone <code>FUNLOAD</code> load module was downloaded and linked separately and independently from Model 204. Starting with version 7.7 of Model 204:
<ul>
<li><var class="product">Fast/Unload</var> is entirely linked with the Model 204 Online load module. </li>

<li>Maintenance zaps applied to the Online load module include all <var class="product">Fast/Unload</var> maintenance.</li>

<li>The version number of <var class="product">Fast/Unload</var> is the same as the version number of Model 204. </li>

<li>If you are authorized for Fast/Unload, the authorization zap for the ONLINE load module will contain authorization for Fast/Unload. The authorization zap used for previous releases of FUNLOAD should not be applied to the FUNLOAD module in 7.7.</li>
</ul>

Under 7.7, the Online load module can be linked with an ALIAS (the standard one is FUNLOAD) and an alternate ENTRY. This alias is functionally indistinguishable from the standalone <var class="product">Fast/Unload</var> FUNLOAD load module installed for all previous versions of <var class="product">Fast/Unload</var>.

The integration of Fast/Unload with the Online load module also makes additional DDnames available to PGM=FUNLOAD for possible problem diagnosis by Rocket Technical Support. These DDnames are <code>CCASNAP</code>, <code>CCAAUDIT</code>, and <code>CCAPRINT</code>, and they are described in [[Fast/Unload invocation#ccadd|Fast/Unload invocation]].

A significant benefit of running Fast/Unload integrated with Model 204 and not standalone is the ability to take advantage of zIIP processing, as described next in the "zIIP exploitation" section.

===zIIP exploitation===
If you have an authorization zap that contains both of the following, your standalone PGM=FUNLOAD jobs will run on a zIIP processor, if one is available:
<ul>
<li><var class="product">[[Performance monitoring and tuning#Offloading Model 204 work to zIIP processors|M204 HPO]]</var>, the zIIP-support product of Model 204

PGM=FUNLOAD automatically supplies the necessary Model 204 parameters to enable zIIP exploitation. </li>

<li>The <var class="product">[[Fast/Unload overview#fuhpo|Fast/Unload HPO]]</var> product </li>
</ul>

===New #VIEW204 function===
The <var>[[Fast/Unload standard functions#.23VIEW204: Value of Model 204 parameter|#VIEW204]]</var> function returns the value of the [[List of Model 204 parameters|Model 204 parameter]] you specify as an argument.

===PUT statement enhancements===


====Length prefix for PUT output values====

New <var>[[Fast/Unload PUT statement#PUT|PUT]]</var> statement syntax is added to insert a one-byte or two-byte binary integer, containing the byte length of a <var>PUT</var> value, in the output stream before the value.

For better readability and lower CPU cost than the techniques currently used to achieve the same result, the <var>AS</var> clause of a <var>PUT</var> statement will now allow the <var>COUNTED</var> keyword:
... PUT info .. AS [format] COUNTED[1|2] 

For example, <code>PUT FIRST.NAME AS COUNTED2</code> puts the first occurrence of field <code>FIRST.NAME</code> as a string value, preceded by a two-byte binary integer containing the length of that occurrence.

With this feature, you can replace FUEL code such as the following: 
%VAL = ITEM.CODE(%OCC)
%LEN = #LEN( %VAL )
PUT %LEN AS FIXED(2)
PUT %VAL 
With: 
PUT %VAL AS COUNTED2 

====#function as PUT "info" argument====

New in this version, a #function call is allowed as the <var>PUT</var> <var class="term">info</var> argument. For example, instead of FUEL code such as the following:
%VAL = #STRIP(ITEM.VALUE(%OCC), 'L', 0)
PUT %VAL 
You can use this more readable and somewhat more efficient equivalent:
PUT #STRIP(ITEM.VALUE(%OCC), 'L', 0) 

===#STRIP function enhancements===


====New #STRIP fourth argument====

The new fourth argument of <var>[[Fast/Unload standard functions##strip|#STRIP]]</var> lets you designate a <var>#STRIP</var> first-argument value to be nullified. That is, when the value of the first argument is equal to the value of the fourth argument, <var>#STRIP</var> returns a null string. You might use this optional argument for fields that have a "placeholder value" or "default value" which is not actual data.

This argument can be conveniently combined with the
new <var>[[#Length prefix for PUT output values|COUNTED]]</var> options for <var>PUT</var>, because a length-prefixed format allows a reliable, unambiguous representation of a series of null strings.

Combining the new fourth argument, the new <var>COUNTED2</var> option, and the new [[#optn|N option]] of the second argument provides a simpler alternative to FUEL code such as the following:
%VAL = ITEM.STRING(%OCC)
IF %VAL EQ '_' THEN
PUT 0 AS FIXED(2)
ELSE
%LEN = #LEN(%VAL)
PUT %LEN AS FIXED(2)
PUT %VAL
END IF


You can replace the above statements by the more readable and efficient: 
PUT #STRIP(ITEM.STRING(%OCC), 'N', , '_') AS COUNTED2


====New #STRIP type options====

<var>P</var> and <var>N</var> strip-type options are added to the <var>#STRIP</var> function:
<ul>
<li>The new <var>P</var> option strips all but one leading <var class="term">pad</var>-argument characters from the <var>#STRIP</var> first argument returned value, if that value contains a non-zero length string of only <var class="term">pad</var> characters.

<var>P</var>, together with other new Fast/Unload <var>PUT</var> features, provides a simpler alternative to FUEL code such as the following:
%VAL = ITEM.NUMBER(%OCC)
IF %VAL EQ '_' OR %VAL EQ '' THEN
PUT 0 AS FIXED(2)
ELSE
%VAL = #STRIP(%VAL, 'L', '0')
IF %VAL EQ '' THEN
%VAL = '0'
END IF
%LEN = #LEN(%VAL)
PUT %LEN AS FIXED(2)
PUT %VAL
END IF 

You can replace the above statements with the following, which outputs a numeric value with leading zeroes stripped: 
PUT #STRIP(ITEM.NUMBER(%OCC), 'P', '0', '_') AS COUNTED2

Note: A FUEL <var>IF</var> statement oddity is that the precedence of <var>AND</var> and <var>OR</var> are the same.</li>

<li id="optn">The new <var>N</var> option strips neither leading-characters nor trailing-characters.

For an example, see [[#New #STRIP fourth argument|New #STRIP fourth argument]], above.</li>
</ul>

==New and changed commands==


===AUTHCTL VIEW (additional information displayed)===
The <var>[[AUTHCTL command#Example|AUTHCTL]]</var> command output now includes a list of the available sets of control parameters for the external security interface you specify in the command.

===DISPLAY MODMAP (new parameter: <var>UEX</var>)===
The <var>[[DISPLAY MODMAP command|DISPLAY MODMAP]]</var> command now has a <var>UEX</var> parameter that displays the entry point addresses of all defined user exits.

===FREE command (new message)===
Prior to this release, a successful <var>[[FREE command#msg|FREE]]</var> command was not followed by a message indicating success. Under version 7.7, <var>FREE</var> now indicates success with the following message:
M204.0510: FREE command successful; ddname freed 

Also new in this release, a <var>FREE</var> command that takes no action because the specified file does not exist or is not allocated is now followed by an explanatory message:

M204.0509: No action taken by FREE command; ddname not allocated 

In earlier versions, no such message followed. 

===JANUS DEFINE (new parameter: <var>SSLTRUST</var>)===
The <var>[[JANUS DEFINE]]</var> command now has an <var>[[SSLTRUST (JANUS DEFINE parameter)|SSLTRUST]]</var> parameter that indicates that the certificate presented by the other side of a TLS/SSL connection is to be accepted even if it is not signed by a known certifying authority.

===JANUS WEB (additional rule support)===


====Expanded ALLOW/DISALLOW rules====
The <var>[[JANUS WEB]]</var> command <var>ALLOW</var>/<var>DISALLOW</var> rules are updated to include support for these HTTP methods:
<ul>
<li>The RESTful ([https://en.wikipedia.org/wiki/Representational_state_transfer Representational State Transfer]) methods CONNECT, DELETE, OPTIONS, PATCH, and TRACE. </li>

<li>The WebDAV ([http://www.webdav.org/specs/rfc4918.html Distributed Authoring and Versioning]) methods PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, and UNLOCK. </li>
</ul>

====ON rules (method name substitution)====
In a version 7.7 <var>[[JANUS WEB ON|JANUS WEB ON]]</var> command, you can now reference the name of the HTTP method that is associated with the incoming request. To do this, specify an <code>M</code> after the escape (<tt>"</tt>) character, as in:

JANUS WEB WEBPORT ON /TEST/* OPEN FILE TEST CMD 'I "M.*'

A GET request for URL <code>/test/foo</code> would result in the file <code>TEST</code> being opened and the command <code>I GET.FOO</code> being issued. A POST for the same URL would result in the command <code>I POST.FOO</code> being issued.

Note: This behavior is a change from past releases, when <code>"M</code> was simply converted to <code>M</code>.

===LOGINCP or LOGONCP (new)===
Because colons are now valid password characters, the <var>[[LOGINCP or LOGONCP command|LOGINCP]]</var> (LOGIN and Change Password) command replaces the former technique for changing passwords using <var>LOGIN</var>.
Before version 7.7, with <var>LOGIN</var>, you specified <var class="term">oldpassword</var><tt>:</tt><var class="term">newpassword</var> in response to the <code>M204.0347: Password</code> prompt.
With the <var>LOGINCP</var> command, you are prompted and re-prompted for the new password after successful logon:
LOGINCP USER1
M204.0347: Password
M204.0353: USER1 USER1 login 16 JUL 29 12.38
M204.2633: Enter new password
M204.2633: Re-enter new password
M204.0350: New password accepted
M204.0345: CCASTAT updated

<var>LOGONCP</var> is a synonym for <var>LOGINCP</var>.

===ZHPF (new parameters: filename and *)===
The <var>[[ZHPF command|ZHPF]]</var> command checks zHPF ability for the file currently opened by the user.

As of Model 204 7.7, you can specify parameters to <var>ZHPF</var>:
<ul>
<li><var class="term">filename</var>, to check a specific file</li>
<li>An asterisk (<tt>*</tt>), to check local files opened by all users</li>
</ul>

==New and changed parameters==


===CUSTOM (new and changed values)===
====New values====
The following values have been added to the <var>[[CUSTOM parameter|CUSTOM]]</var> parameter in this release:
<ul>
<li>The <code>CUSTOM=23</code> value always truncates the user ID to 10 characters.</li>

<li>The <code>CUSTOM=41</code> value allows recording of data on successful RACF user logins. The login data is shown in RACFRW batch reports.</li>

<li>The <code>CUSTOM=42</code> value allows the editing of procedure names containing the following special characters: comma, equal sign, space, single quote, semicolon.</li>
</ul>

====Changed value====
<ul>
<li>The <code>CUSTOM=11</code> value also supports special-characters for RACF passwords as of version 7.7.</li>
</ul>

===LFSCB (new default/minimum value)===
The default (and minimum) value of <var>[[LFSCB parameter|LFSCB]]</var> is now 8 bytes.

===LITBL (new default/minimum value)===
The default (and minimum) value of <var>[[LITBL parameter|LITBL]]</var> is now 8 bytes.

===MINDEBCL (new)===
The new system parameter, <var>[[MINDEBCL parameter|MINDEBCL]]</var>, can be set in an Online to specify the minimum [[Debugger]] Client build number that can be used with that Online.

===MPDELAY and MPDELAYZ (new)===
For an [[Performance monitoring and tuning#Multiprocessing .28MP.2F204.29|MP/204]] Online, the <var>[[MPDELAY parameter|MPDELAY]]</var> and <var>[[MPDELAYZ parameter|MPDELAYZ]]</var> parameters are added to improve the efficiency of the MP scheduler. They reduce the cost of starting too many new subtasks for the amount of work to be done.

===NUMBUF and NUMBUFG===
As described below in [[#Elimination of BTB buffers|Elimination of BTB buffers]], setting <var>NUMBUFG</var> greater than 0 in version 7.7 forces <var>NUMBUF</var> to 0 (no buffer pool buffers reside below the bar). Not setting <var>NUMBUFG</var> or setting it to 0 (no buffers above the bar) allows the calculation of BTB buffers to remain as in previous versions.

===SCHDOFL and SCHDOFLZ (new minimum value)===
The new minimum value of <var>[[SCHDOFL parameter|SCHDOFL]]</var> and <var>[[SCHDOFLZ parameter|SCHDOFLZ]]</var> is 0. Before Model 204 7.7, their minimum allowed value was 1.

===SCHDOFLS (new)===
For z/OS system customers using <var class="product">Model 204</var> zIIP support, the new <var>[[SCHDOFLS parameter|SCHDOFLS]]</var> system parameter helps you to regulate the zIIP processor workload.

<var>SCHDOFLS</var> specifies both of the following:
<ul>
<li>The target number of threads on the zIIP offload queue before a non-SRB MP subtask is dispatched to help the zIIP subtasks. </li>

<li>If started, how aggressively non-SRB MP subtasks pick up work from the zIIP offload queue. </li>
</ul>

This parameter applies to z/OS only.

===SCHDOPT (change to X'20' bit processing)===
The <var>[[SCHDOPT parameter|SCHDOPT]]</var> X'20' bit prevents the maintask from running work that is intended to run on a zIIP subtask (when zIIP subtasks are defined and activated). As of Model 204 7.7, even when this bit is off, the maintask will run some of the zIIP work only if the zIIP subtasks appear to be saturated. Saturation is defined as a zIIP subtask queue length of at least <code>[[SCHDOFLZ parameter|SCHDOFLZ]]*[[AMPSUBZ parameter|AMPSUBZ]]</code>.

Formerly, this saturation requirement was absent, allowing the maintask to take on more (possibly too much) of the zIIP workload.

===SERVSIZE (new default/minimum value)===
The minimum value for <var>[[SERVSIZE parameter|SERVSIZE ]]</var> is changed from zero to 65536. If <var>SERVSIZE</var> is explicitly set in CCAIN and its value is less than 64K, the following message is issued:
M204.1149: SERVSIZE has been set to its minimum value: 65536


If <var>SERVSIZE</var> was not set but was [[Defining the runtime environment (CCAIN)#Sizing user server areas|calculated by the system]] to a value less than 64K, the following message is issued:
M204.0163: SERVSIZE increased to 65536


This change is propagated by zap maintenance to versions 7.6, 7.5, and 7.4 of Model 204. 

===TCPTYPE (new IPV6 values)===
As part of the version 7.7 [[#IPV6|support for IPV6]], three new optional (IPV6-address-only) values are added to the <var>[[TCPTYPE parameter|TCPTYPE]]</var> parameter:
IBMV6
BPXV6
IUCVV6


==Performance enhancements==

===Elimination of BTB buffers===
As of version 7.7, any use of above-the-bar buffer pool (as invoked by a setting of the <var>[[NUMBUFG parameter|NUMBUFG]]</var> parameter greater than 0) will force all buffer pool buffers above the bar — no below-the-bar buffers will exist. In this case, the <var>[[NUMBUF parameter|NUMBUF]]</var> and <var>[[MINBUF parameter|MINBUF]]</var> parameters will be forced to 0, and the other parameters that affect BTB storage (<var>MAXBUF</var>, <var>SPCORE</var>, <var>LDKBMWND</var>, and <var>NLRUQ</var>) will be ignored.

If you set <var>NUMBUFG</var> to 0, all buffers will be below the bar, and the settings of the BTB-related parameters will be respected and calculated as in pre-7.7 versions.

===Increase in request limit for number of images, screens, and menus===
These limits are increased to 4095 per request:
<ul>
<li>The total number of [[Images|images]] for all blocks (formerly 256)</li>

<li>The maximum number of [[Menu statement or block#Menus and screens|menus and screens]] combined (formerly 256)</li>
</ul>

===Large checkpoint data sets===
Support is added for large data sets (as many as 16 million tracks) for the Model 204 Checkpoint facility [[Checkpoints: Storing before-images of changed pages#Creating the CHKPOINT.2FCHKPNT .28and CHKPNTS.29 data set|CHKPOINT or CHKPNTS data sets]]. For details, see [[System_and_media_recovery#ROLL_BACK_processing.2C_Pass_2|ROLL BACK processing, Pass 2]].

==Statistics enhancements==

===BLKO===
The [[Using system statistics#System performance statistics|performance statistic]] BLKO now also reports invisible users that are blocked out. In previous releases, invisible users were not reported and BLKO remained virtually zero. The new BLKO value is more precise, and by summing BLKO, WTSV, BLKI, REDY, SWPG, and RUNG, you can now approximate USRS (average active users).

For the <var>MONITOR</var> command, the [[ONLINE monitoring#User information in formatted displays|QUE column]] now reports new values OFFO and OFFI instead of OFFQ for invisible users:
<ul>
<li>OFFO is invisible and blocked out. </li>
<li>OFFI is invisible and blocked in. </li>
</ul>

The BLKO QUE value continues to mean blocked out and visible (on some queue), and BLKI means blocked in and visible.

===CCATDIFF and CCATDIFH===
The [[Using system statistics#Description of statistics|CCATDIFF]] user and since-last statistic gets incremented each time a user allocates a CCATEMP page, and it gets decremented each time a user frees a page. Its value is not allowed to drop below zero. In the event of a CCATEMP page shortage, CCATDIFF gives system managers the possibility of determining a particular user that might be primarily responsible.

Note: CCATDIFF is a rough guide, not definitive: it might give false high readings for some users, but it will indicate a user whose usage is extremely extraordinary. 

[[Using system statistics#Description of statistics|CCATDIFH]] is a since-last statistic that reports a request's CCATDIFF since-last highwater mark, useful to retrospectively determine which request was responsible for a massive CCATEMP usage spike. For example, it will record a request that allocated a large number of CCATEMP pages but freed the pages before the request ended.

==Other enhancements==

===MODEL 6 screen size and back-paging===
As of Model 204 version 7.7 (and 7.5 or 7.6 with maintenance applied), a large <var>[[LOUTPB parameter|LOUTPB]]</var> value for [[Terminal MODEL 6 support|MODEL 6]] geometries is allowed, even if screen back-paging has been enabled.

In previous releases, during initialization, if back-paging was enabled for the IODEV, <var>LOUTPB</var> was automatically reset to the limit that supported back-paging.

Back-paging will now be disabled for any terminal with a <code>MODEL 6</code> screen geometry that requires more than 6142 bytes.

===ECF calls to the IBM IDCAMS utility===
The new <var>IDCAMS</var> option for the <var>[[External Call Facility#module|External Module]]</var> statement of the Model 204 [[External Call Facility]] lets a SOUL program invoke IDCAMS without using the SYSIN and SYSPRINT DD statements. Instead, the Model 204 Universal Buffer is used to pass the input lines and receive the output lines from IDCAMS.

===Running ECF requests under the invoking user’s profile===
Unless the new system parameter <var>[[ECPRIV parameter|ECPRIV]]</var> 4 bit is set, the job invoked by a privileged [[External Call Facility]] statement at a site where an external authorizer (ACF2, RACF, or Top/Secret) is used runs under the external-authorizer profile of the user that invokes the External Call, rather than under the job's external-authorizer profile.

Prior to version 7.7, such a job always ran under the job's external-authorizer profile, so this is a [[#Profile used for running ECF requests|backward compatibility]] issue.

==Debugger updates==

===SoftSpy authorization===

SoftSpy and Muse are now authorized using the standard zap AUTH mechanism.

EDIT CONFIG is no longer used to enter authorization keys, and the second (key entry) screen of SPY EDIT CONFIG no longer appears.

===SoftSpy Error message for DBCSENV===

As in previous releases, SoftSpy is not supported in a DBCS (double-byte character set) environment. As of version 7.7, if the CCAIN parameter DBCSENV is set to a non-zero value, the SPY command is rejected with the following message:
Message 207: SoftSpy may not be used in a DBCS environment.

===Debugger Client version information display on mainframe===
As of version 7.7 and Client build 64, the <var class="product">Janus/TN3270 Debugger</var> Client sends its build and tag number to the mainframe, and this information is displayed in message [[MSIR.1077]]:
MSIR.1077: Begin debug session, user 3, client: Build: 64, Tag: 2 (Janus debugger session)

This information is not sent if the Debugger Client build number is less than 64, and the mainframe side views all Client versions prior to build 64 as build 63.

The build number, which identifies Client versions, is displayed in the Client Audit Trail tab at start up:
2016 07 30 17:21:47 The Rocket Software Debugger Client
2016 07 30 17:21:47 Build: 65 (01 August 2016) Tag: 1 GA


You can also view the build number of the Client at any time by selecting Help > About. And as of Client build 65, the build number is displayed by the Client function <var>&&buildNumber()</var>.

===Enforcing use of a minimum version of the Debugger Client===
Normally, when you use the TN3270 or Janus Debugger, no restrictions are placed on which version of the Debugger workstation client is used.
As of Client build 65 and Model 204 7.7, you can force Clients to have at least a minimum build number in order to invoke a debugging session with your Online. The new Model 204 system parameter <var>[[MINDEBCL parameter|MINDEBCL]]</var> sets such a minimum.

If you set <var>MINDEBCL</var> to a positive value, use a version of the Debugger Client whose build number is less than <var>MINDEBCL</var>, and invoke a debugging session, the debugging session is rejected. An error message is shown in your browser and at the Client, calling for a Client upgrade.

You also see the following error on the Online's Audit Trail (and on the terminal if you are using <code>TN3270 DEBUG ON</code>):
MSIR.1079: Debugger Client Build: ''xx'' < MINDEBCL: ''yy'' debugger client connection refused


==Compatibility issues==

===APSYPAGE parameter cannot be non-zero===
(Applies to the IBM z/OS system.)
The <var>APSYPAGE</var> parameter was disabled (but still allowed) in version 7.6. As of version 7.7, if <var>APSYPAGE</var> is non-zero, the Online will not come up and the following error message will appear:

M204.2958: APSYPAGE is obsolete as of 7.6.
Rocket recommends using RESPAGE and/or TEMPPAGE as the alternative

See [[APSYPAGE parameter]] for information about alternatives to <var>APSYPAGE</var>.

===Unlabeled FDV statement compilation errors===
Version 7.7 introduces an edge case incompatibility by disallowing code which is very questionable or clearly wrong; that is, previously the compiler allowed pretty much any statements between the label and the FDV. Such statements are no longer allowed.

For example, the following was allowed in older versions of Model 204:
a: audit 'About to FDV'
fdv foo
b: frv in a

Inserting SOUL code between a label and an FDV statement is no longer allowed, and so the result of the above is:

M204.0311 Unacceptable statement reference

This change is propagated by zap maintenance to versions 7.6 and 7.5 of Model 204.

===KOMM addressing changes===
<ul>
<li>KU is no longer 4K addressable from KOMM. It has been relocated to KOMM+1100 and must be addressed using grande (‘G’) instructions.</li>
<li>KHEOC has been renamed to KGEOC.</li>
<li>KUUSRNO has been renamed to KBUSRNO.</li>
<li>In addition, all KUP… fields have been removed and replaced by their 64-bit equivalent KUG… fields. 
For example, before 7.7, VTBL might be addressed by using <code>L R1,KUPVT</code>. 
As of version 7.7, that reference would require <code>LG R1,KUGVT</code>.</li>
</ul>

For context, see [[Customizing functions and translation tables#Converting user-written functions|Converting user-written functions]].

===JANUS WEB ON -- "M substitution===
In the command for a <var>JANUS WEB ON</var> rule, <code>"M</code> can now be used to specify a method name.
This behavior is a change from past releases, when <code>"M</code> was simply converted to <code>M</code>. See [[#ON rules .28method name substitution.29|JANUS WEB ON rules (method name substitution)]] for details.

===Journal format compatibility===
A recovery code error unintentionally allowed recovery to be run using Model 204 7.6 against a version 7.5 journal, and vice versa. Although the error was benign because the journal formats were the same in those versions, mixing of journal versions and Model 204 versions is no longer allowed.

===Profile used for running ECF requests===
As [[#ecfprofile|described earlier]], the default external-authorizer (ACF2, RACF, or Top/Secret) profile under which a job invoked by a privileged ECF statement runs is changed in version 7.7. Instead of such a job running under the job's external-authorizer profile (as it did prior to 7.7), the job runs by default in 7.7 under the user's external-authorizer profile.

The default behavior can be changed by turning on the new system parameter <var>[[ECPRIV parameter|ECPRIV]]</var> 4 bit.
===$ListNew cannot be used in Initial clause===
<var>$ListNew</var> cannot be used in the <var>Initial</var> clause of a [[Using_variables_and_values_in_computation#Declare_statements_for_.25variables|declaration statement]].
This change was introduced as zap maintenance in versions 7.5, 7.6, and 7.7 of Model 204.

==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 updated messages==

See [[New and updated messages in Model 204 version 7.7|New and updated messages in Model 204 version 7.7]] for details.

[[Category: Release notes|Model 204 version 7.7]]

SendWebSocket (Socket function)

2024-07-29T19:53:08Z

Tom: /* Usage notes */

{{Template:Socket:SendWebSocket subtitle}}

This page is [[under construction]].
==Syntax==
{{Template:Socket:SendWebSocket syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>socket</th>
<td>Socket object</td></tr>
<tr><th>string</th>
<td>string</td></tr>
<tr><th>number</th>
<td>number is an op code indicating the type of web socket frame. Numbers 0-7 are non-control frames. Numbers 8-15 are control frames. Control frames are always sent immediately and cannot be fragmented. Specifying a reserved code will cause immediate request cancellation.
<table>
<tr><th>0</th>
<td>A continuation frame. A continuation frame is treated as text or binary based on the op code of the first frame. A continuation frame cannot also be the first frame.</td></tr>
<tr><th>1</th>
<td>A text frame. Text frames are are translated to ASCII with the translate table in effect for the port.</td></tr>
<tr><th>2</th>
<td>A binary frame. No translation is done for binary frames.</td></tr>
<tr><th>3-7</th>
<td>Reserved for future use and will cause request cancellation.</td></tr>
<tr><th>8</th>
<td>Connection close frame.</td></tr>
<tr><th>9</th>
<td>Ping. The receiver should respond with a Pong frame, unless a close frame has been received.</td></tr>
<tr><th>10</th>
<td>Pong. This is sent as a response to a Ping frame.</td></tr>
<tr><th>11-15</th>
<td>Reserved for future use and will cause request cancellation.</td></tr>
<tr><th>128</th>
<td>This value is added to the frame op code to indicate the final fragment of a non-control message. The first fragment may also be the final fragment.</td></tr>
</table></td></tr>
<tr><th>boolean</th>
<td><var>Boolean</var> value that indicates whether to mask the data with a masking key. The default is not to mask the data. Masking is done using an internally generated masking key.</td></tr>
</table>

Sending a control frame always forces a flush of the TCP output buffer. A close or a ping are the only valid control frames.

==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:SendWebSocket footer}}

Release notes for Model 204 version 7.8

2024-07-29T19:19:31Z

Tom: /* Operating system requirements */

These release notes list the enhancements and other changes contained in Model 204 version 7.8.

==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 (Daemon subroutine)|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>
<ul>
<li>[[Janus_Two-Phase_Commit|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>[[Application_Subsystem_development#COMMITX parameter|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|DISPLAY ECF]]</var> command and <var>[[#Managing ECF tables more efficiently|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 command|MONITOR <var>USERS</var>]]</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, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and 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 3.1. (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>

===EndsWith function===
The [[EndsWith (String function)|EndsWith String function]] determines if one string ends with the characters in another. This is analogous to the [[StartsWith and IsStartOf (String functions)|StartsWith function]] except, of course, it checks the end of a string rather than the start.

The following code snippet:
printText {~="War and Peace":endsWith("Peace")}
printText {~="War and Peace":endsWith("War")}

displays:
"War and Peace":endsWith("Peace")=True
"War and Peace":endsWith("War")=False


===$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 will 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===
There 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_Call_Facility#External_Module_statement|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 parameter|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|DEBUGUL]]</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 978, procedure DOCOOLSTUFF in file COOLFILE
M204.2966: Called from line 1215, procedure FOOBAR.CLASS in file CLASSES
M204.2966: Called from line 378, procedure SILLY.CLASS in file CLASSES
M204.2966: Called from line 187, procedure P.ROCKANDROLL in file APSYFILE


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.

==Editor enhancements==
The [[Model 204 full-screen editor#exit|Model 204 editor]] has been enhanced to not hold a lock on a procedure being edited. Instead the timestamp of the procedure on disk is compared against that of the edited procedure when it was loaded or last saved. If different, the save is not allowed. New commands <var>SSAVE</var>, <var>EEND</var>, and <var>GGO</var> are available to force the save in this situation.
In addition, the <var>GO</var> command no longer updates the procedure on disk before <var>INCLUDE</var>ing it if it has not been modified in the editor.
==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.

===MERGEJ now supports up to 99 input journals===
The MERGEJ utility, used to merge journals with overlapping timestamps prior to running Media Recovery, now supports up to 99 input SORTINnn journals to be merged. For this release it is still the case that any previously merged journal must be defined as SORTIN01 to the MERGEJ run, and thus that the MERGEJ run can not accept more than one previously merged journal as input.

This change is also enabled in V7.7 with the application of 77z487.

==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 API calls available on transactional daemons===
Transactional daemons can now use the Janus Web API, mostly $functions that begin with <var>$web</var>. The new [[$Web_Api|$web_api function]] makes it possible to test if the Janus Web API is available, whether on a Janus Web Server thread or one of its transactional daemons.

===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.

===$Web_Form_Parm_Binary===
Janus Web now defers ASCII to EBCDIC translation of form parameter values until a value is requested. This makes it possible to retrieve the exact values sent by the client rather than a translated version. This is important if a form parameter value is UTF-8 encoded and contains non-7-bit ASCII characters (for example if a form parameter contains XML). The [[$Web_Form_Parm_Binary]] function returns the exact value sent by a client for a form parameter with no character translation.

===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 1280 bytes. This change is enabled in V7.7 with the application of zaps 77z424 and 77z448.

===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.

===Limiting the production of MSIR.0019 and MSIR.0020 messages===
The production of the following messages

MSIR.0019 Connection request rejected for port (port), MAXCON exceeded

MSIR.0020 Connection request rejected for port (port), no SDAEMONS available

is now limited to a maximum of one each per time interval set by the <var>[[MAXAUSEW_parameter|MAXAUSEW]]</var> parameter ( minimum seconds between <var>[[MAXAUSER_parameter|MAXAUSER]]</var> warnings, which defaults to 10 seconds ). This avoids flooding the journal / jlog with these messages in situations where the number of connections on a port has been exceeded ( MSIR.0019 ), or the the number of available daemon threads has been exceeded ( MSIR.0020 ).

This change is available in V7.8 with the application of zap 78z011, and within V7.7 with the application of 77z466

==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 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.

Also, [[JANUS WEB|Janus Web rules]] scanning will be offloadable. In addition, the scan for persistent web sessions ([[$Web_Form_Done]] and [[Janus Web Legacy Support]]) will be offloadable. While the rendezvous with the persistent thread will still be maintask-only, stateless requests will not need to go back to the maintask to be processed and, even for persistent requests, the persistent session lookup will be offloadable. These changes should provide better scalability for MP/204 sites with heavy Janus Web activity.

===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.

===Internal performance improvements===
A number of internal performance and optimisation improvements have been made in this release. these include

<ul>
<li>Sampling buffer pool pages rather than carrying out a full scan of large buffer pools ( NUMBUFG > 200000 ) when calculating BUFFnnn stats for SirMon</li>
<li>Optimising group and file closure, in particular providing relief on exit from APSYs where a lerga number of groups may be in use, and where the groups may comprise a large number of file members</li>
<li>Improved handling of timer queues, particularly in an MP/204 environment</li>
<li>More aggressive prioritisation of journal and checkpoint I/O, in order to reduce user waits for such I/), and to reduce related waits on critical file resources
</ul>

==New and changed commands==
===MONITOR===
The MONITOR command output now contains a new column, headed LOG, that shows the logon status of each user in the system, for example

USER SVR FLS PCPU SMPLS RUNG REDY BLKI WTSV BLKO SWPG
7 0.330

USER SVR USERID P CUR SLICE LOG FUNC CNCT CPU SEQIO QUE WT FLGS
0 1 SUPERKLUGE S 56 0.031 CCA EVAL 5 0.012 221 OFFI 12 65
4 2 ADMIN S 51 0.031 CCA 1 0.000 22 RUNG
20 VT75DIED 0.000 0 0.000 0 2 20
21 VT75READ 0.000 37 0.000 0 3 00
22 VT75ERRS 0.000 0 0.000 0 2 20
23 CHKPTIMO 0.000 0 0.000 0 12 20
24 CHKPTIMR 0.000 0 0.000 0 12 20
25 CHKPPST 0.000 0 0.000 0 12 20
26 CHKPAWW 0.000 0 0.000 0 12 20
27 TC62RAPS 0.000 0 0.000 0 27 04
28 TC62SRVC 0.000 0 0.000 0 27 20
>

The LOG column replaces the AGE column in the MONITOR output, as this information was considered more relevant for this command output. Possible values that are shown in the LOG column are as follows
<ul>
<li> CCA - CCASTAT userid</li>
<li> ESM - userid validated by an External Security Manager - ACF2, RACF, or TopSecret/li>
<li> SUB - Subsystem controlled logon</li>
<li> GST - Guest - neither logged on via CCASTAT nor by an ESM</li>
<li> PDG - Logon pending due to errors (e.g. invalid password)</li>
</ul>

This change is also available with V7.7 with the application of zap 77z478.

===MONITOR IODEV===
This new command displays the total number, the current usage and the maximum number of each IODEV type. If the Model 204 parameters include telnet threads (TNDEV parameter), the specified IODEV will actually execute as a daemon thread (SDAEMDEV parameter). For that reason, both the telnet and daemon IODEVs will be incremented and the telnet IODEV will appear with an appended '*'. 
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%
21* 1 1

===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==

===COMMITX===
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.

===ECMSUBS===
This maximum value may now be reset dynamically by a system manager. If the value is raised, new tasks will be added as needed up to the value specified. If the value is lowered, idle subtasks will be detached before they are activated until the new maximum is established.

===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 parameter|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>).

===MODENAME in a Transfer Control PROCESSGROUP===
Previously the MODENAME parameter has been ignored in VTAM TRANSFER PROCESSGROUP processing.

As of V78 with 78Z029 applied, Users will be able to control the characteristics of a session (for example, Display Model, Ru size, EDS support et al.) bound at the VTAM Transfer Control Target
by means of the VTAM Transfer PROCESSGROUP's MODENAME.

A null or unspecified MODENAME in a VTAM Transfer PROCESSGROUP definition will result in the Target LU's
Default LOGMODE being used to Bind the Target Session (This is how all VTAM Transfers worked previously).

Specifying MODENAME=LOGON or MODENAME=LOGIN in a VTAM TRANSFER PROCESSGROUP definition results in the LOGMODE used
to Logon to the Source Online also being used to Bind the Session at the Transfer Target.

Otherwise, anything specified in a VTAM TRANSFER PROCESSGROUP MODENAME parameter will be assumed to be a
valid VTAM LOGMODE and will be used to Bind the Transferred session at the Target. There is a potential
for upward incompatibility in the case where a VTAM TRANSFER PROCESSGROUP definition specifies an invalid value for MODENAME:

Since the MODENAME is no longer ignored, an invalid value will now fail the Transfer.

A failed Transfer consequent to an invalid LOGMODE or a LOGMODE unknown at the Target is flagged with:
M204.2483 'unknown-modename is not a valid LOGMODE name'.

===MQMXTASK===
This maximum value may now be reset dynamically by a system manager. If the value is raised, new tasks will be added as needed up to the value specified. If the value is lowered, idle subtasks will be detached before they are activated until the new maximum is established.

===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.

===WEBOPT===
The new x'10' setting of <var>[[WEBOPT_parameter|WEBOPT]]</var> allows transaction daemon threads to access web data owned by the ancestor ( usually the parent ) thread.

==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, MAXBOUT, MAXSUBT|MAXPRE, MAXBOUT, and 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 non-trivial backward incompatibility issue related to Closure support, introduced in 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.

===BUF and FBMX stats removed===
Unnecessary scans of the buffer pool have been eliminated from most forms of the MONITOR command ( other than MONITOR DISKBUFF itself ), and this provides performance gain when running these commands. However, as a result of this the BUF stat on the MONITOR command output, and the FBMX stat reported in the system final stats block have been removed. These stats were of extremely limited value, and their elimination should not cause any problems for system management. This change is implemented in V7.8 via zap 78z077, and in V7.7 by zap 77z463.

==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 products==
===Janus Two-Phase Commit===
[[Janus Two-Phase Commit]] support makes it possible to create global transactions where updates on multiple Model 204 Onlines or <var>Imagine</var> can be atomically committed or backed out.

===Commit Exit===
The [[Application_Subsystem_development#Commit_exits|Commit exit]] product allows for the invocation of specified APSY code when an an APSY TBO transaction executes its first explicit or implicit COMMIT. The feature is controlled by the new COMMITX parameter.

==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.9 (Beta)

2024-05-07T20:18:49Z

Tom:

THIS PAGE IS UNDER CONSTRUCTION!
These release notes list the enhancements and other changes contained in Model 204 version 7.9, 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.9 release.
Before beginning your installation, please read through this information about product installation and changes.

==New in this release==
===Regular expression engine enhancements===

The [[Regex processing|regular expression engine]] can now produce traces of regular expression processing to help debug and optimize regular expressions. There are new user parameters [[REGEXTR parameter|REGEXTR]] and [[MREGEXTR parameter|MREGEXTR]], as well as a new [[Regex_processing#Common_regex_options|"t" option]] on regex method and $function invocations to control this tracing.


The regular expression engine now supports [https://www.regular-expressions.info/backref.html back references]. The following illustrates the use of a back reference (\1 in the example) to display all lines in procedure FOO where the left side of an assignment also appears on the right side. Note that this example is somewhat simplistic in that it it doesn't account for continuation lines and might not be what one wants if the left side of an assignment is an object member or array element.

b

%i is float
%sl is object stringlist

%sl = new
$procopn("FOO", "FOOPROC")
%sl:appendOpenProcedure

%i = 1
repeat while %i le %sl:count
%i = %sl:regexLocate("(%[a-z._$]+) *=.*\1", %i, options="i")
if %i eq 0 then loop end; end if
print %ls(%i)
%i = %i + 1
end repeat

end

===New Regex class===

Regular expressions can now be compiled into [[Regex class|Regex objects]]. This can be useful in allowing the compilations of dynamically generated regular expressions to be reused without recompilation. There is a new system parameter, [[REGXSTBL parameter|REGXSTBL]] that controls how much STBL space is to be reserved for each <var>Regex</var> object.


===New HDRCTL setting for DAEMONS===

Prior to V7.9, daemons did not output header lines.
Starting with V7.9, HDRCTL may be set to 8 to force daemons to output header lines.

===New MSGCTLU command to allow message changes by non-managers===

Message behavior may now be changed by non-managers effecting the user's thread only.
For instance, anyone may now produce a snap on a specific message within their thread which does not affect anyone else.
See [[MSGCTLU_command|MSGCTLU]] command for more details.

==System Enhancements==
===EAV support for SIRTUNED===

==Debugger enhancements==
Enhancements have been made for debugging applications that use IMAGEs to all of Model 204 debuggers (Janus Debugger, Tn3270 Debugger and SoftSpy).

==Performance enhancements==
===Regex Rewrite===

The [[Regex processing|regular expression engine]] has been completely rewritten to make it significantly faster. Tests indicate simple regex is at least three times as fast as the earlier regular expression engine, and 10 times or more faster for more complex regular expressions. In addition, constant regular expressions are now compiled when the containing procedure is compiled to eliminate the runtime cost of regular expression compilation and to detect errors in regular expressions at SOUL compile-time lather than evaluation time.

===ATB Storage Usage Greatly Increased===
Many more M204 data structures can be placed in ATB storage with 7.9. Probably the most important of these is the Push Down List (PDL).

==New and changed messages==

See [[New and updated messages in Model 204 version 7.9|New and updated messages in Model 204 version 7.9]] for details.

[[Category: Release notes]]

TCPTYPE parameter

2024-02-06T17:11:07Z

Tom: /* Description */

{{Template:TCPTYPE parameter subtitle}}
==Summary==
<dl>
<dt>Default value
<dd>UNKNOWN
<dt>Parameter type
<dd>System
<dt>Where set
<dd>User 0 CCAIN parameters
<dt>Related products
<dd>All
<dt>Introduced
<dd>Before <var class="product">Sirius Mods</var> 6.7
</dl>

==Description==
This parameter specifies the type of [[Janus_TCP/IP_Base|TCP/IP]] network to which Model 204 is connected.
Generally, you can let this parameter default (<var>UNKNOWN</var> is default value). Janus then automatically detects the type of TCP/IP you have on your machine, and it resets the <var>TCPTYPE</var> value accordingly. In this case, IPV4 values are preferred; IPV6 values must be explicitly set.

If you specify type <var>IBM</var> or <var>IBMV6</var>, Janus detects and sets the type of IBM interface it will use, as shown in the table below. Only these values invoke auto-detection.

You can also override auto-detection by explicitly supplying a <var>TCPTYPE</var> parameter value.
The likely reason to do this would be if you have multiple TCP/IP stacks installed, and you want to force use of the non-preferred stack.

The valid <var>TCPTYPE</var> values are in the third column below:
<table>
<tr class="head"><th>Operating system</th><th>Network version</th><th>Value</th><th>Meaning</th></tr>

<tr>
<td rowspan="7">z/OS</td>
<td rowspan="5">IPV4 only</td>
<td>IBM</td>
<td>Auto-detect the "best" IBM TCP/IP interface. For z/OS, this is BPX. </td></tr>

<tr>
<td>BPX</td>
<td>IBM BPX (Unix System Services). </td></tr>

<tr>
<td>HPNS</td>
<td>IBM HPNS (High Performance Native Sockets). Note that despite its name, HPNS's performance is not nearly as good as BPX's. No longer supported as of version 7.9 of Model 204. </td></tr>

<tr>
<td>INTERLNK</td>
<td>InterLink TCP/IP. No longer supported as of version 7.9 of Model 204.</td></tr>

<tr>
<td>IUCV</td>
<td>IBM TCP/IP IUCV (Inter User Communication Vehicle). </td></tr>

<tr>
<td rowspan="2">IPV6 only</td>
<td>IBMV6</td>
<td>Auto-detect the "best" IBM TCP/IP interface. For z/OS, this is BPXV6.

This option is available as of version 7.7 of Model 204.</td></tr>

<tr>
<td>BPXV6</td>
<td>IBM BPX (Unix System Services). 
This option is available as of version 7.7 of Model 204.</td></tr>

<tr>
<td rowspan="4">CMS</td>
<td rowspan="2">IPV4 only</td>
<td>IBM</td>
<td>Auto-detect the "best" IBM TCP/IP interface. For CMS, this is IUCV. </td></tr>
<tr>
<td>IUCV</td>
<td>IBM TCP/IP IUCV (Inter User Communication Vehicle). </td></tr>

<tr rowspan="2">
<td rowspan="2">IPV6 only</td>
<td>IBMV6</td>
<td>Auto-detect the "best" IBM TCP/IP interface. For CMS, this is IUCVV6.

This option is available as of version 7.7 of Model 204.</td></tr>

<tr>
<td>IUCVV6</td>
<td>IBM TCP/IP IUCV (Inter User Communication Vehicle).

This option is available as of version 7.7 of Model 204.</td></tr>

<tr>
<td>z/VSE</td>
<td>IPV4 only</td>
<td>CSI</td>
<td>Connectivity Systems TCP/IP. </td></tr>
</table>

Most of the communication with the TCP/IP address space is accomplished with a [[Controlling system operations (CCAIN)#Pseudo subtasks|Pseudo subtask (PST)]].
Because of this, you may need to increase the <var>[[NSUBTKS parameter|NSUBTKS]]</var> parameter by 1 before using Janus.

[[Category:System parameters]]
[[Category:Parameters]]

NEWSESCMD (JANUS DEFINE parameter)

2023-09-11T19:27:53Z

Tom:

NEWSESCMD 'xxx' — Commands to execute on new session initiation

<var>NEWSESCMD</var> is a parameter on <var>[[JANUS DEFINE]]</var>, which defines and sets characteristics of a Janus port.

This parameter specifies the <var class="product">Model 204</var> commands to be executed when a new login session is initiated. For <var>[[JANUS DEFINE#type|SRVSOCK]]</var> ports every connection starts a new login session. For <var>[[JANUS DEFINE#type|WEBSERV]]</var> ports, a new login session is only started when the user requests a "login required" URL (based on <var>[[JANUS WEB ALLOW]]</var> rules) and the user is not continuing a login session via <var>[[SSLSES (JANUS DEFINE parameter)|SSLSES]]</var> or <var>[[SESCOOKIE (JANUS DEFINE parameter)|SESCOOKIE]]</var>.

Multiple commands must be separated by <code>AND</code>, and any command that contains blanks must be enclosed in quotes. <var>NEWSESCMD</var> may span more than one line (if a hyphen (-) continues the line), but the total length of commands plus one overhead byte per command cannot exceed 255 bytes.

The <var>NEWSESCMD</var> commands are executed before any commands specified in the <var>[[CMD (JANUS DEFINE parameter)|CMD]]</var> clause or <var>[[JANUS WEB ON]]</var> rules for <var>WEBSERV</var> ports. User authentication is the primary function of <var>NEWSESCMD</var> commands. Any [[Janus Web Server $functions|$Web_ function]] can be issued in <var>NEWSESCMD</var> commands on <var>WEBSERV</var> ports, and any [[Janus Sockets $functions|$Sock_ function]] can be issued in <var>NEWSESCMD</var> commands on <var>SRVSOCK</var> ports. In addition, a <var>NEWSESCMD</var> command can issue the <var>[[$Sir_Login]]</var> function as well as the <var>[[$Web_Password]]</var> function on <var>WEBSERV</var> threads. The <var>[[$Web_Hdr_Parm]]</var> and <var>[[$Web_Hdr_Parm_Lstr]]</var> functions can retrieve the Authorization header parameters while running as part of a NEWSESCMD, but will otherwise return a null string.

If <var>NEWSESCMD</var> specifies an <var>INCLUDE</var> command, the included procedure is assumed to come from the first file or group specified in a <var>[[NEWSESOPEN (JANUS DEFINE parameter)|NEWSESOPEN]]</var> clause.

Examples of some valid <var>NEWSESCMD</var> clauses:

JANUS DEFINE MYWEB 80 WEBSERV 10 NEWSESCMD WEBLOGIN

JANUS DEFINE TELNETSRV 23 SRVSOCK 10 -
NEWSESOPEN TELNETP -
NEWSESCMD 'UTABLE LQTBL 3000' AND -
'INCLUDE TELNETLOGIN'


Because of the role of <var>NEWSESCMD</var> in enforcing user access security, most resources used during <var>NEWSESCMD</var> processing are automatically cleaned up after the <var>NEWSESCMD</var> processing is completed. This includes all files being closed and all user tables being cleared (though not resized). The one exception to this is that GTBL can be left intact after <var>NEWSESCMD</var> processing, if the <var>[[NEWSESNOCLEARG (JANUS DEFINE parameter)|NEWSESNOCLEARG]]</var> parameter is specified on the port definition.

If a <var>NEWSESCMD</var> command logs a user in using <var>$Sir_Login</var>, the rest of the request runs under that userid. For web requests, it is possible that a <var>NEWSESCMD</var> will log a user on, but that user will not be authorized to run the request URL based on <var>[[JANUS WEB ALLOW]]</var> rules. In such a case, <var class="product">[[Janus Web Server]]</var> will either send a "404 Unauthorized" status to the browser (which will result in a login pop-up window being presented to the end-user), or it will run the <var>[[JANUS WEB exception rules#unauth|UNAUTHORIZED]]</var> exception handler, if one is present.

If the <var>NEWSESCMD</var> does not perform a <var>$Sir_Login</var>, processing continues as it would without a <var>NEWSESCMD</var>. That is, on a <var>SRVSOCK</var> port, the request will run under the <var>[[SOCKUSER (JANUS DEFINE parameter)|SOCKUSER]]</var> userid, and on a <var>WEBSERV</var> port, <var class="product">Janus Web Server</var> will attempt to log the user in based on the userid and password passed in the HTTP authorization header, if one is present.

<var>NEWSESCMD</var> command processing can also close the connection with the client, either with a <var>[[$Sock_Close]]</var> on a <var>SRVSOCK</var> port or with a <var>[[$Web_Done]]</var> on a <var>WEBSERV</var> port. In such a case, no further processing occurs on the thread after the <var>NEWSESCMD</var> commands complete.

This parameter is valid for <var>[[JANUS DEFINE#type|SRVSOCK]]</var>, <var>[[JANUS DEFINE#type|WEBSERV]]</var>, and <var>[[JANUS DEFINE#type|TNSERV]]</var> port types.

This parameter is '''not''' valid on an <var>[[JANUS DEFINE#type|FTPSERVER]]</var> port definition.

For <var>[[JANUS DEFINE#type|TNSERV]]</var> ports, the <var>NEWSESCMD</var> is only run for the initial '''connection'''. If a user logs off and logs back on in the same connection, the <var>NEWSESCMD</var> will not be executed. Because of this, if a <var>NEWSESCMD</var> does a <var>$Sir_Login</var>, it might make sense for it to specify the <var>TRUST</var> parameter on the <var>$Sir_Login</var> to allow subsequent logins in the same connection to be trusted logins.

==See also==
<ul>
<li>[[List of Janus commands]]
<li>[[JANUS DEFINE#parmlist|List of JANUS DEFINE parameters]]
</ul>

[[Category:JANUS DEFINE parameters|NEWSESCMD]]

File:Befirxdzhkjycwg1c4la.jpg

2023-04-06T13:48:08Z

Tom:

File:Gitbad.png

2023-04-05T18:42:49Z

Tom:

File:Soloette.jpg

2023-04-05T17:01:31Z

Tom:

LoadSystemFunctionInfo (XmlDoc subroutine)

2023-03-21T19:45:58Z

Tom: Blanked the page

LoadSystemFunctionInfo (XmlDoc subroutine)

2023-03-21T19:38:29Z

Tom:

{{Template:XmlDoc:LoadSystemMethodInfo subtitle}}
<var>LoadSystemMethodInfo</var> loads an <var>XmlDoc</var> with information about methods in classes selected by a "pattern" argument. This method is primarily intended for <var class="product">SOUL</var> products delivered by Rocket Software, and the schema of the document may change from release to release. Users of [[SoulEdit]] (V7.5 and later) can see this method in action via the INFO command which provides introspection into specified methods.

==Syntax==
{{Template:XmlDoc:LoadSystemFunctionInfo syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>doc</th>
<td>An expression that points to the <var>XmlDoc</var> to contain the selected method information.</td></tr>

<tr><th>pattern</th>
<td>A string whose case is ignored and that can have any of the following forms:
<table class="syntaxNested">

<tr><th>methodPattern</th>
<td>This selects, from any system class, all methods that match the specified pattern.</td></tr>

<tr><th>classPattern<var>:</var>methodPattern</th>
<td>This selects, from any system class matching <var class="term">classPattern</var>, all methods that match <var class="term">methodPattern</var>. </td></tr>

<tr><th><var>System:</var>classPattern<var>:</var>methodPattern</th>
<td>This is the same as <var class="term">classPattern<var>:</var>methodPattern</var>. </td></tr>
</table></td></tr>

<tr><th><var>ShowBase</var></th>
<td>A <var>[[Enumerations#Using_Boolean_enumerations|Boolean]]</var> enumeration that specifies how to handle base and extension classes:
<ul>
<li>If <var>False</var>, the default, then base classes are omitted from the output <var>XmlDoc</var>, and the methods in extension classes include methods from their base classes. </li>

<li>If <var>True</var>, then base classes (which match the selection pattern) are included in the output <var>XmlDoc</var>, and the members of base classes are not included in extension classes. </li>
</ul>
This [[Notation conventions for methods#Named parameters|name required]] argument was new in version 7.9 of the <var class="product">Sirius Mods</var>.</td></tr>
</table>

==Usage notes==
<ul>
<li>The <var>New</var> method will only be displayed if either is true:
<ul>
<li>The ''methodPattern'' is the string <code>New</code>.</li>
<li>The <var>New</var> method has any arguments. </li>
</ul></li>

<li><var>LoadSystemMethodInfo</var> will not display classes in the module LOCAL, if they are selected by a pattern (that is, ''pattern'' contains a wildcard character), or if there is no ''classPattern'' component.</li>
</ul>

==Examples==
The following request displays the class data for the <var>[[AddAttribute (XmlNode function)|AddAttribute]]</var> method:
begin
%d is object xmlDoc
%d = new
%d:loadSystemMethodInfo('AddAttribute')
%d:print
end

The example result follows:
<classes selection="AddAttribute">
<class name="XmlNode" system="yes" new="no" discard="no" docObject="nod">
<methods module="JSOPF" offset="00002038">
<method name="AddAttribute" type="function" callable="yes" requiredProdNum="35" desc="Add Attribute to Element node">
<result>
<type name="Object" class="XmlNode"/>
</result>
<arg docArg="name">
<type name="Unicode"/>
</arg>
<arg docArg="value">
<type name="Unicode"/>
</arg>
<arg optional="yes" docArg="uri">
<type name="Unicode"/>
</arg>
</method>
</methods>
</class>
</classes>


==See also==
{{Template:XmlDoc:LoadSystemMethodInfo footer}}

LoadSystemFunctionInfo (XmlDoc subroutine)

2023-03-21T19:35:16Z

Tom: Copy/paste of System method Xmldoc for new systemFunction Xmldoc

{{Template:XmlDoc:LoadSystemMethodInfo subtitle}}
<var>LoadSystemMethodInfo</var> loads an <var>XmlDoc</var> with information about methods in classes selected by a "pattern" argument. This method is primarily intended for <var class="product">SOUL</var> products delivered by Rocket Software, and the schema of the document may change from release to release. Users of [[SoulEdit]] (V7.5 and later) can see this method in action via the INFO command which provides introspection into specified methods.

==Syntax==
{{Template:XmlDoc:LoadSystemMethodInfo syntax}}

===Syntax terms===
<table class="syntaxTable">
<tr><th>doc</th>
<td>An expression that points to the <var>XmlDoc</var> to contain the selected method information.</td></tr>

<tr><th>pattern</th>
<td>A string whose case is ignored and that can have any of the following forms:
<table class="syntaxNested">

<tr><th>methodPattern</th>
<td>This selects, from any system class, all methods that match the specified pattern.</td></tr>

<tr><th>classPattern<var>:</var>methodPattern</th>
<td>This selects, from any system class matching <var class="term">classPattern</var>, all methods that match <var class="term">methodPattern</var>. </td></tr>

<tr><th><var>System:</var>classPattern<var>:</var>methodPattern</th>
<td>This is the same as <var class="term">classPattern<var>:</var>methodPattern</var>. </td></tr>
</table></td></tr>

<tr><th><var>ShowBase</var></th>
<td>A <var>[[Enumerations#Using_Boolean_enumerations|Boolean]]</var> enumeration that specifies how to handle base and extension classes:
<ul>
<li>If <var>False</var>, the default, then base classes are omitted from the output <var>XmlDoc</var>, and the methods in extension classes include methods from their base classes. </li>

<li>If <var>True</var>, then base classes (which match the selection pattern) are included in the output <var>XmlDoc</var>, and the members of base classes are not included in extension classes. </li>
</ul>
This [[Notation conventions for methods#Named parameters|name required]] argument was new in version 7.9 of the <var class="product">Sirius Mods</var>.</td></tr>
</table>

==Usage notes==
<ul>
<li>The <var>New</var> method will only be displayed if either is true:
<ul>
<li>The ''methodPattern'' is the string <code>New</code>.</li>
<li>The <var>New</var> method has any arguments. </li>
</ul></li>

<li><var>LoadSystemMethodInfo</var> will not display classes in the module LOCAL, if they are selected by a pattern (that is, ''pattern'' contains a wildcard character), or if there is no ''classPattern'' component.</li>
</ul>

==Examples==
The following request displays the class data for the <var>[[AddAttribute (XmlNode function)|AddAttribute]]</var> method:
begin
%d is object xmlDoc
%d = new
%d:loadSystemMethodInfo('AddAttribute')
%d:print
end

The example result follows:
<classes selection="AddAttribute">
<class name="XmlNode" system="yes" new="no" discard="no" docObject="nod">
<methods module="JSOPF" offset="00002038">
<method name="AddAttribute" type="function" callable="yes" requiredProdNum="35" desc="Add Attribute to Element node">
<result>
<type name="Object" class="XmlNode"/>
</result>
<arg docArg="name">
<type name="Unicode"/>
</arg>
<arg docArg="value">
<type name="Unicode"/>
</arg>
<arg optional="yes" docArg="uri">
<type name="Unicode"/>
</arg>
</method>
</methods>
</class>
</classes>


==See also==
{{Template:XmlDoc:LoadSystemMethodInfo footer}}

List of XmlDoc API methods

2023-03-21T19:33:50Z

Tom: Make entry for $function XmlDoc method

{{Template:API list header|desc=XmlDoc API}}
<table class="wikitable">
<tr><th>Method</th><th>Class</th><th>Description</th></tr>
<tr><td valign="top">[[AddAttribute (XmlNode function)|AddAttribute]]</td><td valign="top">XmlNode</td><td valign="top">Add Attribute to Element node</td></tr>
<tr><td valign="top">[[AddComment (XmlDoc/XmlNode function)|AddComment]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Add Comment to XmlDoc Root or to Element XmlNode</td></tr>
<tr><td valign="top">[[AddElement (XmlDoc/XmlNode function)|AddElement]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Add Element to XmlDoc Root or to Element XmlNode</td></tr>
<tr><td valign="top">[[AddNamespace (XmlNode subroutine)|AddNamespace]]</td><td valign="top">XmlNode</td><td valign="top">Add namespace declaration to Element node</td></tr>
<tr><td valign="top">[[AddPI (XmlDoc/XmlNode function)|AddPI]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Add Processing Instruction to XmlDoc Root or to Element XmlNode</td></tr>
<tr><td valign="top">[[AddSubtree (XmlDoc/XmlNode function)|AddSubtree]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Copy subtree to XmlDoc Root or to Element XmlNode</td></tr>
<tr><td valign="top">[[AddText (XmlNode function)|AddText]]</td><td valign="top">XmlNode</td><td valign="top">Add Text child to Element node</td></tr>
<tr><td valign="top">[[AddTopElement (XmlDoc function)|AddTopElement]]</td><td valign="top">XmlDoc</td><td valign="top">Add new top element to XmlDoc</td></tr>
<tr><td valign="top">[[AddToRecord (XmlDoc subroutine)|AddToRecord]]</td><td valign="top">XmlDoc</td><td valign="top">Add fields and/or fieldgroups to the current record</td></tr>
<tr><td valign="top">[[AdjacentText (XmlDoc property)|AdjacentText]]</td><td valign="top">XmlDoc</td><td valign="top">Are adjacent text nodes allowed?</td></tr>
<tr><td valign="top">[[AllowNull (XmlDoc property)|AllowNull]]</td><td valign="top">XmlDoc</td><td valign="top">Allow null characters in node values?</td></tr>
<tr><td valign="top">[[AllowXmlAttribute (XmlDoc property)|AllowXmlAttribute]]</td><td valign="top">XmlDoc</td><td valign="top">May Attribute names begin with "xml"?</td></tr>
<tr><td valign="top">[[AllowXmlElement (XmlDoc property)|AllowXmlElement]]</td><td valign="top">XmlDoc</td><td valign="top">May Element names begin with "xml"?</td></tr>
<tr><td valign="top">[[AppendValue (XmlNode subroutine)|AppendValue]]</td><td valign="top">XmlNode</td><td valign="top">Append to value of node</td></tr>
<tr><td valign="top">[[Audit (XmlDoc/XmlNode subroutine)|Audit]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Display selected subtree on audit trail</td></tr>
<tr><td valign="top">[[ClientCertificate (XmlDoc function)|ClientCertificate]]</td><td valign="top">XmlDoc</td><td valign="top">Create XmlDoc with client certificate details</td></tr>
<tr><td valign="top">[[Copy (XmlDoc function)|Copy]]</td><td valign="top">XmlDoc</td><td valign="top">Copy this XmlDoc</td></tr>
<tr><td valign="top">[[Count (XmlNodelist function)|Count]]</td><td valign="top">XmlNodelist</td><td valign="top">Number of nodes in this nodelist</td></tr>
<tr><td valign="top">[[DeepCopy (XmlDoc function)|DeepCopy]]</td><td valign="top">XmlDoc</td><td valign="top">Deep copy this XmlDoc</td></tr>
<tr><td valign="top">[[DeepCopy (XmlNode function)|DeepCopy]]</td><td valign="top">XmlNode</td><td valign="top">Deep copy this node</td></tr>
<tr><td valign="top">[[DeepDiscard (XmlNode subroutine)|DeepDiscard]]</td><td valign="top">XmlNode</td><td valign="top">Do deep discard of an XmlNode object</td></tr>
<tr><td valign="top">[[DefaultURI (XmlDoc/XmlNode function)|DefaultURI]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Default URI in scope at selected node</td></tr>
<tr><td valign="top">[[DeleteSelectionPrefix (XmlDoc subroutine)|DeleteSelectionPrefix]]</td><td valign="top">XmlDoc</td><td valign="top">Delete prefix's XPath-selection association</td></tr>
<tr><td valign="top">[[DeleteSubtree (XmlDoc/XmlNode subroutine)|DeleteSubtree]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Delete selected subtree</td></tr>
<tr><td valign="top">[[DeleteTopElement (XmlDoc subroutine)|DeleteTopElement]]</td><td valign="top">XmlDoc</td><td valign="top">Delete top element from XmlDoc</td></tr>
<tr><td valign="top">[[Difference (XmlNodelist function)|Difference]]</td><td valign="top">XmlNodelist</td><td valign="top">Difference between XmlNodelists</td></tr>
<tr><td valign="top">[[Encoding (XmlDoc property)|Encoding]]</td><td valign="top">XmlDoc</td><td valign="top">Encoding of XML document</td></tr>
<tr><td valign="top">[[Exists (XmlDoc/XmlNode function)|Exists]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Is XPath result non-empty?</td></tr>
<tr><td valign="top">[[InsertCommentBefore (XmlNode function)|InsertCommentBefore]]</td><td valign="top">XmlNode</td><td valign="top">Insert a Comment before this node</td></tr>
<tr><td valign="top">[[InsertElementBefore (XmlNode function)|InsertElementBefore]]</td><td valign="top">XmlNode</td><td valign="top">Insert an Element before this node</td></tr>
<tr><td valign="top">[[InsertPIBefore (XmlNode function)|InsertPIBefore]]</td><td valign="top">XmlNode</td><td valign="top">Insert a processing instruction before this node</td></tr>
<tr><td valign="top">[[InsertSubtreeBefore (XmlNode function)|InsertSubtreeBefore]]</td><td valign="top">XmlNode</td><td valign="top">Insert copy of subtree before this node</td></tr>
<tr><td valign="top">[[InsertTextBefore (XmlNode function)|InsertTextBefore]]</td><td valign="top">XmlNode</td><td valign="top">Insert Text node before this node</td></tr>
<tr><td valign="top">[[InvalidChar (XmlDoc property)|InvalidChar]]</td><td valign="top">XmlDoc</td><td valign="top">Allow invalid characters (obsolete)</td></tr>
<tr><td valign="top">[[InvalidCharacterPosition (XmlDoc function)|InvalidCharacterPosition]]</td><td valign="top">XmlDoc</td><td valign="top">Detect invalid characters</td></tr>
<tr><td valign="top">[[IsSelectionPrefix (XmlDoc function)|IsSelectionPrefix]]</td><td valign="top">XmlDoc</td><td valign="top">Check if prefix has XPath-selection association</td></tr>
<tr><td valign="top">[[IsValidString (XmlDoc function)|IsValidString]]</td><td valign="top">XmlDoc</td><td valign="top">Valid XML Element/Attribute value? (obsolete)</td></tr>
<tr><td valign="top">[[Item (XmlNodelist function)|Item]]</td><td valign="top">XmlNodelist</td><td valign="top">Retrieve an item from this nodelist</td></tr>
<tr><td valign="top">[[Length (XmlDoc/XmlNode function)|Length]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Length of string-value of selected node</td></tr>
<tr><td valign="top">[[LoadCommandInfo (XmlDoc subroutine)|LoadCommandInfo]]</td><td valign="top">XmlDoc</td><td valign="top">Load command info into this XmlDoc</td></tr>
<tr><td valign="top">[[LoadFromRecord (XmlDoc/XmlNode subroutine)|LoadFromRecord]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Load fields and fieldgroups from current record</td></tr>
<tr><td valign="top">[[LoadFromStringlist (XmlDoc/XmlNode function)|LoadFromStringlist]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Deserialize Stringlist into XmlDoc (obsolete)</td></tr>
<tr><td valign="top">[[LoadMessageInfo (XmlDoc subroutine)|LoadMessageInfo]]</td><td valign="top">XmlDoc</td><td valign="top">Load message info into this XmlDoc</td></tr>
<tr><td valign="top">[[LoadMsgctl (XmlDoc subroutine)|LoadMsgctl]]</td><td valign="top">XmlDoc</td><td valign="top">Load MSGCTL commands to this XmlDoc</td></tr>
<tr><td valign="top">[[LoadParameterInfo (XmlDoc subroutine)|LoadParameterInfo]]</td><td valign="top">XmlDoc</td><td valign="top">Load parameter info into this XmlDoc</td></tr>
<tr><td valign="top">[[LoadSystemFunctionInfo (XmlDoc subroutine)|LoadSystemFunctionInfo]]</td><td valign="top">XmlDoc</td><td valign="top">Load info about system $functions into this XmlDoc</td></tr>
<tr><td valign="top">[[LoadSystemMethodInfo (XmlDoc subroutine)|LoadSystemMethodInfo]]</td><td valign="top">XmlDoc</td><td valign="top">Load info about system methods into this XmlDoc</td></tr>
<tr><td valign="top">[[LoadXml (XmlDoc/XmlNode function)|LoadXml]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Deserialize XML document or fragment into XmlDoc Root or into Element XmlNode</td></tr>
<tr><td valign="top">[[LocalName (XmlDoc/XmlNode function)|LocalName]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Name (without prefix) of selected node</td></tr>
<tr><td valign="top">[[Namespace (XmlDoc property)|Namespace]]</td><td valign="top">XmlDoc</td><td valign="top">(Dis)allow or disable prefix handling</td></tr>
<tr><td valign="top">[[New (XmlDoc constructor)|New]]</td><td valign="top">XmlDoc</td><td valign="top">Create a new XmlDoc object</td></tr>
<tr><td valign="top">[[New (XmlNodelist constructor)|New]]</td><td valign="top">XmlNodelist</td><td valign="top">Create a new XmlNodelist</td></tr>
<tr><td valign="top">[[NewFromRecord (XmlDoc function)|NewFromRecord]]</td><td valign="top">XmlDoc</td><td valign="top">Create a new XmlDoc from the current record</td></tr>
<tr><td valign="top">[[Next (XmlNode function)|Next]]</td><td valign="top">XmlNode</td><td valign="top">Get the next node after this node</td></tr>
<tr><td valign="top">[[NoEmptyElement (XmlNode property)|NoEmptyElement]]</td><td valign="top">XmlNode</td><td valign="top">Suppress/produce empty tag when serializing this Element, if childless</td></tr>
<tr><td valign="top">[[Prefix (XmlDoc/XmlNode function)|Prefix]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Prefix part of name of selected node</td></tr>
<tr><td valign="top">[[PrefixURI (XmlDoc/XmlNode function)|PrefixURI]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">URI of specified prefix in context of selected node</td></tr>
<tr><td valign="top">[[Previous (XmlNode function)|Previous]]</td><td valign="top">XmlNode</td><td valign="top">Get node previous to this node</td></tr>
<tr><td valign="top">[[Print (XmlDoc/XmlNode subroutine)|Print]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Print selected subtree</td></tr>
<tr><td valign="top">[[QName (XmlDoc/XmlNode function)|QName]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Name (with prefix, if any) of selected node</td></tr>
<tr><td valign="top">[[SelectCount (XmlDoc/XmlNode function)|SelectCount]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Number of selected nodes</td></tr>
<tr><td valign="top">[[SelectionNamespace (XmlDoc property)|SelectionNamespace]]</td><td valign="top">XmlDoc</td><td valign="top">Bind prefix to URI (or null) for XPath</td></tr>
<tr><td valign="top">[[SelectNodes (XmlDoc/XmlNode function)|SelectNodes]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Get list of selected nodes as XmlNodelist</td></tr>
<tr><td valign="top">[[SelectSingleNode (XmlDoc/XmlNode function)|SelectSingleNode]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Get selected node as XmlNode</td></tr>
<tr><td valign="top">[[Serial (XmlDoc/XmlNode function)|Serial]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Serialize selected subtree as string</td></tr>
<tr><td valign="top">[[Standalone (XmlDoc property)|Standalone]]</td><td valign="top">XmlDoc</td><td valign="top">Standalone specification in "XML declaration"</td></tr>
<tr><td valign="top">[[ToXPathString (XmlDoc/XmlNode function)|ToXPathString]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">XPath expression for selected node</td></tr>
<tr><td valign="top">[[ToXPathStringlist (XmlDoc/XmlNode function)|ToXPathStringlist]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">XPath expression (in Stringlist) for selected node</td></tr>
<tr><td valign="top">[[Trace (XmlDoc/XmlNode subroutine)|Trace]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Display selected subtree on Trace stream</td></tr>
<tr><td valign="top">[[Type (XmlDoc/XmlNode function)|Type]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Type of selected node</td></tr>
<tr><td valign="top">[[UnionSelected (XmlNodelist function)|UnionSelected]]</td><td valign="top">XmlNodelist</td><td valign="top">Union of XmlNodelist and selected nodes</td></tr>
<tr><td valign="top">[[URI (XmlDoc/XmlNode function)|URI]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">Namespace URI of name of selected node</td></tr>
<tr><td valign="top">[[Value (XmlDoc/XmlNode property)|Value]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">String-value of selected node</td></tr>
<tr><td valign="top">[[ValueDefault (XmlDoc/XmlNode function)|ValueDefault]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">String-value of selected node (allow empty XPath)</td></tr>
<tr><td valign="top">[[Version (XmlDoc property)|Version]]</td><td valign="top">XmlDoc</td><td valign="top">Version number in "XML declaration"</td></tr>
<tr><td valign="top">[[WebReceive (XmlDoc function)|WebReceive]]</td><td valign="top">XmlDoc</td><td valign="top">Deserialize Web request into this XmlDoc</td></tr>
<tr><td valign="top">[[WebSend (XmlDoc subroutine)|WebSend]]</td><td valign="top">XmlDoc</td><td valign="top">Serialize XmlDoc as Web response</td></tr>
<tr><td valign="top">[[Xml (XmlDoc function)|Xml]]</td><td valign="top">XmlDoc</td><td valign="top">Serialize XmlDoc as UTF-8 string</td></tr>
<tr><td valign="top">[[XmlDoc (XmlNode function)|XmlDoc]]</td><td valign="top">XmlNode</td><td valign="top">Get the XmlDoc associated with this node</td></tr>
<tr><td valign="top">[[XmlDoc (XmlNodelist function)|XmlDoc]]</td><td valign="top">XmlNodelist</td><td valign="top">Get the XmlDoc associated with this nodelist</td></tr>
<tr><td valign="top">[[XPathNodeID (XmlDoc/XmlNode function)|XPathNodeID]]</td><td valign="top">XmlDoc/XmlNode</td><td valign="top">XPath expression (in Stringlist) for selected node</td></tr>
</table>
==See also==
<table class="list"><tr>
<td valign="top"><ul style="margin-top:0px;">
<li>[[XmlDoc class]]
<li>[[XmlNode class]]
<li>[[XmlNodelist class]]
</ul></td>
<td valign="top"><ul style="margin-top:0px;">
<li>[[List of XmlDoc methods]]
<li>[[List of XmlNode methods]]
<li>[[List of XmlNodelist methods]]
</ul></td>
<td valign="top"><ul style="margin-top:0px;">
<li>[[XmlDoc methods syntax]]
<li>[[XmlNode methods syntax]]
<li>[[XmlNodelist methods syntax]]
</ul></td>
</tr>
</table>
[[Category:Lists of methods]]

SirAud parameters

2022-02-24T21:38:44Z

Tom: /* NCP parameter */

<var class="product">SirAud</var> has a set of parameters you can use to restrict the size of some
reports or otherwise configure the <var class="product">SirAud</var> run.
These parameters must be provided in either of these ways:
<ul>
<li>As a PARM on the EXEC card in MVS, for example:
<nowiki>//SIRAUD EXEC PGM=SIRAUD,PARM='NSUBS=10 ALLPR'
</nowiki>

<li>As options on the M204CMS command in CMS, for example:
<nowiki>M204CMS SIRAUD ( NSUBS 10 ALLPR %
</nowiki>
</ul>

Under MVS, parameters are specified either by a parameter name alone or
by a parameter name followed by an equal sign (<tt>=</tt>) followed by the parameter value.
Under CMS, parameters are specified by a parameter name followed
by a space and a percent sign (<tt>%</tt>), or by a parameter name followed by a space and a parameter value.

This page describes the parameter settings that are available for <var class="product">SirAud</var>.
Note: You can change the default setting for some of the parameters; see [[#SirAud default customization|SirAud default customization]], below. 

==ALLPR and NOPR==
These are two of the report selection parameters.
The report selection parameters determine which reports are produced.
They also direct all of the report output of <var class="product">SirAud</var> to be written to the SYSPRINT output file, rather than
having each of <var class="product">SirAud</var>'s reports written to a separate output file.
If any report selection parameter is specified, all of the <var class="product">SirAud</var> report output is written to SYSPRINT, and only to there.

The report selection parameters are <var>ALLPR</var>, <var>NOPR</var>, and the following:
<ul>
<li><var>FILERP</var> and <var>NOFILERP</var>
<li><var>PERFRP</var> and <var>NOPERFRP</var>
<li><var>PROCRP</var> and <var>NOPROCRP</var>
<li><var>SUBRP</var> and <var>NOSUBRP</var>
<li><var>UTBLRP</var> and <var>NOUTBLRP</var>
<li><var>UTBLSM</var> and <var>NOUTBLSM</var>
</ul>
Any of the above individual report parameters beginning with <code>NO</code> is called the "negative" form of
the parameter, and it indicates that the given report should not be produced
The form without <code>NO</code> is called the "positive" form, and it indicates the given report should be produced.

<var>ALLPR</var> is a shorthand for a list of all of the positive forms of the
individual report parameters.
<var>NOPR</var> is a shorthand for a list of all of the negative forms of the
individual report parameters.

The effect of the report selection parameters is cumulative, and the specification of any of them can override the effect of a preceding specification.
If the first report selection parameter specified is a positive individual
report parameter, an implicit <code>NOPR</code> precedes that.
If the first report selection parameter specified is a negative individual
report parameter, an implicit <code>ALLPR</code> precedes that.

Thus, for example, the following produces all reports except PERFREPT and FILEREPT:
PARM=(NOPERFRP,NOFILERP)


The following produces only the UTBLSUMM and SUBREPT reports:
PARM=(UTBLSM,SUBRP)


And the following produces all reports except PROCREPT (the <code>UTBLRP</code> in this example is superfluous):
PARM=(NOPROCRP,UTBLRP)


You may customize your <var class="product">SirAud</var> load module so that <var>ALLPR</var> is the default; see
[[SirAud parameters#cszallp|ALLPR parameter customization]].

==FROM parameter==
This parameter is used to restrict the analysis of the journal
to those journal blocks that contain records that
are at or after the indicated date and time.
If the time on the journal block's trailer is greater than or equal to
the <var>FROM</var> specification, the records in that block are included in the
report analysis.
Consequently, some records that are earlier than the <var>FROM</var> setting may be included.

The <var>FROM</var> syntax is:
FROM = yyddd | time | yyddd time 

The <var>FROM</var> parameter options are:
<table>
<tr><th>yyddd</th>
<td>Indicates the date, in Julian format, where the <var>FROM</var> century is such that the start of the time period is within 40 years of the start date of the journal.

The analysis starts at the first journal record in the first journal block on or after the indicated day.</td></tr>

<tr><th>time</th>
<td>Indicates the 24-hour time in the format hh:mm[:ss]; ss defaults to 00.

The analysis starts at the first journal record in the first journal block on or after the indicated time of the first day of the journal.
If the <var class="term">time</var> value is less than the time of the first journal block, the analysis starts at the first journal record in the first journal block on or after the indicated time of the day after the first day of the journal.</td></tr>

<tr><th nowrap>yyddd time</th>
<td>Indicates the date, in Julian format, where the <var>FROM</var> century is such that the start of the time period is within 40 years of the start date of the journal, and the 24-hour time in the format hh:mm[:ss] (where ss defaults to 00).

The analysis starts at the first journal record in the first journal block on or after the indicated time of the indicated day.
<blockquote class="note">Note: This format cannot be passed as a command line program parameter under CMS, although it may be used in a SYSIN file record (see [[SirAud#sysin|SYSIN]]). Under MVS, the format is:
...,PARM=' ... FROM=yyddd time ... '

</blockquote></td></tr>
</table>

Also see the [[#toparm|TO parameter]], which can be used to specify the end of the date/time range for analysis.

Regardless of any date range restriction specified by <var>FROM</var> or
<var>TO</var>, <var class="product">SirAud</var> examines the beginning part of the journal, through the following message:
<code>M204.0075: INITIALIZATION COMPLETED. BUFFERS = n</code>.
The histogram of journal record types will include totals from this
initialization section of the journal as well as from the date range
selected for analysis.

A date range can be useful to provide a reference for interpreting
other measures of <var class="product">Model 204</var> activity.
For example, <var class="product">[[SirTune]]</var> can show ratios for running procedure A versus other procedures:
Assume that a <var class="product">SirTune</var> report over some busy time period shows procedure A using 11% of the CPU in
that period, and then you change the procedure.
After the changes, <var class="product">SirTune</var> on a new busy period might show procedure A CPU goes up to 12%.
One way to check the effectiveness of your changes is to use
<var class="product">SirAud</var> [[SirAud report contents#PROCREPT|PROCREPT]] reports with date/time ranges to see if this increase in CPU correlates to an increased number of invocations between the two busy times.

==FILERP and NOFILERP==
The <var>FILERP</var> and <var>NOFILERP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>FILERP</var>) or suppressing (<var>NOFILERP</var>) the [[SirAud report contents#FILEREPT|FILEREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==MAXBLK parameter==
Syntax:
MAXBLK = n

This parameter is used to specify the number of journal blocks to process.

==NAMEOFF parameter==
Syntax:
NAMEOFF = n 

This can be used, under the direction of Technical Support,
to facilitate running <var class="product">SirAud</var> with newer releases of <var class="product">Model 204</var>,
compensating for changes in the journal format.

==NCP parameter==
Syntax:
NCP = 1-255 

This parameter sets the number of channel programs to use for the input journal.
A higher value can improve journal I/O performance. If this parameter not specified, the value specified in the JOURNAL DD statement is used, otherwise the default of 22 is used. Under CMS, this parameter is allowed but ignored, and the value is set to 1.

==NFILES parameter==
Syntax:
NFILES = n 

This parameter is used to restrict the number of files summarized in [[SirAud report contents#FILEREPT|FILEREPT]]
to the top <var class="term">n</var> files by total disk I/O.

==NPROCS parameter==
Syntax:
NPROCS = n 

This parameter is used to restrict the number of procedures summarized in
[[SirAud report contents#PROCREPT|PROCREPT]] to the top <var class="term">n</var> procedures by total CPU.

==NSUBS parameter==
Syntax:
NSUBS = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#SUBREPT|SUBREPT]] to the top <var class="term">n</var> subsystems by total CPU.

==NUTBLS parameter==
Syntax:
NUTBLS = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#UTBLREPT|UTBLREPT]] to the top <var class="term">n</var> subsystems by server size.

==NUSUMM parameter==
Syntax:
NUSUMM = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#UTBLSUMM|UTBLSUMM]] to the top <var class="term">n</var> subsystems by server size.

==PERFRP and NOPERFRP parameters==
The <var>PERFRP</var> and <var>NOPERFRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>PERFRP</var>) or suppressing (<var>NOPERFRP</var>) the [[SirAud report contents#PERFREPT|PERFREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==PROCRP and NOPROCRP parameters==
The <var>PROCRP</var> and <var>NOPROCRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>PROCRP</var>) or suppressing (<var>NOPROCRP</var>) the [[SirAud report contents#PROCREPT|PROCREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==SKIPBLK parameter==
Syntax:
SKIPBLK = n 

This parameter is used to specify a number of journal blocks to skip.

==SUBRP and NOSUBRP parameters==
The <var>SUBRP</var> and <var>NOSUBRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>SUBRP</var>) or suppressing (<var>NOSUBRP</var>) the [[SirAud report contents#SUBREPT|SUBREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==TO parameter==
Syntax:
TO = yyddd | time | yyddd time 

This parameter is used to restrict the analysis of the journal
to those journal blocks that contain records that are at the indicated date and time.
If the time on the journal block's header is less than or equal to the <var>TO</var> specification, the records in that block are included in the report analysis.
Consequently, some records that are later than the <var>TO</var> setting may be included.

The <var>TO</var> parameter options are:
<table>
<tr><th>yyddd</th>
<td>Indicates the date, in Julian format, where the <var>TO</var> century is such that the end of the time period is within 40 years of the start date of the journal.

The analysis ends with the last journal record in the last journal block on or before the indicated day.</td></tr>

<tr><th>time</th>
<td>Indicates the 24-hour time in the hh:mm[:ss] format; ss defaults to 59.

The analysis ends with the last journal record in the last journal block on or before the indicated time of the starting day of analysis.
If the <code>time</code> value is less than the starting time of analysis, the analysis ends with the last journal record in the last journal block on or before the indicated time of the day after the starting day of analysis. 

The starting date and time of analysis is specified by the <var>FROM</var> parameter, if present, and otherwise is the date and time at the start of the journal.</td></tr>

<tr><th nowrap>yyddd time</th>
<td>Indicates the date, in Julian format, where the <var>TO</var> century is such that the end of the time period is within 40 years of the start date of the journal, and the 24-hour time in the format hh:mm[:ss]; ss defaults to 59.

The analysis ends with the last journal record in the last journal block on or before the indicated time of the indicated day.

<blockquote class="note">Note: This format cannot be passed as a command line program parameter under CMS, although it may be used in a SYSIN file record (see [[SirAud#sysin|SYSIN]]).
Under MVS, the format is:
...,PARM=' ... TO=yyddd time ... '

</blockquote></td></tr>
</table>

Also see the [[#from|FROM parameter]], which can be used to specify the start of the date/time range for analysis.
The description there also provides an example of one benefit of date/time range selection with <var class="product">SirAud</var>.

==UTBLRANG parameter==
Syntax:
UTBLRANG = n 

This parameter is used to specify the number of standard deviations a server table
highwater mark for an individual procedure is allowed to vary from the
mean for the subsystem before the procedure is flagged for [[SirAud report contents#UTBLREPT|UTBLREPT]].

The default is 2.

==UTBLRP and NOUTBLRP parameters==
The <var>UTBLRP</var> and <var>NOUTBLRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>UTBLRP</var>) or suppressing (<var>NOUTBLRP</var>) the [[SirAud report contents#UTBLREPT|UTBLREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other
report selection parameters.

==UTBLSM and NOUTBLSM parameters==
The <var>UTBLSM</var> and <var>NOUTBLSM</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>UTBLSM</var>) or suppressing (<var>NOUTBLSM</var>) the [[SirAud report contents#UTBLSUMM|UTBLSUMM]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other
report selection parameters.

You can change some of the <var class="product">SirAud</var> defaults by applying zaps any time after you have installed the load module.
This page contains the customizations you can perform.

==SirAud default customization==

===ALLPR parameter customization===
Apply the following zap to make the <var>[[SirAud parameters#allpr|ALLPR]]</var> parameter the default:
NAME SIRAUD JCUST
VER 08 00
REP 08 80 ALLPR is default



==See also==
{{Template:SirAud topic list}}

[[Category:SirAud]]

SirAud parameters

2022-02-24T21:37:28Z

Tom: /* NCP parameter */

<var class="product">SirAud</var> has a set of parameters you can use to restrict the size of some
reports or otherwise configure the <var class="product">SirAud</var> run.
These parameters must be provided in either of these ways:
<ul>
<li>As a PARM on the EXEC card in MVS, for example:
<nowiki>//SIRAUD EXEC PGM=SIRAUD,PARM='NSUBS=10 ALLPR'
</nowiki>

<li>As options on the M204CMS command in CMS, for example:
<nowiki>M204CMS SIRAUD ( NSUBS 10 ALLPR %
</nowiki>
</ul>

Under MVS, parameters are specified either by a parameter name alone or
by a parameter name followed by an equal sign (<tt>=</tt>) followed by the parameter value.
Under CMS, parameters are specified by a parameter name followed
by a space and a percent sign (<tt>%</tt>), or by a parameter name followed by a space and a parameter value.

This page describes the parameter settings that are available for <var class="product">SirAud</var>.
Note: You can change the default setting for some of the parameters; see [[#SirAud default customization|SirAud default customization]], below. 

==ALLPR and NOPR==
These are two of the report selection parameters.
The report selection parameters determine which reports are produced.
They also direct all of the report output of <var class="product">SirAud</var> to be written to the SYSPRINT output file, rather than
having each of <var class="product">SirAud</var>'s reports written to a separate output file.
If any report selection parameter is specified, all of the <var class="product">SirAud</var> report output is written to SYSPRINT, and only to there.

The report selection parameters are <var>ALLPR</var>, <var>NOPR</var>, and the following:
<ul>
<li><var>FILERP</var> and <var>NOFILERP</var>
<li><var>PERFRP</var> and <var>NOPERFRP</var>
<li><var>PROCRP</var> and <var>NOPROCRP</var>
<li><var>SUBRP</var> and <var>NOSUBRP</var>
<li><var>UTBLRP</var> and <var>NOUTBLRP</var>
<li><var>UTBLSM</var> and <var>NOUTBLSM</var>
</ul>
Any of the above individual report parameters beginning with <code>NO</code> is called the "negative" form of
the parameter, and it indicates that the given report should not be produced
The form without <code>NO</code> is called the "positive" form, and it indicates the given report should be produced.

<var>ALLPR</var> is a shorthand for a list of all of the positive forms of the
individual report parameters.
<var>NOPR</var> is a shorthand for a list of all of the negative forms of the
individual report parameters.

The effect of the report selection parameters is cumulative, and the specification of any of them can override the effect of a preceding specification.
If the first report selection parameter specified is a positive individual
report parameter, an implicit <code>NOPR</code> precedes that.
If the first report selection parameter specified is a negative individual
report parameter, an implicit <code>ALLPR</code> precedes that.

Thus, for example, the following produces all reports except PERFREPT and FILEREPT:
PARM=(NOPERFRP,NOFILERP)


The following produces only the UTBLSUMM and SUBREPT reports:
PARM=(UTBLSM,SUBRP)


And the following produces all reports except PROCREPT (the <code>UTBLRP</code> in this example is superfluous):
PARM=(NOPROCRP,UTBLRP)


You may customize your <var class="product">SirAud</var> load module so that <var>ALLPR</var> is the default; see
[[SirAud parameters#cszallp|ALLPR parameter customization]].

==FROM parameter==
This parameter is used to restrict the analysis of the journal
to those journal blocks that contain records that
are at or after the indicated date and time.
If the time on the journal block's trailer is greater than or equal to
the <var>FROM</var> specification, the records in that block are included in the
report analysis.
Consequently, some records that are earlier than the <var>FROM</var> setting may be included.

The <var>FROM</var> syntax is:
FROM = yyddd | time | yyddd time 

The <var>FROM</var> parameter options are:
<table>
<tr><th>yyddd</th>
<td>Indicates the date, in Julian format, where the <var>FROM</var> century is such that the start of the time period is within 40 years of the start date of the journal.

The analysis starts at the first journal record in the first journal block on or after the indicated day.</td></tr>

<tr><th>time</th>
<td>Indicates the 24-hour time in the format hh:mm[:ss]; ss defaults to 00.

The analysis starts at the first journal record in the first journal block on or after the indicated time of the first day of the journal.
If the <var class="term">time</var> value is less than the time of the first journal block, the analysis starts at the first journal record in the first journal block on or after the indicated time of the day after the first day of the journal.</td></tr>

<tr><th nowrap>yyddd time</th>
<td>Indicates the date, in Julian format, where the <var>FROM</var> century is such that the start of the time period is within 40 years of the start date of the journal, and the 24-hour time in the format hh:mm[:ss] (where ss defaults to 00).

The analysis starts at the first journal record in the first journal block on or after the indicated time of the indicated day.
<blockquote class="note">Note: This format cannot be passed as a command line program parameter under CMS, although it may be used in a SYSIN file record (see [[SirAud#sysin|SYSIN]]). Under MVS, the format is:
...,PARM=' ... FROM=yyddd time ... '

</blockquote></td></tr>
</table>

Also see the [[#toparm|TO parameter]], which can be used to specify the end of the date/time range for analysis.

Regardless of any date range restriction specified by <var>FROM</var> or
<var>TO</var>, <var class="product">SirAud</var> examines the beginning part of the journal, through the following message:
<code>M204.0075: INITIALIZATION COMPLETED. BUFFERS = n</code>.
The histogram of journal record types will include totals from this
initialization section of the journal as well as from the date range
selected for analysis.

A date range can be useful to provide a reference for interpreting
other measures of <var class="product">Model 204</var> activity.
For example, <var class="product">[[SirTune]]</var> can show ratios for running procedure A versus other procedures:
Assume that a <var class="product">SirTune</var> report over some busy time period shows procedure A using 11% of the CPU in
that period, and then you change the procedure.
After the changes, <var class="product">SirTune</var> on a new busy period might show procedure A CPU goes up to 12%.
One way to check the effectiveness of your changes is to use
<var class="product">SirAud</var> [[SirAud report contents#PROCREPT|PROCREPT]] reports with date/time ranges to see if this increase in CPU correlates to an increased number of invocations between the two busy times.

==FILERP and NOFILERP==
The <var>FILERP</var> and <var>NOFILERP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>FILERP</var>) or suppressing (<var>NOFILERP</var>) the [[SirAud report contents#FILEREPT|FILEREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==MAXBLK parameter==
Syntax:
MAXBLK = n

This parameter is used to specify the number of journal blocks to process.

==NAMEOFF parameter==
Syntax:
NAMEOFF = n 

This can be used, under the direction of Technical Support,
to facilitate running <var class="product">SirAud</var> with newer releases of <var class="product">Model 204</var>,
compensating for changes in the journal format.

==NCP parameter==
Syntax:
NCP = 1-255 

This parameter sets the number of channel programs to use for the input journal.
A higher value can improve journal I/O performance. If this parameter not specified, the value specified in the JOURNAL DD statement is used, otherwise the default of 22 is used. Under CMS, this parameter is allowed, but ignored.

==NFILES parameter==
Syntax:
NFILES = n 

This parameter is used to restrict the number of files summarized in [[SirAud report contents#FILEREPT|FILEREPT]]
to the top <var class="term">n</var> files by total disk I/O.

==NPROCS parameter==
Syntax:
NPROCS = n 

This parameter is used to restrict the number of procedures summarized in
[[SirAud report contents#PROCREPT|PROCREPT]] to the top <var class="term">n</var> procedures by total CPU.

==NSUBS parameter==
Syntax:
NSUBS = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#SUBREPT|SUBREPT]] to the top <var class="term">n</var> subsystems by total CPU.

==NUTBLS parameter==
Syntax:
NUTBLS = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#UTBLREPT|UTBLREPT]] to the top <var class="term">n</var> subsystems by server size.

==NUSUMM parameter==
Syntax:
NUSUMM = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#UTBLSUMM|UTBLSUMM]] to the top <var class="term">n</var> subsystems by server size.

==PERFRP and NOPERFRP parameters==
The <var>PERFRP</var> and <var>NOPERFRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>PERFRP</var>) or suppressing (<var>NOPERFRP</var>) the [[SirAud report contents#PERFREPT|PERFREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==PROCRP and NOPROCRP parameters==
The <var>PROCRP</var> and <var>NOPROCRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>PROCRP</var>) or suppressing (<var>NOPROCRP</var>) the [[SirAud report contents#PROCREPT|PROCREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==SKIPBLK parameter==
Syntax:
SKIPBLK = n 

This parameter is used to specify a number of journal blocks to skip.

==SUBRP and NOSUBRP parameters==
The <var>SUBRP</var> and <var>NOSUBRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>SUBRP</var>) or suppressing (<var>NOSUBRP</var>) the [[SirAud report contents#SUBREPT|SUBREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==TO parameter==
Syntax:
TO = yyddd | time | yyddd time 

This parameter is used to restrict the analysis of the journal
to those journal blocks that contain records that are at the indicated date and time.
If the time on the journal block's header is less than or equal to the <var>TO</var> specification, the records in that block are included in the report analysis.
Consequently, some records that are later than the <var>TO</var> setting may be included.

The <var>TO</var> parameter options are:
<table>
<tr><th>yyddd</th>
<td>Indicates the date, in Julian format, where the <var>TO</var> century is such that the end of the time period is within 40 years of the start date of the journal.

The analysis ends with the last journal record in the last journal block on or before the indicated day.</td></tr>

<tr><th>time</th>
<td>Indicates the 24-hour time in the hh:mm[:ss] format; ss defaults to 59.

The analysis ends with the last journal record in the last journal block on or before the indicated time of the starting day of analysis.
If the <code>time</code> value is less than the starting time of analysis, the analysis ends with the last journal record in the last journal block on or before the indicated time of the day after the starting day of analysis. 

The starting date and time of analysis is specified by the <var>FROM</var> parameter, if present, and otherwise is the date and time at the start of the journal.</td></tr>

<tr><th nowrap>yyddd time</th>
<td>Indicates the date, in Julian format, where the <var>TO</var> century is such that the end of the time period is within 40 years of the start date of the journal, and the 24-hour time in the format hh:mm[:ss]; ss defaults to 59.

The analysis ends with the last journal record in the last journal block on or before the indicated time of the indicated day.

<blockquote class="note">Note: This format cannot be passed as a command line program parameter under CMS, although it may be used in a SYSIN file record (see [[SirAud#sysin|SYSIN]]).
Under MVS, the format is:
...,PARM=' ... TO=yyddd time ... '

</blockquote></td></tr>
</table>

Also see the [[#from|FROM parameter]], which can be used to specify the start of the date/time range for analysis.
The description there also provides an example of one benefit of date/time range selection with <var class="product">SirAud</var>.

==UTBLRANG parameter==
Syntax:
UTBLRANG = n 

This parameter is used to specify the number of standard deviations a server table
highwater mark for an individual procedure is allowed to vary from the
mean for the subsystem before the procedure is flagged for [[SirAud report contents#UTBLREPT|UTBLREPT]].

The default is 2.

==UTBLRP and NOUTBLRP parameters==
The <var>UTBLRP</var> and <var>NOUTBLRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>UTBLRP</var>) or suppressing (<var>NOUTBLRP</var>) the [[SirAud report contents#UTBLREPT|UTBLREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other
report selection parameters.

==UTBLSM and NOUTBLSM parameters==
The <var>UTBLSM</var> and <var>NOUTBLSM</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>UTBLSM</var>) or suppressing (<var>NOUTBLSM</var>) the [[SirAud report contents#UTBLSUMM|UTBLSUMM]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other
report selection parameters.

You can change some of the <var class="product">SirAud</var> defaults by applying zaps any time after you have installed the load module.
This page contains the customizations you can perform.

==SirAud default customization==

===ALLPR parameter customization===
Apply the following zap to make the <var>[[SirAud parameters#allpr|ALLPR]]</var> parameter the default:
NAME SIRAUD JCUST
VER 08 00
REP 08 80 ALLPR is default



==See also==
{{Template:SirAud topic list}}

[[Category:SirAud]]

AUD039 NCP value must be from 1-255

2022-02-24T19:35:37Z

Tom:

An invalid NCP value was specified in the EXEC statement parameters. If no value is specified in the PARM= parameter, the value specified in the JOURNAL DD statement is used, otherwise a default of 22 is used. A higher value can improve journal I/O performance.

[[Category:SirAud messages]]

AUD038 (message text)

2022-02-24T18:28:11Z

Tom:

This informational message displays the date, time, and message text from a Model 204 journal entry indicating a journal stream switch occurred during the run.

[[Category:SirAud messages]]

SirAud parameters

2022-02-24T16:01:38Z

Tom: /* NCP parameter */

<var class="product">SirAud</var> has a set of parameters you can use to restrict the size of some
reports or otherwise configure the <var class="product">SirAud</var> run.
These parameters must be provided in either of these ways:
<ul>
<li>As a PARM on the EXEC card in MVS, for example:
<nowiki>//SIRAUD EXEC PGM=SIRAUD,PARM='NSUBS=10 ALLPR'
</nowiki>

<li>As options on the M204CMS command in CMS, for example:
<nowiki>M204CMS SIRAUD ( NSUBS 10 ALLPR %
</nowiki>
</ul>

Under MVS, parameters are specified either by a parameter name alone or
by a parameter name followed by an equal sign (<tt>=</tt>) followed by the parameter value.
Under CMS, parameters are specified by a parameter name followed
by a space and a percent sign (<tt>%</tt>), or by a parameter name followed by a space and a parameter value.

This page describes the parameter settings that are available for <var class="product">SirAud</var>.
Note: You can change the default setting for some of the parameters; see [[#SirAud default customization|SirAud default customization]], below. 

==ALLPR and NOPR==
These are two of the report selection parameters.
The report selection parameters determine which reports are produced.
They also direct all of the report output of <var class="product">SirAud</var> to be written to the SYSPRINT output file, rather than
having each of <var class="product">SirAud</var>'s reports written to a separate output file.
If any report selection parameter is specified, all of the <var class="product">SirAud</var> report output is written to SYSPRINT, and only to there.

The report selection parameters are <var>ALLPR</var>, <var>NOPR</var>, and the following:
<ul>
<li><var>FILERP</var> and <var>NOFILERP</var>
<li><var>PERFRP</var> and <var>NOPERFRP</var>
<li><var>PROCRP</var> and <var>NOPROCRP</var>
<li><var>SUBRP</var> and <var>NOSUBRP</var>
<li><var>UTBLRP</var> and <var>NOUTBLRP</var>
<li><var>UTBLSM</var> and <var>NOUTBLSM</var>
</ul>
Any of the above individual report parameters beginning with <code>NO</code> is called the "negative" form of
the parameter, and it indicates that the given report should not be produced
The form without <code>NO</code> is called the "positive" form, and it indicates the given report should be produced.

<var>ALLPR</var> is a shorthand for a list of all of the positive forms of the
individual report parameters.
<var>NOPR</var> is a shorthand for a list of all of the negative forms of the
individual report parameters.

The effect of the report selection parameters is cumulative, and the specification of any of them can override the effect of a preceding specification.
If the first report selection parameter specified is a positive individual
report parameter, an implicit <code>NOPR</code> precedes that.
If the first report selection parameter specified is a negative individual
report parameter, an implicit <code>ALLPR</code> precedes that.

Thus, for example, the following produces all reports except PERFREPT and FILEREPT:
PARM=(NOPERFRP,NOFILERP)


The following produces only the UTBLSUMM and SUBREPT reports:
PARM=(UTBLSM,SUBRP)


And the following produces all reports except PROCREPT (the <code>UTBLRP</code> in this example is superfluous):
PARM=(NOPROCRP,UTBLRP)


You may customize your <var class="product">SirAud</var> load module so that <var>ALLPR</var> is the default; see
[[SirAud parameters#cszallp|ALLPR parameter customization]].

==FROM parameter==
This parameter is used to restrict the analysis of the journal
to those journal blocks that contain records that
are at or after the indicated date and time.
If the time on the journal block's trailer is greater than or equal to
the <var>FROM</var> specification, the records in that block are included in the
report analysis.
Consequently, some records that are earlier than the <var>FROM</var> setting may be included.

The <var>FROM</var> syntax is:
FROM = yyddd | time | yyddd time 

The <var>FROM</var> parameter options are:
<table>
<tr><th>yyddd</th>
<td>Indicates the date, in Julian format, where the <var>FROM</var> century is such that the start of the time period is within 40 years of the start date of the journal.

The analysis starts at the first journal record in the first journal block on or after the indicated day.</td></tr>

<tr><th>time</th>
<td>Indicates the 24-hour time in the format hh:mm[:ss]; ss defaults to 00.

The analysis starts at the first journal record in the first journal block on or after the indicated time of the first day of the journal.
If the <var class="term">time</var> value is less than the time of the first journal block, the analysis starts at the first journal record in the first journal block on or after the indicated time of the day after the first day of the journal.</td></tr>

<tr><th nowrap>yyddd time</th>
<td>Indicates the date, in Julian format, where the <var>FROM</var> century is such that the start of the time period is within 40 years of the start date of the journal, and the 24-hour time in the format hh:mm[:ss] (where ss defaults to 00).

The analysis starts at the first journal record in the first journal block on or after the indicated time of the indicated day.
<blockquote class="note">Note: This format cannot be passed as a command line program parameter under CMS, although it may be used in a SYSIN file record (see [[SirAud#sysin|SYSIN]]). Under MVS, the format is:
...,PARM=' ... FROM=yyddd time ... '

</blockquote></td></tr>
</table>

Also see the [[#toparm|TO parameter]], which can be used to specify the end of the date/time range for analysis.

Regardless of any date range restriction specified by <var>FROM</var> or
<var>TO</var>, <var class="product">SirAud</var> examines the beginning part of the journal, through the following message:
<code>M204.0075: INITIALIZATION COMPLETED. BUFFERS = n</code>.
The histogram of journal record types will include totals from this
initialization section of the journal as well as from the date range
selected for analysis.

A date range can be useful to provide a reference for interpreting
other measures of <var class="product">Model 204</var> activity.
For example, <var class="product">[[SirTune]]</var> can show ratios for running procedure A versus other procedures:
Assume that a <var class="product">SirTune</var> report over some busy time period shows procedure A using 11% of the CPU in
that period, and then you change the procedure.
After the changes, <var class="product">SirTune</var> on a new busy period might show procedure A CPU goes up to 12%.
One way to check the effectiveness of your changes is to use
<var class="product">SirAud</var> [[SirAud report contents#PROCREPT|PROCREPT]] reports with date/time ranges to see if this increase in CPU correlates to an increased number of invocations between the two busy times.

==FILERP and NOFILERP==
The <var>FILERP</var> and <var>NOFILERP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>FILERP</var>) or suppressing (<var>NOFILERP</var>) the [[SirAud report contents#FILEREPT|FILEREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==MAXBLK parameter==
Syntax:
MAXBLK = n

This parameter is used to specify the number of journal blocks to process.

==NAMEOFF parameter==
Syntax:
NAMEOFF = n 

This can be used, under the direction of Technical Support,
to facilitate running <var class="product">SirAud</var> with newer releases of <var class="product">Model 204</var>,
compensating for changes in the journal format.

==NCP parameter==
Syntax:
NCP = 1-255 

This parameter sets the number of channel programs to use for the input journal.
A higher value can improve I/O performance. If this parameter not specified, the value specified in the JOURNAL DD statement is used, otherwise the default of 22 is used. Under CMS, this parameter is allowed, but ignored.

==NFILES parameter==
Syntax:
NFILES = n 

This parameter is used to restrict the number of files summarized in [[SirAud report contents#FILEREPT|FILEREPT]]
to the top <var class="term">n</var> files by total disk I/O.

==NPROCS parameter==
Syntax:
NPROCS = n 

This parameter is used to restrict the number of procedures summarized in
[[SirAud report contents#PROCREPT|PROCREPT]] to the top <var class="term">n</var> procedures by total CPU.

==NSUBS parameter==
Syntax:
NSUBS = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#SUBREPT|SUBREPT]] to the top <var class="term">n</var> subsystems by total CPU.

==NUTBLS parameter==
Syntax:
NUTBLS = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#UTBLREPT|UTBLREPT]] to the top <var class="term">n</var> subsystems by server size.

==NUSUMM parameter==
Syntax:
NUSUMM = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#UTBLSUMM|UTBLSUMM]] to the top <var class="term">n</var> subsystems by server size.

==PERFRP and NOPERFRP parameters==
The <var>PERFRP</var> and <var>NOPERFRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>PERFRP</var>) or suppressing (<var>NOPERFRP</var>) the [[SirAud report contents#PERFREPT|PERFREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==PROCRP and NOPROCRP parameters==
The <var>PROCRP</var> and <var>NOPROCRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>PROCRP</var>) or suppressing (<var>NOPROCRP</var>) the [[SirAud report contents#PROCREPT|PROCREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==SKIPBLK parameter==
Syntax:
SKIPBLK = n 

This parameter is used to specify a number of journal blocks to skip.

==SUBRP and NOSUBRP parameters==
The <var>SUBRP</var> and <var>NOSUBRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>SUBRP</var>) or suppressing (<var>NOSUBRP</var>) the [[SirAud report contents#SUBREPT|SUBREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==TO parameter==
Syntax:
TO = yyddd | time | yyddd time 

This parameter is used to restrict the analysis of the journal
to those journal blocks that contain records that are at the indicated date and time.
If the time on the journal block's header is less than or equal to the <var>TO</var> specification, the records in that block are included in the report analysis.
Consequently, some records that are later than the <var>TO</var> setting may be included.

The <var>TO</var> parameter options are:
<table>
<tr><th>yyddd</th>
<td>Indicates the date, in Julian format, where the <var>TO</var> century is such that the end of the time period is within 40 years of the start date of the journal.

The analysis ends with the last journal record in the last journal block on or before the indicated day.</td></tr>

<tr><th>time</th>
<td>Indicates the 24-hour time in the hh:mm[:ss] format; ss defaults to 59.

The analysis ends with the last journal record in the last journal block on or before the indicated time of the starting day of analysis.
If the <code>time</code> value is less than the starting time of analysis, the analysis ends with the last journal record in the last journal block on or before the indicated time of the day after the starting day of analysis. 

The starting date and time of analysis is specified by the <var>FROM</var> parameter, if present, and otherwise is the date and time at the start of the journal.</td></tr>

<tr><th nowrap>yyddd time</th>
<td>Indicates the date, in Julian format, where the <var>TO</var> century is such that the end of the time period is within 40 years of the start date of the journal, and the 24-hour time in the format hh:mm[:ss]; ss defaults to 59.

The analysis ends with the last journal record in the last journal block on or before the indicated time of the indicated day.

<blockquote class="note">Note: This format cannot be passed as a command line program parameter under CMS, although it may be used in a SYSIN file record (see [[SirAud#sysin|SYSIN]]).
Under MVS, the format is:
...,PARM=' ... TO=yyddd time ... '

</blockquote></td></tr>
</table>

Also see the [[#from|FROM parameter]], which can be used to specify the start of the date/time range for analysis.
The description there also provides an example of one benefit of date/time range selection with <var class="product">SirAud</var>.

==UTBLRANG parameter==
Syntax:
UTBLRANG = n 

This parameter is used to specify the number of standard deviations a server table
highwater mark for an individual procedure is allowed to vary from the
mean for the subsystem before the procedure is flagged for [[SirAud report contents#UTBLREPT|UTBLREPT]].

The default is 2.

==UTBLRP and NOUTBLRP parameters==
The <var>UTBLRP</var> and <var>NOUTBLRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>UTBLRP</var>) or suppressing (<var>NOUTBLRP</var>) the [[SirAud report contents#UTBLREPT|UTBLREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other
report selection parameters.

==UTBLSM and NOUTBLSM parameters==
The <var>UTBLSM</var> and <var>NOUTBLSM</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>UTBLSM</var>) or suppressing (<var>NOUTBLSM</var>) the [[SirAud report contents#UTBLSUMM|UTBLSUMM]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other
report selection parameters.

You can change some of the <var class="product">SirAud</var> defaults by applying zaps any time after you have installed the load module.
This page contains the customizations you can perform.

==SirAud default customization==

===ALLPR parameter customization===
Apply the following zap to make the <var>[[SirAud parameters#allpr|ALLPR]]</var> parameter the default:
NAME SIRAUD JCUST
VER 08 00
REP 08 80 ALLPR is default



==See also==
{{Template:SirAud topic list}}

[[Category:SirAud]]

SirAud parameters

2022-02-24T15:59:40Z

Tom:

<var class="product">SirAud</var> has a set of parameters you can use to restrict the size of some
reports or otherwise configure the <var class="product">SirAud</var> run.
These parameters must be provided in either of these ways:
<ul>
<li>As a PARM on the EXEC card in MVS, for example:
<nowiki>//SIRAUD EXEC PGM=SIRAUD,PARM='NSUBS=10 ALLPR'
</nowiki>

<li>As options on the M204CMS command in CMS, for example:
<nowiki>M204CMS SIRAUD ( NSUBS 10 ALLPR %
</nowiki>
</ul>

Under MVS, parameters are specified either by a parameter name alone or
by a parameter name followed by an equal sign (<tt>=</tt>) followed by the parameter value.
Under CMS, parameters are specified by a parameter name followed
by a space and a percent sign (<tt>%</tt>), or by a parameter name followed by a space and a parameter value.

This page describes the parameter settings that are available for <var class="product">SirAud</var>.
Note: You can change the default setting for some of the parameters; see [[#SirAud default customization|SirAud default customization]], below. 

==ALLPR and NOPR==
These are two of the report selection parameters.
The report selection parameters determine which reports are produced.
They also direct all of the report output of <var class="product">SirAud</var> to be written to the SYSPRINT output file, rather than
having each of <var class="product">SirAud</var>'s reports written to a separate output file.
If any report selection parameter is specified, all of the <var class="product">SirAud</var> report output is written to SYSPRINT, and only to there.

The report selection parameters are <var>ALLPR</var>, <var>NOPR</var>, and the following:
<ul>
<li><var>FILERP</var> and <var>NOFILERP</var>
<li><var>PERFRP</var> and <var>NOPERFRP</var>
<li><var>PROCRP</var> and <var>NOPROCRP</var>
<li><var>SUBRP</var> and <var>NOSUBRP</var>
<li><var>UTBLRP</var> and <var>NOUTBLRP</var>
<li><var>UTBLSM</var> and <var>NOUTBLSM</var>
</ul>
Any of the above individual report parameters beginning with <code>NO</code> is called the "negative" form of
the parameter, and it indicates that the given report should not be produced
The form without <code>NO</code> is called the "positive" form, and it indicates the given report should be produced.

<var>ALLPR</var> is a shorthand for a list of all of the positive forms of the
individual report parameters.
<var>NOPR</var> is a shorthand for a list of all of the negative forms of the
individual report parameters.

The effect of the report selection parameters is cumulative, and the specification of any of them can override the effect of a preceding specification.
If the first report selection parameter specified is a positive individual
report parameter, an implicit <code>NOPR</code> precedes that.
If the first report selection parameter specified is a negative individual
report parameter, an implicit <code>ALLPR</code> precedes that.

Thus, for example, the following produces all reports except PERFREPT and FILEREPT:
PARM=(NOPERFRP,NOFILERP)


The following produces only the UTBLSUMM and SUBREPT reports:
PARM=(UTBLSM,SUBRP)


And the following produces all reports except PROCREPT (the <code>UTBLRP</code> in this example is superfluous):
PARM=(NOPROCRP,UTBLRP)


You may customize your <var class="product">SirAud</var> load module so that <var>ALLPR</var> is the default; see
[[SirAud parameters#cszallp|ALLPR parameter customization]].

==FROM parameter==
This parameter is used to restrict the analysis of the journal
to those journal blocks that contain records that
are at or after the indicated date and time.
If the time on the journal block's trailer is greater than or equal to
the <var>FROM</var> specification, the records in that block are included in the
report analysis.
Consequently, some records that are earlier than the <var>FROM</var> setting may be included.

The <var>FROM</var> syntax is:
FROM = yyddd | time | yyddd time 

The <var>FROM</var> parameter options are:
<table>
<tr><th>yyddd</th>
<td>Indicates the date, in Julian format, where the <var>FROM</var> century is such that the start of the time period is within 40 years of the start date of the journal.

The analysis starts at the first journal record in the first journal block on or after the indicated day.</td></tr>

<tr><th>time</th>
<td>Indicates the 24-hour time in the format hh:mm[:ss]; ss defaults to 00.

The analysis starts at the first journal record in the first journal block on or after the indicated time of the first day of the journal.
If the <var class="term">time</var> value is less than the time of the first journal block, the analysis starts at the first journal record in the first journal block on or after the indicated time of the day after the first day of the journal.</td></tr>

<tr><th nowrap>yyddd time</th>
<td>Indicates the date, in Julian format, where the <var>FROM</var> century is such that the start of the time period is within 40 years of the start date of the journal, and the 24-hour time in the format hh:mm[:ss] (where ss defaults to 00).

The analysis starts at the first journal record in the first journal block on or after the indicated time of the indicated day.
<blockquote class="note">Note: This format cannot be passed as a command line program parameter under CMS, although it may be used in a SYSIN file record (see [[SirAud#sysin|SYSIN]]). Under MVS, the format is:
...,PARM=' ... FROM=yyddd time ... '

</blockquote></td></tr>
</table>

Also see the [[#toparm|TO parameter]], which can be used to specify the end of the date/time range for analysis.

Regardless of any date range restriction specified by <var>FROM</var> or
<var>TO</var>, <var class="product">SirAud</var> examines the beginning part of the journal, through the following message:
<code>M204.0075: INITIALIZATION COMPLETED. BUFFERS = n</code>.
The histogram of journal record types will include totals from this
initialization section of the journal as well as from the date range
selected for analysis.

A date range can be useful to provide a reference for interpreting
other measures of <var class="product">Model 204</var> activity.
For example, <var class="product">[[SirTune]]</var> can show ratios for running procedure A versus other procedures:
Assume that a <var class="product">SirTune</var> report over some busy time period shows procedure A using 11% of the CPU in
that period, and then you change the procedure.
After the changes, <var class="product">SirTune</var> on a new busy period might show procedure A CPU goes up to 12%.
One way to check the effectiveness of your changes is to use
<var class="product">SirAud</var> [[SirAud report contents#PROCREPT|PROCREPT]] reports with date/time ranges to see if this increase in CPU correlates to an increased number of invocations between the two busy times.

==FILERP and NOFILERP==
The <var>FILERP</var> and <var>NOFILERP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>FILERP</var>) or suppressing (<var>NOFILERP</var>) the [[SirAud report contents#FILEREPT|FILEREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==MAXBLK parameter==
Syntax:
MAXBLK = n

This parameter is used to specify the number of journal blocks to process.

==NAMEOFF parameter==
Syntax:
NAMEOFF = n 

This can be used, under the direction of Technical Support,
to facilitate running <var class="product">SirAud</var> with newer releases of <var class="product">Model 204</var>,
compensating for changes in the journal format.

==NCP parameter==
Syntax:
NCP = 1-255 

This parameter sets the number of channel programs to use for the input journal.
A higher value can improve I/O performance. If this parameter not specified, the value specified in the JOURNAL DD statement is used, otherwise the default of 22 is used.

==NFILES parameter==
Syntax:
NFILES = n 

This parameter is used to restrict the number of files summarized in [[SirAud report contents#FILEREPT|FILEREPT]]
to the top <var class="term">n</var> files by total disk I/O.

==NPROCS parameter==
Syntax:
NPROCS = n 

This parameter is used to restrict the number of procedures summarized in
[[SirAud report contents#PROCREPT|PROCREPT]] to the top <var class="term">n</var> procedures by total CPU.

==NSUBS parameter==
Syntax:
NSUBS = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#SUBREPT|SUBREPT]] to the top <var class="term">n</var> subsystems by total CPU.

==NUTBLS parameter==
Syntax:
NUTBLS = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#UTBLREPT|UTBLREPT]] to the top <var class="term">n</var> subsystems by server size.

==NUSUMM parameter==
Syntax:
NUSUMM = n 

This parameter is used to restrict the number of subsystems summarized in
[[SirAud report contents#UTBLSUMM|UTBLSUMM]] to the top <var class="term">n</var> subsystems by server size.

==PERFRP and NOPERFRP parameters==
The <var>PERFRP</var> and <var>NOPERFRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>PERFRP</var>) or suppressing (<var>NOPERFRP</var>) the [[SirAud report contents#PERFREPT|PERFREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==PROCRP and NOPROCRP parameters==
The <var>PROCRP</var> and <var>NOPROCRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>PROCRP</var>) or suppressing (<var>NOPROCRP</var>) the [[SirAud report contents#PROCREPT|PROCREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==SKIPBLK parameter==
Syntax:
SKIPBLK = n 

This parameter is used to specify a number of journal blocks to skip.

==SUBRP and NOSUBRP parameters==
The <var>SUBRP</var> and <var>NOSUBRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>SUBRP</var>) or suppressing (<var>NOSUBRP</var>) the [[SirAud report contents#SUBREPT|SUBREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other report selection parameters.

==TO parameter==
Syntax:
TO = yyddd | time | yyddd time 

This parameter is used to restrict the analysis of the journal
to those journal blocks that contain records that are at the indicated date and time.
If the time on the journal block's header is less than or equal to the <var>TO</var> specification, the records in that block are included in the report analysis.
Consequently, some records that are later than the <var>TO</var> setting may be included.

The <var>TO</var> parameter options are:
<table>
<tr><th>yyddd</th>
<td>Indicates the date, in Julian format, where the <var>TO</var> century is such that the end of the time period is within 40 years of the start date of the journal.

The analysis ends with the last journal record in the last journal block on or before the indicated day.</td></tr>

<tr><th>time</th>
<td>Indicates the 24-hour time in the hh:mm[:ss] format; ss defaults to 59.

The analysis ends with the last journal record in the last journal block on or before the indicated time of the starting day of analysis.
If the <code>time</code> value is less than the starting time of analysis, the analysis ends with the last journal record in the last journal block on or before the indicated time of the day after the starting day of analysis. 

The starting date and time of analysis is specified by the <var>FROM</var> parameter, if present, and otherwise is the date and time at the start of the journal.</td></tr>

<tr><th nowrap>yyddd time</th>
<td>Indicates the date, in Julian format, where the <var>TO</var> century is such that the end of the time period is within 40 years of the start date of the journal, and the 24-hour time in the format hh:mm[:ss]; ss defaults to 59.

The analysis ends with the last journal record in the last journal block on or before the indicated time of the indicated day.

<blockquote class="note">Note: This format cannot be passed as a command line program parameter under CMS, although it may be used in a SYSIN file record (see [[SirAud#sysin|SYSIN]]).
Under MVS, the format is:
...,PARM=' ... TO=yyddd time ... '

</blockquote></td></tr>
</table>

Also see the [[#from|FROM parameter]], which can be used to specify the start of the date/time range for analysis.
The description there also provides an example of one benefit of date/time range selection with <var class="product">SirAud</var>.

==UTBLRANG parameter==
Syntax:
UTBLRANG = n 

This parameter is used to specify the number of standard deviations a server table
highwater mark for an individual procedure is allowed to vary from the
mean for the subsystem before the procedure is flagged for [[SirAud report contents#UTBLREPT|UTBLREPT]].

The default is 2.

==UTBLRP and NOUTBLRP parameters==
The <var>UTBLRP</var> and <var>NOUTBLRP</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>UTBLRP</var>) or suppressing (<var>NOUTBLRP</var>) the [[SirAud report contents#UTBLREPT|UTBLREPT]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other
report selection parameters.

==UTBLSM and NOUTBLSM parameters==
The <var>UTBLSM</var> and <var>NOUTBLSM</var> parameters have two effects:
<ul>
<li>Forcing all report output to the SYSPRINT file
<li>Producing (<var>UTBLSM</var>) or suppressing (<var>NOUTBLSM</var>) the [[SirAud report contents#UTBLSUMM|UTBLSUMM]] report.
</ul>

See [[#allpr|ALLPR and NOPR]] for a discussion of these and the other
report selection parameters.

You can change some of the <var class="product">SirAud</var> defaults by applying zaps any time after you have installed the load module.
This page contains the customizations you can perform.

==SirAud default customization==

===ALLPR parameter customization===
Apply the following zap to make the <var>[[SirAud parameters#allpr|ALLPR]]</var> parameter the default:
NAME SIRAUD JCUST
VER 08 00
REP 08 80 ALLPR is default



==See also==
{{Template:SirAud topic list}}

[[Category:SirAud]]

AUD039 NCP value must be from 1-255

2022-02-24T15:34:58Z

Tom: Created page with "An invalid NCP value was specified in the EXEC statement parameters. A higher value can improve I/O performance on the input JOURNAL. If no value is specified in the PARM= par..."

An invalid NCP value was specified in the EXEC statement parameters. A higher value can improve I/O performance on the input JOURNAL. If no value is specified in the PARM= parameter, the value specified in the JOURNAL DD statement is used, otherwise a default of 22 is used.

[[Category:SirAud messages]]

AUD038 (message text)

2022-02-24T15:13:52Z

Tom: Created page with "This informational message displays the message text from a Model 204 journal entry indicating a journal stream switch occurred during the run. Category:SirAud messages"

This informational message displays the message text from a Model 204 journal entry indicating a journal stream switch occurred during the run.

[[Category:SirAud messages]]

AUD037 Using header to determine version = (version) jobname = (jobname) JESID = (jesid) SMFid = (smfid)

2022-02-24T15:11:27Z

Tom: Created page with "This informational message displays the Model 204 version and operating system information from the initialization record in the journal being processed. Category:SirAud m..."

This informational message displays the Model 204 version and operating system information from the initialization record in the journal being processed.

[[Category:SirAud messages]]

AUD036 Assuming Version = (version)

2022-02-24T15:04:43Z

Tom: Created page with "This informational message indicates that SirAud could not determine the release Model 204 from the initialization record in the journal and assumes it is generated by the ver..."

This informational message indicates that SirAud could not determine the release Model 204 from the initialization record in the journal and assumes it is generated by the version shown in the message.

[[Category:SirAud messages]]

AUD035 (date/time) (error text)

2022-02-24T14:59:12Z

Tom: Created page with "This informational message shows the Model 204 error text written to the journal after a snap was taken. This message usually follows an AUD034 message. Category:SirAud mes..."

This informational message shows the Model 204 error text written to the journal after a snap was taken. This message usually follows an AUD034 message.

[[Category:SirAud messages]]

AUD034 (date/time) SNAPID = 1 was begun for user (user number)

2022-02-24T14:44:43Z

Tom: Created page with "This informational message indicates that a Model 204 snap was taken for the specified user during the run being analyzed by SirAud. Category:SirAud messages"

This informational message indicates that a Model 204 snap was taken for the specified user during the run being analyzed by SirAud.

[[Category:SirAud messages]]

AUD033 (date/time) Termination record with return code (return code)

2022-02-24T14:41:46Z

Tom: Created page with "This is an information messages that shows the Model 204 completion code at the end of the run being analyzed. Category:SirAud messages"

This is an information messages that shows the Model 204 completion code at the end of the run being analyzed.

[[Category:SirAud messages]]

AUD032 JOURNAL contains (types) records

2022-02-24T14:38:52Z

Tom: Created page with "This indicates that the CCAJLOG or CCAJRNL input file contains either recovery records, statistics and message records, or both types of records.This is an informational messa..."

This indicates that the CCAJLOG or CCAJRNL input file contains either recovery records, statistics and message records, or both types of records.This is an informational message.

[[Category:SirAud messages]]

AUD031 (date/time) Initialization record for (m204 version) on system (system ID)

2022-02-24T14:26:48Z

Tom: Created page with "This informational message displays the contents of the CCAJRNL/CCAJLOG initialization record. Category:SirAud messages"

This informational message displays the contents of the CCAJRNL/CCAJLOG initialization record.

[[Category:SirAud messages]]

AUD030 Merged journal produced by MERGEJ from input journal(s)

2022-02-24T14:14:40Z

Tom: Created page with "This indicates that <var class="product">SirAud</var> detected an input journal created by the MERGEJ utility. This is an informational message. Category:SirAud messages"

This indicates that <var class="product">SirAud</var> detected an input journal created by the MERGEJ utility. This is an informational message.

[[Category:SirAud messages]]

RockZap

2022-02-18T20:07:21Z

Tom: /* UPPER */

==Introduction==
<var class="product">RockZap</var> is a load module maintenance facility, similar to z/OS IMASPZAP
or the CMS ZAP command. Prior to version 7.5 of Model 204, <var class="product">RockZap</var> was named <code>SirZap</code>.

<var class="product">RockZap</var> modifies load modules (or for CMS, both
load modules and text libraries) based on
information from control statements supplied by the user.
<var class="product">RockZap</var> is not
a plug compatible replacement for the IBM ZAP utilities, but it provides
functional and performance enhancements for load module maintenance.

<var class="product">RockZap</var> is distributed as part of a software maintenance agreement
between Rocket Software Inc. and its customers.
<var class="product">RockZap</var> is provided for
the purpose of applying maintenance to Rocket Model 204 products, but
you need not limit use of <var class="product">RockZap</var> to those products.

===Versions===
This wiki page
assumes that a site is running <var class="product">RockZap</var> version 1.6 or later.
Any documented feature or facility that requires a later version
of <var class="product">RockZap</var> will be clearly marked to indicate this.
If a feature or parameter is not
indicated as requiring any specific version of <var class="product">RockZap</var>, it can
be assumed that it is available in all versions covered by this
document; that is, versions 1.6 and later of <var class="product">RockZap</var>.

===Messages===
<var class="product">RockZap</var> messages are documented in [[:Category:RockZap messages]].

===Downloading===
<ol>
<li>Using your [[Rocket M204 user ID]] and password, log in to the [https://model204.rocketsoftware.com/maint/objlist Model 204 object file download page].</li>

<li>Click the Download object file link to the right of the RockZap object file.</li>
</ol>

==RockZap features==
RockZap provides the following features:
<ul>
<li><var class="product">RockZap</var> can save significant amounts of elapsed time and CPU for long
ZAP input streams.
This is because <var class="product">RockZap</var> applies all ZAPs in the input
stream before writing a module back to disk.
(IMASPZAP and CMS ZAP both
write parts of the load module back to disk each time a new <var>NAME</var>
statement is encountered, reducing performance significantly.)</li>

<li><var class="product">RockZap</var> detects and reports ZAPs that are already applied.
Using
IMASPZAP or CMS ZAP, the user must inspect long CSECT dumps produced by
the ZAP utility in order to determine if the ZAP is already applied, or
simply in error.</li>

<li><var class="product">RockZap</var> allows the module name on all <var>NAME</var> statements to be overridden using the <var>MODULE</var> option.
This provides the ability to have the same set of <var>VER</var>s and <var>REP</var>s applied to different load modules without making global changes to the <var>NAME</var> statements.
</li>

<li><var class="product">RockZap</var> can "back out" or remove ZAPs without requiring
modification to the ZAP control statements.
By using the BACKOUT
option, ZAPs can be removed from the load module and replaced by the
original Verify data.</li>

<li><var class="product">RockZap</var> limits error reporting to the specific statements in error, and it
reports only the information necessary to diagnose and correct the
error.</li>

<li><var class="product">RockZap</var> only writes modified load modules.
If the ZAPs are already
completely applied, <var class="product">RockZap</var> does not write the load module back to disk.</li>

<li><var class="product">RockZap</var> enforces stricter rules on ZAP input statements.
Verify statements are required for all replaced bytes.
This ensures that the
load module contents are known before they are modified, and that a ZAP
can be removed or "backed out" if necessary.
You can override this feature,
however, using the <var>[[#* !NOVERIFY|* !NOVERIFY]]</var> statement.</li>

<li><var class="product">RockZap</var> 1.7 and later support z/OS datasets with the LARGE attribute.</li>

</ul>

==Differences between RockZap and IMASPZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> only modifies direct access load libraries.
<var class="product">RockZap</var> does not
modify PDSEs or any other types of direct access data sets.</li>

<li>The following SPZAP statements are not supported but are ignored
when encountered in the input stream: SETSSI, IDRDATA, and CHECKSUM.</li>

<li>The following IMASPZAP statments are not supported and will cause
<var class="product">RockZap</var> to terminate when they are encountered:
CONSOLE, ABSDUMP, ABSDUMPT, and RECORD.</li>
</ul>

==Differences between RockZap and CMS ZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> does not support CMS LOADLIBs.</li>

<li>The following ZAP statements are not supported but are ignored
when encountered in the input stream: COMMENT and LOG.</li>
</ul>

==CMS installation==
<var class="product">RockZap</var> is distributed as a single load module in VMFPLC2 format.
A set of object decks is also included in case linkedit is required.
(This might be necessary for some older CMS versions).

[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

The <var class="product">RockZap</var> load module is linked <code>AMODE=31</code>.
If <var class="product">RockZap</var> must be relinked
on your system, use the following commands:
LOAD ROCKZAP (RESET ROCKZAP RMODE 24 AMODE 31
GENMOD ROCKZAP (FROM APPL

Note: You can omit the <var>RMODE</var> and <var>AMODE</var> parameters if you are running in a non-XA environment.


==IBM z/OS installation==
[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

<code>ROCKZAP</code> can be copied to SYS1.LINKLIB or SYS1.LPALIB, and it is reentrant.

<div id="options"></div>
==RockZap options==
z/OS users supply <var class="product">RockZap</var> options in the <code>PARM</code> parameter of the EXEC job control statement.

For example, to force uppercase output and to
backout ZAPs, use the following EXEC statement:
//ROCKZAP EXEC PGM=ROCKZAP,PARM='UPPER,BACKOUT'


CMS users specify options following a left parenthesis on the <var>ROCKZAP</var>
command line.

For example, to force uppercase output and to backout the
ZAPs in the file <code>LOCAL ZAP A1</code>, specify the following:
ROCKZAP LOCAL ( BACKOUT UPPER


===BACKOUT===
The <var>BACKOUT</var> option removes a ZAP without requiring any modification to
the ZAP input statements.
<var>BACKOUT</var> reverses the effect of a ZAP by
replacing the original <code>Verify</code> data in the module.

If the ZAPs were applied with IMASPZAP, CMS ZAP, or with <var class="product">RockZap</var> using the <var>* !NOVERIFY</var> statement, <var class="product">RockZap</var> might not be able to perform a backout because all the original <code>Verify</code> data might not be present.

===EXTRACT filetype===
The <var>EXTRACT</var> option lets you extract individual object files from
a CMS text library.
<var>EXTRACT</var> can only be used when the <var>TXTLIB</var> option is also
specified.

<var>EXTRACT</var> requires a parameter that specifies the file type
of the object files it creates. One object file is created for each
member of the text library. The text library member name is used as the CMS file name.

===MODULE===
The <var>MODULE=modname</var> option allows the module name on each <var>NAME</var> statement to be overridden with a single load-module name. This means that you can use the same <var>ROCKZAP</var> jobstream to apply the same zaps to different load modules in the designated load library (SYSLIB) without making changes to any of the <var>[[#NAME|NAME]]</var> control statements.

For example, <code>PARM='MODULE=ONLINE'</code> applies the zaps to the module named <code>ONLINE</code> in the designated load library, regardless of the load-module name on each <var>NAME</var> statement. Then, using the same job stream, <code>PARM='MODULE=ONLINTST'</code> applies the same zaps to the module named <code>ONLINTST</code>, again, regardless of the load-module name on each <var>NAME</var> statement.

Note: If you are applying zaps to a <var class="product">Model 204</var> load module, you must specify a value for <var>MODULE</var>. 

The <var>MODULE</var> option was introduced in version 1.6 of <var class="product">RockZap</var>.

===REPORT===
Under the <var>REPORT</var> option, <var class="product">RockZap</var> runs normally but does not update any load modules. This is useful if you have a production load module you do not want to modify, but you do want to know whether or not a particular set of ZAPs are applied.

===TXTLIB txtlib===
The <var>TXTLIB</var> option is valid under CMS only.
<var>TXTLIB</var> specifies that the
ZAPs should be applied to a CMS text library instead of a load module.

You must provide the name of the text library following the <var>TXTLIB</var>
parameter.
The first parameter of the name statement (the module name)
is ignored when using the <var>TXTLIB</var> option.
Only the CSECT name is used for text libraries.
No load modules are inspected or modified when the
<var>TXTLIB</var> option is specified.

===UPPER===
The <var>UPPER</var> option forces all <var class="product">RockZap</var> output to upper case.

===MISSING===
The <var>MISSING</var> option suppresses errors resulting from a NAME statement that references a CSECT not present in the load module.
<var>MISSING</var> is the default.

===NOMISSING===
The <var>NOMISSING</var> option flags errors resulting from a NAME statement that references a CSECT not present in the load module. A missing CSECT results in a return code of 4.

==RockZap control statements==
<var class="product">RockZap</var> control statements appear in columns 1 to 72 in fixed length,
80 byte records.
Statements that begin with an asterisk are treated as
comments and are ignored, except for the two special inline parameter statements
<var>* !VERIFY</var> and <var>* !NOVERIFY</var>.
Control statements can begin in any column,
but line continuation is not allowed.

===VER===
The <var>VER</var> statement identifies a range of bytes to be matched with the
load module contents.
<var>VER</var> statements must follow a <var>NAME</var> statement.
A <var>VER</var> statement must be present for each range of bytes that will be
replaced in the load module.
This is to ensure that the ZAP can be backed out later if necessary.

The format of the <var>VER</var> statement is:
VER offset verify-values comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT specified in the previous <var>NAME</var> statement, or from the start of the load module if no CSECT was specified.</td></tr>

<tr><th nowrap>verify-values</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values are the expected contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">verify-values</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>VER</var> statements:
VER 00 010203,040506 Verify bytes at offset 0.

VER 01ca 47f0,c0e9

VER 23EC D20310004000,90ECD000,07FC


===REP===
The <var>REP</var> statement identifies a range of bytes to replace the current
contents of a load module.
The <var>REP</var> statement must be preceded by <var>VER</var>
statements that cover the entire range of bytes that will be replaced.

The format of the <var>REP</var> statement is:
REP offset replace-value comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT in the previous <var>NAME</var> statement.</td></tr>

<tr><th nowrap>replace-value</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values will replace the contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">replace-value</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>REP</var> statements:
REP 00 FFFFFF,FFFFFF Replace bytes at offset 0.

REP 01ca 47f0,c0e8

REP 23EC D203101C4000,90ECD008,07FE


===NAME===
The <var>NAME</var> statement identifies a load module, and optionally a CSECT, that defines the context for the <var>VER</var> and <var>REP</var> statements that follow.
<var>NAMEX</var> is a synonym for <var>NAME</var> that allows compatibility with the Fujitsu
OSIV ZAP utility.

The format of the <var>NAME</var> statement is:
NAME module [csect]

Where:
<table>
<tr><th>module</th>
<td>The name of the load module. Under CMS the filetype must be <var>MODULE</var>. Under z/OS this is the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section in the load module. A <var class="term">csect</var> value is optional. If the CSECT name is missing, subsequent verify and replace displacements are calculated from offset 0 in the load module.</td></tr>
</table>

Note: You can use the <var>[[#MODULE|MODULE]]</var> parameter to override the module name in <var>NAME</var> statements. 

===DUMP or DUMPT===
The <var>DUMP</var> statement prints all or part of the contents of a load
module or CMS text library to SYSPRINT.
Specifying <var>DUMPT</var> has the same effect as <var>DUMP</var>.

The format of the <var>DUMP</var> or <var>DUMPT</var> statement is:
DUMP[T] name [csect [offset [length]]]

Where:
<table>
<tr><th>name</th>
<td>The name of the load module or text library. Under CMS, specify the filename (only) of a file whose filetype must be <var>MODULE</var> or <var>TXTLIB</var>. Under z/OS, specify the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section. A <var class="term">csect</var> value is optional. If the CSECT clause is missing, the entire load module or text library contents are dumped.</td></tr>

<tr><th>offset</th>
<td>The hexadecimal starting offset within the CSECT. This is optional, and it can only be specified when a <var class="term">csect</var> name is specified. Use the <var class="term">offset</var> parameter when you want to dump only a part of a CSECT. If the offset is omitted, it defaults to 0.</td></tr>

<tr><th>length</th>
<td>The number of bytes (in hexadecimal) of the CSECT to dump. This is an optional parameter, and it can only be specified if a <var class="term">csect</var> value and starting <var class="term">offset</var> value are specified.</td></tr>
</table>

===* !VERIFY===
The special statement <var>* !VERIFY</var> (and <var>* !NOVERIFY</var>) lets you control whether individual ZAPs are verified before being applied.

The main purpose of these statements is to override whether the current portion of the zap requires verify data. This can be useful when a single ZAP in an input stream containing many ZAPs has no verify data.

The asterisk and space are necessary so that other ZAP utilities treat
the statements as comments.

Use <var>* !VERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !VERIFY</var> statement are verified (the <var>VER</var> data must match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
 Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use
the <var>* !NOVERIFY</var> statement instead, and only when needed. 

===* !NOVERIFY===
The special inline statement
<var>* !NOVERIFY</var> (and <var>* !VERIFY</var>) lets you control
whether individual ZAPs are verified before being applied.
The main purpose of these statements is to override whether the current
portion of the zap requires verify data.
This can be useful when a single ZAP in an input stream containing many ZAPs has no verify
data or the verify data is known to be incorrect.

Use <var>* !NOVERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !NOVERIFY</var> statement are not verified (the <var>VER</var> data may be missing or not match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use the <var>* !NOVERIFY</var> statement instead, and only when needed. 

==Using RockZap under z/OS==
Job Control requirements for <var class="product">RockZap</var> are the same as for IMASPZAP. Most <var class="product">RockZap</var> storage is allocated above the 16 megabyte line, so the default region size should be sufficient.

===RockZap DD statements===
Required statements:
<ul>
<li>SYSLIB points to the load library PDS (Partitioned Data
Set) containing the load module you want to ZAP. The load library cannot be a PDSE (Partition Data Set Extended) dataset.</li>

<li>SYSIN contains the ZAP control statements and must
have the DCB attributes of <code>RECFM=F</code> or <code>RECFM=FB</code>, and <code>LRECL=80</code>.</li>

<li>SYSPRINT is the report data set.</li>
</ul>

===RockZap sample JCL===
//ROCKZAP JOB CLASS=A,MSGCLASS=A
//ZAP EXEC PGM=ROCKZAP,PARM='RockZap parms'
//STEPLIB DD DSN=ROCKZAP.V106.LOAD,DISP=SHR
//SYSLIB DD DSN=loadlib,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
zap control statements
/*


==Using RockZap under CMS==
The format of the <var>ROCKZAP</var> command is:
ROCKZAP fn [ft [fm]] ( options


<var class="product">RockZap</var> is invoked as a CMS command.
Simply enter <code>ROCKZAP</code> followed by the
name of the input file.
The default filetype is <code>ZAP</code>, and the
default filemode is <code>*</code>.

Options are supplied in any order following the left parenthesis.
See [[#options|RockZap options]] for a list of options.

<var class="product">RockZap</var> writes the report and any modified load modules to the disk
accessed as the "A" disk.
Make sure that the "A" disk is accessed in Read/Write mode.

===Using RockZap with CMS text libraries===
When <var class="product">RockZap</var> processes a text library, the resulting text library or object files usually contain fewer records than the original.
No information is lost and the
resulting text library or object file is logically the same as the original.
Text records in the object file are always written with the maximum amount of object code
per record. Often, fewer records are required than are typically written by the
compiler or assembler that originally generated the object.

This object file "normalization" is similar to how a linkage editor processes an object
file.
<var class="product">RockZap</var> performs this normalization so that ZAPs can be applied more efficiently.

==RockZap return codes==
<table class="thJustBold">
<tr><th>0</th>
<td>ZAPs were processed successfully. Any modified load modules are written back to disk.</td></tr>

<tr><th>4</th>
<td>ZAPs were processed successfully, but one or more warning messages were produced. This usually indicates a CSECT was missing from one or more of the load modules. Check the <var class="product">RockZap</var> report for the name of the module and CSECT. If any load modules were modified, they are written back to disk.</td></tr>

<tr><th>8</th>
<td>One or more errors occurred. Check the <var class="product">RockZap</var> report for details.</td></tr>

<tr><th>12</th>
<td><var class="product">RockZap</var> was unable to open the input file. Make sure the filename is correct and that the file or PDS member is present.</td></tr>

<tr><th>40</th>
<td><var class="product">RockZap</var> could not open the report file (SYSPRINT). For z/OS, make sure a DD statement for SYSPRINT is present. For CMS, the internal FILEDEF for SYSPRINT may have failed. Make sure the "A" disk is accessed in read/write mode.</td></tr>
</table>

==Deprecated options==
The following program options are no longer necessary.
It is recommended
that you not use them, and that if you discover them in old JCL or EXECs,
you correct them to use the newer recommended approaches.

===NOVERIFY===
The <var>NOVERIFY</var> option lets you apply ZAPs that have no verify data.
Use the <var>NOVERIFY</var> option with caution.
Once a ZAP is applied using <var>NOVERIFY</var>,
the original contents of the load module are lost.

Note: Since the <var>* !NOVERIFY</var> statement can provide the functionality needed for applying a portion of a zap without verify data, it is strongly recommended that you not use the <var>NOVERIFY</var> option, which might extend to other portions of the zap with incorrect verify data.


===VERIFY===
The <var>VERIFY</var> option ensures that all replace data has been successfully
verified before updating the load module.
<var>VERIFY</var> is a <var class="product">RockZap</var> default, and it need not be specified.

Note: Since it is recommended that you do not use the <var>NOVERIFY</var> option, you might want to avoid the <var>VERIFY</var> option as well, thus eliminating any tendency to control requirement of verify data at the job step level.


[[Category:RKTools]]

RockZap

2022-02-18T20:07:07Z

Tom: /* UPPER */

==Introduction==
<var class="product">RockZap</var> is a load module maintenance facility, similar to z/OS IMASPZAP
or the CMS ZAP command. Prior to version 7.5 of Model 204, <var class="product">RockZap</var> was named <code>SirZap</code>.

<var class="product">RockZap</var> modifies load modules (or for CMS, both
load modules and text libraries) based on
information from control statements supplied by the user.
<var class="product">RockZap</var> is not
a plug compatible replacement for the IBM ZAP utilities, but it provides
functional and performance enhancements for load module maintenance.

<var class="product">RockZap</var> is distributed as part of a software maintenance agreement
between Rocket Software Inc. and its customers.
<var class="product">RockZap</var> is provided for
the purpose of applying maintenance to Rocket Model 204 products, but
you need not limit use of <var class="product">RockZap</var> to those products.

===Versions===
This wiki page
assumes that a site is running <var class="product">RockZap</var> version 1.6 or later.
Any documented feature or facility that requires a later version
of <var class="product">RockZap</var> will be clearly marked to indicate this.
If a feature or parameter is not
indicated as requiring any specific version of <var class="product">RockZap</var>, it can
be assumed that it is available in all versions covered by this
document; that is, versions 1.6 and later of <var class="product">RockZap</var>.

===Messages===
<var class="product">RockZap</var> messages are documented in [[:Category:RockZap messages]].

===Downloading===
<ol>
<li>Using your [[Rocket M204 user ID]] and password, log in to the [https://model204.rocketsoftware.com/maint/objlist Model 204 object file download page].</li>

<li>Click the Download object file link to the right of the RockZap object file.</li>
</ol>

==RockZap features==
RockZap provides the following features:
<ul>
<li><var class="product">RockZap</var> can save significant amounts of elapsed time and CPU for long
ZAP input streams.
This is because <var class="product">RockZap</var> applies all ZAPs in the input
stream before writing a module back to disk.
(IMASPZAP and CMS ZAP both
write parts of the load module back to disk each time a new <var>NAME</var>
statement is encountered, reducing performance significantly.)</li>

<li><var class="product">RockZap</var> detects and reports ZAPs that are already applied.
Using
IMASPZAP or CMS ZAP, the user must inspect long CSECT dumps produced by
the ZAP utility in order to determine if the ZAP is already applied, or
simply in error.</li>

<li><var class="product">RockZap</var> allows the module name on all <var>NAME</var> statements to be overridden using the <var>MODULE</var> option.
This provides the ability to have the same set of <var>VER</var>s and <var>REP</var>s applied to different load modules without making global changes to the <var>NAME</var> statements.
</li>

<li><var class="product">RockZap</var> can "back out" or remove ZAPs without requiring
modification to the ZAP control statements.
By using the BACKOUT
option, ZAPs can be removed from the load module and replaced by the
original Verify data.</li>

<li><var class="product">RockZap</var> limits error reporting to the specific statements in error, and it
reports only the information necessary to diagnose and correct the
error.</li>

<li><var class="product">RockZap</var> only writes modified load modules.
If the ZAPs are already
completely applied, <var class="product">RockZap</var> does not write the load module back to disk.</li>

<li><var class="product">RockZap</var> enforces stricter rules on ZAP input statements.
Verify statements are required for all replaced bytes.
This ensures that the
load module contents are known before they are modified, and that a ZAP
can be removed or "backed out" if necessary.
You can override this feature,
however, using the <var>[[#* !NOVERIFY|* !NOVERIFY]]</var> statement.</li>

<li><var class="product">RockZap</var> 1.7 and later support z/OS datasets with the LARGE attribute.</li>

</ul>

==Differences between RockZap and IMASPZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> only modifies direct access load libraries.
<var class="product">RockZap</var> does not
modify PDSEs or any other types of direct access data sets.</li>

<li>The following SPZAP statements are not supported but are ignored
when encountered in the input stream: SETSSI, IDRDATA, and CHECKSUM.</li>

<li>The following IMASPZAP statments are not supported and will cause
<var class="product">RockZap</var> to terminate when they are encountered:
CONSOLE, ABSDUMP, ABSDUMPT, and RECORD.</li>
</ul>

==Differences between RockZap and CMS ZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> does not support CMS LOADLIBs.</li>

<li>The following ZAP statements are not supported but are ignored
when encountered in the input stream: COMMENT and LOG.</li>
</ul>

==CMS installation==
<var class="product">RockZap</var> is distributed as a single load module in VMFPLC2 format.
A set of object decks is also included in case linkedit is required.
(This might be necessary for some older CMS versions).

[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

The <var class="product">RockZap</var> load module is linked <code>AMODE=31</code>.
If <var class="product">RockZap</var> must be relinked
on your system, use the following commands:
LOAD ROCKZAP (RESET ROCKZAP RMODE 24 AMODE 31
GENMOD ROCKZAP (FROM APPL

Note: You can omit the <var>RMODE</var> and <var>AMODE</var> parameters if you are running in a non-XA environment.


==IBM z/OS installation==
[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

<code>ROCKZAP</code> can be copied to SYS1.LINKLIB or SYS1.LPALIB, and it is reentrant.

<div id="options"></div>
==RockZap options==
z/OS users supply <var class="product">RockZap</var> options in the <code>PARM</code> parameter of the EXEC job control statement.

For example, to force uppercase output and to
backout ZAPs, use the following EXEC statement:
//ROCKZAP EXEC PGM=ROCKZAP,PARM='UPPER,BACKOUT'


CMS users specify options following a left parenthesis on the <var>ROCKZAP</var>
command line.

For example, to force uppercase output and to backout the
ZAPs in the file <code>LOCAL ZAP A1</code>, specify the following:
ROCKZAP LOCAL ( BACKOUT UPPER


===BACKOUT===
The <var>BACKOUT</var> option removes a ZAP without requiring any modification to
the ZAP input statements.
<var>BACKOUT</var> reverses the effect of a ZAP by
replacing the original <code>Verify</code> data in the module.

If the ZAPs were applied with IMASPZAP, CMS ZAP, or with <var class="product">RockZap</var> using the <var>* !NOVERIFY</var> statement, <var class="product">RockZap</var> might not be able to perform a backout because all the original <code>Verify</code> data might not be present.

===EXTRACT filetype===
The <var>EXTRACT</var> option lets you extract individual object files from
a CMS text library.
<var>EXTRACT</var> can only be used when the <var>TXTLIB</var> option is also
specified.

<var>EXTRACT</var> requires a parameter that specifies the file type
of the object files it creates. One object file is created for each
member of the text library. The text library member name is used as the CMS file name.

===MODULE===
The <var>MODULE=modname</var> option allows the module name on each <var>NAME</var> statement to be overridden with a single load-module name. This means that you can use the same <var>ROCKZAP</var> jobstream to apply the same zaps to different load modules in the designated load library (SYSLIB) without making changes to any of the <var>[[#NAME|NAME]]</var> control statements.

For example, <code>PARM='MODULE=ONLINE'</code> applies the zaps to the module named <code>ONLINE</code> in the designated load library, regardless of the load-module name on each <var>NAME</var> statement. Then, using the same job stream, <code>PARM='MODULE=ONLINTST'</code> applies the same zaps to the module named <code>ONLINTST</code>, again, regardless of the load-module name on each <var>NAME</var> statement.

Note: If you are applying zaps to a <var class="product">Model 204</var> load module, you must specify a value for <var>MODULE</var>. 

The <var>MODULE</var> option was introduced in version 1.6 of <var class="product">RockZap</var>.

===REPORT===
Under the <var>REPORT</var> option, <var class="product">RockZap</var> runs normally but does not update any load modules. This is useful if you have a production load module you do not want to modify, but you do want to know whether or not a particular set of ZAPs are applied.

===TXTLIB txtlib===
The <var>TXTLIB</var> option is valid under CMS only.
<var>TXTLIB</var> specifies that the
ZAPs should be applied to a CMS text library instead of a load module.

You must provide the name of the text library following the <var>TXTLIB</var>
parameter.
The first parameter of the name statement (the module name)
is ignored when using the <var>TXTLIB</var> option.
Only the CSECT name is used for text libraries.
No load modules are inspected or modified when the
<var>TXTLIB</var> option is specified.

===UPPER===
The <var>UPPER</var> option forces all <var class="product">RockZap</var> output to

===MISSING===
The <var>MISSING</var> option suppresses errors resulting from a NAME statement that references a CSECT not present in the load module.
<var>MISSING</var> is the default.

===NOMISSING===
The <var>NOMISSING</var> option flags errors resulting from a NAME statement that references a CSECT not present in the load module. A missing CSECT results in a return code of 4.

==RockZap control statements==
<var class="product">RockZap</var> control statements appear in columns 1 to 72 in fixed length,
80 byte records.
Statements that begin with an asterisk are treated as
comments and are ignored, except for the two special inline parameter statements
<var>* !VERIFY</var> and <var>* !NOVERIFY</var>.
Control statements can begin in any column,
but line continuation is not allowed.

===VER===
The <var>VER</var> statement identifies a range of bytes to be matched with the
load module contents.
<var>VER</var> statements must follow a <var>NAME</var> statement.
A <var>VER</var> statement must be present for each range of bytes that will be
replaced in the load module.
This is to ensure that the ZAP can be backed out later if necessary.

The format of the <var>VER</var> statement is:
VER offset verify-values comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT specified in the previous <var>NAME</var> statement, or from the start of the load module if no CSECT was specified.</td></tr>

<tr><th nowrap>verify-values</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values are the expected contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">verify-values</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>VER</var> statements:
VER 00 010203,040506 Verify bytes at offset 0.

VER 01ca 47f0,c0e9

VER 23EC D20310004000,90ECD000,07FC


===REP===
The <var>REP</var> statement identifies a range of bytes to replace the current
contents of a load module.
The <var>REP</var> statement must be preceded by <var>VER</var>
statements that cover the entire range of bytes that will be replaced.

The format of the <var>REP</var> statement is:
REP offset replace-value comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT in the previous <var>NAME</var> statement.</td></tr>

<tr><th nowrap>replace-value</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values will replace the contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">replace-value</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>REP</var> statements:
REP 00 FFFFFF,FFFFFF Replace bytes at offset 0.

REP 01ca 47f0,c0e8

REP 23EC D203101C4000,90ECD008,07FE


===NAME===
The <var>NAME</var> statement identifies a load module, and optionally a CSECT, that defines the context for the <var>VER</var> and <var>REP</var> statements that follow.
<var>NAMEX</var> is a synonym for <var>NAME</var> that allows compatibility with the Fujitsu
OSIV ZAP utility.

The format of the <var>NAME</var> statement is:
NAME module [csect]

Where:
<table>
<tr><th>module</th>
<td>The name of the load module. Under CMS the filetype must be <var>MODULE</var>. Under z/OS this is the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section in the load module. A <var class="term">csect</var> value is optional. If the CSECT name is missing, subsequent verify and replace displacements are calculated from offset 0 in the load module.</td></tr>
</table>

Note: You can use the <var>[[#MODULE|MODULE]]</var> parameter to override the module name in <var>NAME</var> statements. 

===DUMP or DUMPT===
The <var>DUMP</var> statement prints all or part of the contents of a load
module or CMS text library to SYSPRINT.
Specifying <var>DUMPT</var> has the same effect as <var>DUMP</var>.

The format of the <var>DUMP</var> or <var>DUMPT</var> statement is:
DUMP[T] name [csect [offset [length]]]

Where:
<table>
<tr><th>name</th>
<td>The name of the load module or text library. Under CMS, specify the filename (only) of a file whose filetype must be <var>MODULE</var> or <var>TXTLIB</var>. Under z/OS, specify the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section. A <var class="term">csect</var> value is optional. If the CSECT clause is missing, the entire load module or text library contents are dumped.</td></tr>

<tr><th>offset</th>
<td>The hexadecimal starting offset within the CSECT. This is optional, and it can only be specified when a <var class="term">csect</var> name is specified. Use the <var class="term">offset</var> parameter when you want to dump only a part of a CSECT. If the offset is omitted, it defaults to 0.</td></tr>

<tr><th>length</th>
<td>The number of bytes (in hexadecimal) of the CSECT to dump. This is an optional parameter, and it can only be specified if a <var class="term">csect</var> value and starting <var class="term">offset</var> value are specified.</td></tr>
</table>

===* !VERIFY===
The special statement <var>* !VERIFY</var> (and <var>* !NOVERIFY</var>) lets you control whether individual ZAPs are verified before being applied.

The main purpose of these statements is to override whether the current portion of the zap requires verify data. This can be useful when a single ZAP in an input stream containing many ZAPs has no verify data.

The asterisk and space are necessary so that other ZAP utilities treat
the statements as comments.

Use <var>* !VERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !VERIFY</var> statement are verified (the <var>VER</var> data must match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
 Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use
the <var>* !NOVERIFY</var> statement instead, and only when needed. 

===* !NOVERIFY===
The special inline statement
<var>* !NOVERIFY</var> (and <var>* !VERIFY</var>) lets you control
whether individual ZAPs are verified before being applied.
The main purpose of these statements is to override whether the current
portion of the zap requires verify data.
This can be useful when a single ZAP in an input stream containing many ZAPs has no verify
data or the verify data is known to be incorrect.

Use <var>* !NOVERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !NOVERIFY</var> statement are not verified (the <var>VER</var> data may be missing or not match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use the <var>* !NOVERIFY</var> statement instead, and only when needed. 

==Using RockZap under z/OS==
Job Control requirements for <var class="product">RockZap</var> are the same as for IMASPZAP. Most <var class="product">RockZap</var> storage is allocated above the 16 megabyte line, so the default region size should be sufficient.

===RockZap DD statements===
Required statements:
<ul>
<li>SYSLIB points to the load library PDS (Partitioned Data
Set) containing the load module you want to ZAP. The load library cannot be a PDSE (Partition Data Set Extended) dataset.</li>

<li>SYSIN contains the ZAP control statements and must
have the DCB attributes of <code>RECFM=F</code> or <code>RECFM=FB</code>, and <code>LRECL=80</code>.</li>

<li>SYSPRINT is the report data set.</li>
</ul>

===RockZap sample JCL===
//ROCKZAP JOB CLASS=A,MSGCLASS=A
//ZAP EXEC PGM=ROCKZAP,PARM='RockZap parms'
//STEPLIB DD DSN=ROCKZAP.V106.LOAD,DISP=SHR
//SYSLIB DD DSN=loadlib,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
zap control statements
/*


==Using RockZap under CMS==
The format of the <var>ROCKZAP</var> command is:
ROCKZAP fn [ft [fm]] ( options


<var class="product">RockZap</var> is invoked as a CMS command.
Simply enter <code>ROCKZAP</code> followed by the
name of the input file.
The default filetype is <code>ZAP</code>, and the
default filemode is <code>*</code>.

Options are supplied in any order following the left parenthesis.
See [[#options|RockZap options]] for a list of options.

<var class="product">RockZap</var> writes the report and any modified load modules to the disk
accessed as the "A" disk.
Make sure that the "A" disk is accessed in Read/Write mode.

===Using RockZap with CMS text libraries===
When <var class="product">RockZap</var> processes a text library, the resulting text library or object files usually contain fewer records than the original.
No information is lost and the
resulting text library or object file is logically the same as the original.
Text records in the object file are always written with the maximum amount of object code
per record. Often, fewer records are required than are typically written by the
compiler or assembler that originally generated the object.

This object file "normalization" is similar to how a linkage editor processes an object
file.
<var class="product">RockZap</var> performs this normalization so that ZAPs can be applied more efficiently.

==RockZap return codes==
<table class="thJustBold">
<tr><th>0</th>
<td>ZAPs were processed successfully. Any modified load modules are written back to disk.</td></tr>

<tr><th>4</th>
<td>ZAPs were processed successfully, but one or more warning messages were produced. This usually indicates a CSECT was missing from one or more of the load modules. Check the <var class="product">RockZap</var> report for the name of the module and CSECT. If any load modules were modified, they are written back to disk.</td></tr>

<tr><th>8</th>
<td>One or more errors occurred. Check the <var class="product">RockZap</var> report for details.</td></tr>

<tr><th>12</th>
<td><var class="product">RockZap</var> was unable to open the input file. Make sure the filename is correct and that the file or PDS member is present.</td></tr>

<tr><th>40</th>
<td><var class="product">RockZap</var> could not open the report file (SYSPRINT). For z/OS, make sure a DD statement for SYSPRINT is present. For CMS, the internal FILEDEF for SYSPRINT may have failed. Make sure the "A" disk is accessed in read/write mode.</td></tr>
</table>

==Deprecated options==
The following program options are no longer necessary.
It is recommended
that you not use them, and that if you discover them in old JCL or EXECs,
you correct them to use the newer recommended approaches.

===NOVERIFY===
The <var>NOVERIFY</var> option lets you apply ZAPs that have no verify data.
Use the <var>NOVERIFY</var> option with caution.
Once a ZAP is applied using <var>NOVERIFY</var>,
the original contents of the load module are lost.

Note: Since the <var>* !NOVERIFY</var> statement can provide the functionality needed for applying a portion of a zap without verify data, it is strongly recommended that you not use the <var>NOVERIFY</var> option, which might extend to other portions of the zap with incorrect verify data.


===VERIFY===
The <var>VERIFY</var> option ensures that all replace data has been successfully
verified before updating the load module.
<var>VERIFY</var> is a <var class="product">RockZap</var> default, and it need not be specified.

Note: Since it is recommended that you do not use the <var>NOVERIFY</var> option, you might want to avoid the <var>VERIFY</var> option as well, thus eliminating any tendency to control requirement of verify data at the job step level.


[[Category:RKTools]]

RockZap

2022-02-18T20:06:24Z

Tom: /* RockZap options */

==Introduction==
<var class="product">RockZap</var> is a load module maintenance facility, similar to z/OS IMASPZAP
or the CMS ZAP command. Prior to version 7.5 of Model 204, <var class="product">RockZap</var> was named <code>SirZap</code>.

<var class="product">RockZap</var> modifies load modules (or for CMS, both
load modules and text libraries) based on
information from control statements supplied by the user.
<var class="product">RockZap</var> is not
a plug compatible replacement for the IBM ZAP utilities, but it provides
functional and performance enhancements for load module maintenance.

<var class="product">RockZap</var> is distributed as part of a software maintenance agreement
between Rocket Software Inc. and its customers.
<var class="product">RockZap</var> is provided for
the purpose of applying maintenance to Rocket Model 204 products, but
you need not limit use of <var class="product">RockZap</var> to those products.

===Versions===
This wiki page
assumes that a site is running <var class="product">RockZap</var> version 1.6 or later.
Any documented feature or facility that requires a later version
of <var class="product">RockZap</var> will be clearly marked to indicate this.
If a feature or parameter is not
indicated as requiring any specific version of <var class="product">RockZap</var>, it can
be assumed that it is available in all versions covered by this
document; that is, versions 1.6 and later of <var class="product">RockZap</var>.

===Messages===
<var class="product">RockZap</var> messages are documented in [[:Category:RockZap messages]].

===Downloading===
<ol>
<li>Using your [[Rocket M204 user ID]] and password, log in to the [https://model204.rocketsoftware.com/maint/objlist Model 204 object file download page].</li>

<li>Click the Download object file link to the right of the RockZap object file.</li>
</ol>

==RockZap features==
RockZap provides the following features:
<ul>
<li><var class="product">RockZap</var> can save significant amounts of elapsed time and CPU for long
ZAP input streams.
This is because <var class="product">RockZap</var> applies all ZAPs in the input
stream before writing a module back to disk.
(IMASPZAP and CMS ZAP both
write parts of the load module back to disk each time a new <var>NAME</var>
statement is encountered, reducing performance significantly.)</li>

<li><var class="product">RockZap</var> detects and reports ZAPs that are already applied.
Using
IMASPZAP or CMS ZAP, the user must inspect long CSECT dumps produced by
the ZAP utility in order to determine if the ZAP is already applied, or
simply in error.</li>

<li><var class="product">RockZap</var> allows the module name on all <var>NAME</var> statements to be overridden using the <var>MODULE</var> option.
This provides the ability to have the same set of <var>VER</var>s and <var>REP</var>s applied to different load modules without making global changes to the <var>NAME</var> statements.
</li>

<li><var class="product">RockZap</var> can "back out" or remove ZAPs without requiring
modification to the ZAP control statements.
By using the BACKOUT
option, ZAPs can be removed from the load module and replaced by the
original Verify data.</li>

<li><var class="product">RockZap</var> limits error reporting to the specific statements in error, and it
reports only the information necessary to diagnose and correct the
error.</li>

<li><var class="product">RockZap</var> only writes modified load modules.
If the ZAPs are already
completely applied, <var class="product">RockZap</var> does not write the load module back to disk.</li>

<li><var class="product">RockZap</var> enforces stricter rules on ZAP input statements.
Verify statements are required for all replaced bytes.
This ensures that the
load module contents are known before they are modified, and that a ZAP
can be removed or "backed out" if necessary.
You can override this feature,
however, using the <var>[[#* !NOVERIFY|* !NOVERIFY]]</var> statement.</li>

<li><var class="product">RockZap</var> 1.7 and later support z/OS datasets with the LARGE attribute.</li>

</ul>

==Differences between RockZap and IMASPZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> only modifies direct access load libraries.
<var class="product">RockZap</var> does not
modify PDSEs or any other types of direct access data sets.</li>

<li>The following SPZAP statements are not supported but are ignored
when encountered in the input stream: SETSSI, IDRDATA, and CHECKSUM.</li>

<li>The following IMASPZAP statments are not supported and will cause
<var class="product">RockZap</var> to terminate when they are encountered:
CONSOLE, ABSDUMP, ABSDUMPT, and RECORD.</li>
</ul>

==Differences between RockZap and CMS ZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> does not support CMS LOADLIBs.</li>

<li>The following ZAP statements are not supported but are ignored
when encountered in the input stream: COMMENT and LOG.</li>
</ul>

==CMS installation==
<var class="product">RockZap</var> is distributed as a single load module in VMFPLC2 format.
A set of object decks is also included in case linkedit is required.
(This might be necessary for some older CMS versions).

[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

The <var class="product">RockZap</var> load module is linked <code>AMODE=31</code>.
If <var class="product">RockZap</var> must be relinked
on your system, use the following commands:
LOAD ROCKZAP (RESET ROCKZAP RMODE 24 AMODE 31
GENMOD ROCKZAP (FROM APPL

Note: You can omit the <var>RMODE</var> and <var>AMODE</var> parameters if you are running in a non-XA environment.


==IBM z/OS installation==
[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

<code>ROCKZAP</code> can be copied to SYS1.LINKLIB or SYS1.LPALIB, and it is reentrant.

<div id="options"></div>
==RockZap options==
z/OS users supply <var class="product">RockZap</var> options in the <code>PARM</code> parameter of the EXEC job control statement.

For example, to force uppercase output and to
backout ZAPs, use the following EXEC statement:
//ROCKZAP EXEC PGM=ROCKZAP,PARM='UPPER,BACKOUT'


CMS users specify options following a left parenthesis on the <var>ROCKZAP</var>
command line.

For example, to force uppercase output and to backout the
ZAPs in the file <code>LOCAL ZAP A1</code>, specify the following:
ROCKZAP LOCAL ( BACKOUT UPPER


===BACKOUT===
The <var>BACKOUT</var> option removes a ZAP without requiring any modification to
the ZAP input statements.
<var>BACKOUT</var> reverses the effect of a ZAP by
replacing the original <code>Verify</code> data in the module.

If the ZAPs were applied with IMASPZAP, CMS ZAP, or with <var class="product">RockZap</var> using the <var>* !NOVERIFY</var> statement, <var class="product">RockZap</var> might not be able to perform a backout because all the original <code>Verify</code> data might not be present.

===EXTRACT filetype===
The <var>EXTRACT</var> option lets you extract individual object files from
a CMS text library.
<var>EXTRACT</var> can only be used when the <var>TXTLIB</var> option is also
specified.

<var>EXTRACT</var> requires a parameter that specifies the file type
of the object files it creates. One object file is created for each
member of the text library. The text library member name is used as the CMS file name.

===MODULE===
The <var>MODULE=modname</var> option allows the module name on each <var>NAME</var> statement to be overridden with a single load-module name. This means that you can use the same <var>ROCKZAP</var> jobstream to apply the same zaps to different load modules in the designated load library (SYSLIB) without making changes to any of the <var>[[#NAME|NAME]]</var> control statements.

For example, <code>PARM='MODULE=ONLINE'</code> applies the zaps to the module named <code>ONLINE</code> in the designated load library, regardless of the load-module name on each <var>NAME</var> statement. Then, using the same job stream, <code>PARM='MODULE=ONLINTST'</code> applies the same zaps to the module named <code>ONLINTST</code>, again, regardless of the load-module name on each <var>NAME</var> statement.

Note: If you are applying zaps to a <var class="product">Model 204</var> load module, you must specify a value for <var>MODULE</var>. 

The <var>MODULE</var> option was introduced in version 1.6 of <var class="product">RockZap</var>.

===REPORT===
Under the <var>REPORT</var> option, <var class="product">RockZap</var> runs normally but does not update any load modules. This is useful if you have a production load module you do not want to modify, but you do want to know whether or not a particular set of ZAPs are applied.

===TXTLIB txtlib===
The <var>TXTLIB</var> option is valid under CMS only.
<var>TXTLIB</var> specifies that the
ZAPs should be applied to a CMS text library instead of a load module.

You must provide the name of the text library following the <var>TXTLIB</var>
parameter.
The first parameter of the name statement (the module name)
is ignored when using the <var>TXTLIB</var> option.
Only the CSECT name is used for text libraries.
No load modules are inspected or modified when the
<var>TXTLIB</var> option is specified.

===UPPER===
The <var>UPPER</var> option forces all <var class="product">RockZap</var> output to uppercase.
This is usually unnecessary, except on certain Japanese terminals and
when sending output to uppercase-only printers.
<var>UPPER</var> is the default setting for Hitachi and Fujitsu systems.

===MISSING===
The <var>MISSING</var> option suppresses errors resulting from a NAME statement that references a CSECT not present in the load module.
<var>MISSING</var> is the default.

===NOMISSING===
The <var>NOMISSING</var> option flags errors resulting from a NAME statement that references a CSECT not present in the load module. A missing CSECT results in a return code of 4.

==RockZap control statements==
<var class="product">RockZap</var> control statements appear in columns 1 to 72 in fixed length,
80 byte records.
Statements that begin with an asterisk are treated as
comments and are ignored, except for the two special inline parameter statements
<var>* !VERIFY</var> and <var>* !NOVERIFY</var>.
Control statements can begin in any column,
but line continuation is not allowed.

===VER===
The <var>VER</var> statement identifies a range of bytes to be matched with the
load module contents.
<var>VER</var> statements must follow a <var>NAME</var> statement.
A <var>VER</var> statement must be present for each range of bytes that will be
replaced in the load module.
This is to ensure that the ZAP can be backed out later if necessary.

The format of the <var>VER</var> statement is:
VER offset verify-values comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT specified in the previous <var>NAME</var> statement, or from the start of the load module if no CSECT was specified.</td></tr>

<tr><th nowrap>verify-values</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values are the expected contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">verify-values</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>VER</var> statements:
VER 00 010203,040506 Verify bytes at offset 0.

VER 01ca 47f0,c0e9

VER 23EC D20310004000,90ECD000,07FC


===REP===
The <var>REP</var> statement identifies a range of bytes to replace the current
contents of a load module.
The <var>REP</var> statement must be preceded by <var>VER</var>
statements that cover the entire range of bytes that will be replaced.

The format of the <var>REP</var> statement is:
REP offset replace-value comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT in the previous <var>NAME</var> statement.</td></tr>

<tr><th nowrap>replace-value</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values will replace the contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">replace-value</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>REP</var> statements:
REP 00 FFFFFF,FFFFFF Replace bytes at offset 0.

REP 01ca 47f0,c0e8

REP 23EC D203101C4000,90ECD008,07FE


===NAME===
The <var>NAME</var> statement identifies a load module, and optionally a CSECT, that defines the context for the <var>VER</var> and <var>REP</var> statements that follow.
<var>NAMEX</var> is a synonym for <var>NAME</var> that allows compatibility with the Fujitsu
OSIV ZAP utility.

The format of the <var>NAME</var> statement is:
NAME module [csect]

Where:
<table>
<tr><th>module</th>
<td>The name of the load module. Under CMS the filetype must be <var>MODULE</var>. Under z/OS this is the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section in the load module. A <var class="term">csect</var> value is optional. If the CSECT name is missing, subsequent verify and replace displacements are calculated from offset 0 in the load module.</td></tr>
</table>

Note: You can use the <var>[[#MODULE|MODULE]]</var> parameter to override the module name in <var>NAME</var> statements. 

===DUMP or DUMPT===
The <var>DUMP</var> statement prints all or part of the contents of a load
module or CMS text library to SYSPRINT.
Specifying <var>DUMPT</var> has the same effect as <var>DUMP</var>.

The format of the <var>DUMP</var> or <var>DUMPT</var> statement is:
DUMP[T] name [csect [offset [length]]]

Where:
<table>
<tr><th>name</th>
<td>The name of the load module or text library. Under CMS, specify the filename (only) of a file whose filetype must be <var>MODULE</var> or <var>TXTLIB</var>. Under z/OS, specify the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section. A <var class="term">csect</var> value is optional. If the CSECT clause is missing, the entire load module or text library contents are dumped.</td></tr>

<tr><th>offset</th>
<td>The hexadecimal starting offset within the CSECT. This is optional, and it can only be specified when a <var class="term">csect</var> name is specified. Use the <var class="term">offset</var> parameter when you want to dump only a part of a CSECT. If the offset is omitted, it defaults to 0.</td></tr>

<tr><th>length</th>
<td>The number of bytes (in hexadecimal) of the CSECT to dump. This is an optional parameter, and it can only be specified if a <var class="term">csect</var> value and starting <var class="term">offset</var> value are specified.</td></tr>
</table>

===* !VERIFY===
The special statement <var>* !VERIFY</var> (and <var>* !NOVERIFY</var>) lets you control whether individual ZAPs are verified before being applied.

The main purpose of these statements is to override whether the current portion of the zap requires verify data. This can be useful when a single ZAP in an input stream containing many ZAPs has no verify data.

The asterisk and space are necessary so that other ZAP utilities treat
the statements as comments.

Use <var>* !VERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !VERIFY</var> statement are verified (the <var>VER</var> data must match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
 Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use
the <var>* !NOVERIFY</var> statement instead, and only when needed. 

===* !NOVERIFY===
The special inline statement
<var>* !NOVERIFY</var> (and <var>* !VERIFY</var>) lets you control
whether individual ZAPs are verified before being applied.
The main purpose of these statements is to override whether the current
portion of the zap requires verify data.
This can be useful when a single ZAP in an input stream containing many ZAPs has no verify
data or the verify data is known to be incorrect.

Use <var>* !NOVERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !NOVERIFY</var> statement are not verified (the <var>VER</var> data may be missing or not match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use the <var>* !NOVERIFY</var> statement instead, and only when needed. 

==Using RockZap under z/OS==
Job Control requirements for <var class="product">RockZap</var> are the same as for IMASPZAP. Most <var class="product">RockZap</var> storage is allocated above the 16 megabyte line, so the default region size should be sufficient.

===RockZap DD statements===
Required statements:
<ul>
<li>SYSLIB points to the load library PDS (Partitioned Data
Set) containing the load module you want to ZAP. The load library cannot be a PDSE (Partition Data Set Extended) dataset.</li>

<li>SYSIN contains the ZAP control statements and must
have the DCB attributes of <code>RECFM=F</code> or <code>RECFM=FB</code>, and <code>LRECL=80</code>.</li>

<li>SYSPRINT is the report data set.</li>
</ul>

===RockZap sample JCL===
//ROCKZAP JOB CLASS=A,MSGCLASS=A
//ZAP EXEC PGM=ROCKZAP,PARM='RockZap parms'
//STEPLIB DD DSN=ROCKZAP.V106.LOAD,DISP=SHR
//SYSLIB DD DSN=loadlib,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
zap control statements
/*


==Using RockZap under CMS==
The format of the <var>ROCKZAP</var> command is:
ROCKZAP fn [ft [fm]] ( options


<var class="product">RockZap</var> is invoked as a CMS command.
Simply enter <code>ROCKZAP</code> followed by the
name of the input file.
The default filetype is <code>ZAP</code>, and the
default filemode is <code>*</code>.

Options are supplied in any order following the left parenthesis.
See [[#options|RockZap options]] for a list of options.

<var class="product">RockZap</var> writes the report and any modified load modules to the disk
accessed as the "A" disk.
Make sure that the "A" disk is accessed in Read/Write mode.

===Using RockZap with CMS text libraries===
When <var class="product">RockZap</var> processes a text library, the resulting text library or object files usually contain fewer records than the original.
No information is lost and the
resulting text library or object file is logically the same as the original.
Text records in the object file are always written with the maximum amount of object code
per record. Often, fewer records are required than are typically written by the
compiler or assembler that originally generated the object.

This object file "normalization" is similar to how a linkage editor processes an object
file.
<var class="product">RockZap</var> performs this normalization so that ZAPs can be applied more efficiently.

==RockZap return codes==
<table class="thJustBold">
<tr><th>0</th>
<td>ZAPs were processed successfully. Any modified load modules are written back to disk.</td></tr>

<tr><th>4</th>
<td>ZAPs were processed successfully, but one or more warning messages were produced. This usually indicates a CSECT was missing from one or more of the load modules. Check the <var class="product">RockZap</var> report for the name of the module and CSECT. If any load modules were modified, they are written back to disk.</td></tr>

<tr><th>8</th>
<td>One or more errors occurred. Check the <var class="product">RockZap</var> report for details.</td></tr>

<tr><th>12</th>
<td><var class="product">RockZap</var> was unable to open the input file. Make sure the filename is correct and that the file or PDS member is present.</td></tr>

<tr><th>40</th>
<td><var class="product">RockZap</var> could not open the report file (SYSPRINT). For z/OS, make sure a DD statement for SYSPRINT is present. For CMS, the internal FILEDEF for SYSPRINT may have failed. Make sure the "A" disk is accessed in read/write mode.</td></tr>
</table>

==Deprecated options==
The following program options are no longer necessary.
It is recommended
that you not use them, and that if you discover them in old JCL or EXECs,
you correct them to use the newer recommended approaches.

===NOVERIFY===
The <var>NOVERIFY</var> option lets you apply ZAPs that have no verify data.
Use the <var>NOVERIFY</var> option with caution.
Once a ZAP is applied using <var>NOVERIFY</var>,
the original contents of the load module are lost.

Note: Since the <var>* !NOVERIFY</var> statement can provide the functionality needed for applying a portion of a zap without verify data, it is strongly recommended that you not use the <var>NOVERIFY</var> option, which might extend to other portions of the zap with incorrect verify data.


===VERIFY===
The <var>VERIFY</var> option ensures that all replace data has been successfully
verified before updating the load module.
<var>VERIFY</var> is a <var class="product">RockZap</var> default, and it need not be specified.

Note: Since it is recommended that you do not use the <var>NOVERIFY</var> option, you might want to avoid the <var>VERIFY</var> option as well, thus eliminating any tendency to control requirement of verify data at the job step level.


[[Category:RKTools]]

ZAP0049 Fixed applied: (N-N)

2022-02-18T15:59:09Z

Tom: Blanked the page

ZAP0049 Fixes applied: (N-N)

2022-02-18T15:57:33Z

Tom: Created page with "An informational message showing the numbers or ranges of fixes applied to the ROCKZAP load module itself. This messages appears only in ROCKZAP version 1.07 and later. Ca..."

An informational message showing the numbers or ranges of fixes applied to the ROCKZAP load module itself. This messages appears only in ROCKZAP version 1.07 and later.

[[Category:RockZap messages]]

ZAP0048 Maximum 31-bit memory used: (N)K bytes

2022-02-18T15:56:39Z

Tom:

An informational message indicating the total amount of 31-bit memory required by ROCKZAP. This message appears in ROCKZAP version 1.07 and later.

[[Category:RockZap messages]]

ZAP0047 Maximum 24-bit memory used: (N)K bytes

2022-02-18T15:55:58Z

Tom:

An informational message indicating the total amount of 24-bit memory required by ROCKZAP. This message appears in ROCKZAP version 1.07 and later.

[[Category:RockZap messages]]

ZAP0049 Fixed applied: (N-N)

2022-02-18T15:55:20Z

Tom: Created page with "An informational message showing the numbers or ranges of fixes applied to the ROCKZAP load module itself. This messages appears only in ROCKZAP version 1.07 and later. Ca..."

An informational message showing the numbers or ranges of fixes applied to the ROCKZAP load module itself. This messages appears only in ROCKZAP version 1.07 and later.

[[Category:RockZap messages]]

ZAP0048 Maximum 31-bit memory used: (N)K bytes

2022-02-18T15:52:47Z

Tom: Created page with "An informational message indicating the total amount of 31-bit memory required by ROCKZAP. Category:RockZap messages"

An informational message indicating the total amount of 31-bit memory required by ROCKZAP.

[[Category:RockZap messages]]

ZAP0047 Maximum 24-bit memory used: (N)K bytes

2022-02-18T15:50:26Z

Tom: Created page with "An informational message indicating the total amount of 24-bit memory required by ROCKZAP. Category:RockZap messages"

An informational message indicating the total amount of 24-bit memory required by ROCKZAP.

[[Category:RockZap messages]]

ZAP0046 ZAPs in statements (N-N) skipped

2022-02-18T15:46:33Z

Tom: Created page with "An informational message indicating that the ZAPs in the specified range were not applied to the load module because the CSECT specified in the NAME statement was not found in..."

An informational message indicating that the ZAPs in the specified range were not applied to the load module because the CSECT specified in the NAME statement was not found in the module.

[[Category:RockZap messages]]

Category:SirAud messages

2022-02-18T15:36:26Z

Tom:

Note that the '''AUD'''''nnn'' form of messages are used only for versions 1.06 and earlier of <var class="product">SirAud</var>; starting with version 7.8 of <var class="product">SirAud</var> (the first version after 1.06), any messages issued by <var class="product">SirAud</var> appear as '''MSIR.'''wxyz messages.

==PDF of category pages==
You can [{{fullurl:{{FULLPAGENAMEE}}|action=pdfbook}} use this link] to create a PDF file that contains all the pages in this category. If this category contains a "Subcategories" section, the PDF will also contain a linked list of the pages that belong to each subcategory listed in the "Subcategories" section.

Note: The resulting PDF is not optimized for online use. All blue links except for those in the table of contents (TOC) take you outside of the PDF (typically to http://m204wiki.rocketsoftware.com), so you must rely on the PDF bookmarks and TOC for online navigation. Hovering your mouse over a link will reveal its destination. 

[[Category:Sirius messages| SirAud messages]]

RockZap

2022-02-17T22:21:06Z

Tom: /* RockZap features */

==Introduction==
<var class="product">RockZap</var> is a load module maintenance facility, similar to z/OS IMASPZAP
or the CMS ZAP command. Prior to version 7.5 of Model 204, <var class="product">RockZap</var> was named <code>SirZap</code>.

<var class="product">RockZap</var> modifies load modules (or for CMS, both
load modules and text libraries) based on
information from control statements supplied by the user.
<var class="product">RockZap</var> is not
a plug compatible replacement for the IBM ZAP utilities, but it provides
functional and performance enhancements for load module maintenance.

<var class="product">RockZap</var> is distributed as part of a software maintenance agreement
between Rocket Software Inc. and its customers.
<var class="product">RockZap</var> is provided for
the purpose of applying maintenance to Rocket Model 204 products, but
you need not limit use of <var class="product">RockZap</var> to those products.

===Versions===
This wiki page
assumes that a site is running <var class="product">RockZap</var> version 1.6 or later.
Any documented feature or facility that requires a later version
of <var class="product">RockZap</var> will be clearly marked to indicate this.
If a feature or parameter is not
indicated as requiring any specific version of <var class="product">RockZap</var>, it can
be assumed that it is available in all versions covered by this
document; that is, versions 1.6 and later of <var class="product">RockZap</var>.

===Messages===
<var class="product">RockZap</var> messages are documented in [[:Category:RockZap messages]].

===Downloading===
<ol>
<li>Using your [[Rocket M204 user ID]] and password, log in to the [https://model204.rocketsoftware.com/maint/objlist Model 204 object file download page].</li>

<li>Click the Download object file link to the right of the RockZap object file.</li>
</ol>

==RockZap features==
RockZap provides the following features:
<ul>
<li><var class="product">RockZap</var> can save significant amounts of elapsed time and CPU for long
ZAP input streams.
This is because <var class="product">RockZap</var> applies all ZAPs in the input
stream before writing a module back to disk.
(IMASPZAP and CMS ZAP both
write parts of the load module back to disk each time a new <var>NAME</var>
statement is encountered, reducing performance significantly.)</li>

<li><var class="product">RockZap</var> detects and reports ZAPs that are already applied.
Using
IMASPZAP or CMS ZAP, the user must inspect long CSECT dumps produced by
the ZAP utility in order to determine if the ZAP is already applied, or
simply in error.</li>

<li><var class="product">RockZap</var> allows the module name on all <var>NAME</var> statements to be overridden using the <var>MODULE</var> option.
This provides the ability to have the same set of <var>VER</var>s and <var>REP</var>s applied to different load modules without making global changes to the <var>NAME</var> statements.
</li>

<li><var class="product">RockZap</var> can "back out" or remove ZAPs without requiring
modification to the ZAP control statements.
By using the BACKOUT
option, ZAPs can be removed from the load module and replaced by the
original Verify data.</li>

<li><var class="product">RockZap</var> limits error reporting to the specific statements in error, and it
reports only the information necessary to diagnose and correct the
error.</li>

<li><var class="product">RockZap</var> only writes modified load modules.
If the ZAPs are already
completely applied, <var class="product">RockZap</var> does not write the load module back to disk.</li>

<li><var class="product">RockZap</var> enforces stricter rules on ZAP input statements.
Verify statements are required for all replaced bytes.
This ensures that the
load module contents are known before they are modified, and that a ZAP
can be removed or "backed out" if necessary.
You can override this feature,
however, using the <var>[[#* !NOVERIFY|* !NOVERIFY]]</var> statement.</li>

<li><var class="product">RockZap</var> 1.7 and later support z/OS datasets with the LARGE attribute.</li>

</ul>

==Differences between RockZap and IMASPZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> only modifies direct access load libraries.
<var class="product">RockZap</var> does not
modify PDSEs or any other types of direct access data sets.</li>

<li>The following SPZAP statements are not supported but are ignored
when encountered in the input stream: SETSSI, IDRDATA, and CHECKSUM.</li>

<li>The following IMASPZAP statments are not supported and will cause
<var class="product">RockZap</var> to terminate when they are encountered:
CONSOLE, ABSDUMP, ABSDUMPT, and RECORD.</li>
</ul>

==Differences between RockZap and CMS ZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> does not support CMS LOADLIBs.</li>

<li>The following ZAP statements are not supported but are ignored
when encountered in the input stream: COMMENT and LOG.</li>
</ul>

==CMS installation==
<var class="product">RockZap</var> is distributed as a single load module in VMFPLC2 format.
A set of object decks is also included in case linkedit is required.
(This might be necessary for some older CMS versions).

[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

The <var class="product">RockZap</var> load module is linked <code>AMODE=31</code>.
If <var class="product">RockZap</var> must be relinked
on your system, use the following commands:
LOAD ROCKZAP (RESET ROCKZAP RMODE 24 AMODE 31
GENMOD ROCKZAP (FROM APPL

Note: You can omit the <var>RMODE</var> and <var>AMODE</var> parameters if you are running in a non-XA environment.


==IBM z/OS installation==
[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

<code>ROCKZAP</code> can be copied to SYS1.LINKLIB or SYS1.LPALIB, and it is reentrant.

<div id="options"></div>
==RockZap options==
z/OS users supply <var class="product">RockZap</var> options in the <code>PARM</code> parameter of the EXEC job control statement.

For example, to force uppercase output and to
backout ZAPs, use the following EXEC statement:
//ROCKZAP EXEC PGM=ROCKZAP,PARM='UPPER,BACKOUT'


CMS users specify options following a left parenthesis on the <var>ROCKZAP</var>
command line.

For example, to force uppercase output and to backout the
ZAPs in the file <code>LOCAL ZAP A1</code>, specify the following:
ROCKZAP LOCAL ( BACKOUT UPPER


===BACKOUT===
The <var>BACKOUT</var> option removes a ZAP without requiring any modification to
the ZAP input statements.
<var>BACKOUT</var> reverses the effect of a ZAP by
replacing the original <code>Verify</code> data in the module.

If the ZAPs were applied with IMASPZAP, CMS ZAP, or with <var class="product">RockZap</var> using the <var>* !NOVERIFY</var> statement, <var class="product">RockZap</var> might not be able to perform a backout because all the original <code>Verify</code> data might not be present.

===EXTRACT filetype===
The <var>EXTRACT</var> option lets you extract individual object files from
a CMS text library.
<var>EXTRACT</var> can only be used when the <var>TXTLIB</var> option is also
specified.

<var>EXTRACT</var> requires a parameter that specifies the file type
of the object files it creates. One object file is created for each
member of the text library. The text library member name is used as the CMS file name.

===MODULE===
The <var>MODULE=modname</var> option allows the module name on each <var>NAME</var> statement to be overridden with a single load-module name. This means that you can use the same <var>ROCKZAP</var> jobstream to apply the same zaps to different load modules in the designated load library (SYSLIB) without making changes to any of the <var>[[#NAME|NAME]]</var> control statements.

For example, <code>PARM='MODULE=ONLINE'</code> applies the zaps to the module named <code>ONLINE</code> in the designated load library, regardless of the load-module name on each <var>NAME</var> statement. Then, using the same job stream, <code>PARM='MODULE=ONLINTST'</code> applies the same zaps to the module named <code>ONLINTST</code>, again, regardless of the load-module name on each <var>NAME</var> statement.

Note: If you are applying zaps to a <var class="product">Model 204</var> load module, you must specify a value for <var>MODULE</var>. 

The <var>MODULE</var> option was introduced in version 1.6 of <var class="product">RockZap</var>.

===REPORT===
Under the <var>REPORT</var> option, <var class="product">RockZap</var> runs normally but does not update any load modules. This is useful if you have a production load module you do not want to modify, but you do want to know whether or not a particular set of ZAPs are applied.

===TXTLIB txtlib===
The <var>TXTLIB</var> option is valid under CMS only.
<var>TXTLIB</var> specifies that the
ZAPs should be applied to a CMS text library instead of a load module.

You must provide the name of the text library following the <var>TXTLIB</var>
parameter.
The first parameter of the name statement (the module name)
is ignored when using the <var>TXTLIB</var> option.
Only the CSECT name is used for text libraries.
No load modules are inspected or modified when the
<var>TXTLIB</var> option is specified.

===UPPER===
The <var>UPPER</var> option forces all <var class="product">RockZap</var> output to uppercase.
This is usually unnecessary, except on certain Japanese terminals and
when sending output to uppercase-only printers.
<var>UPPER</var> is the default setting for Hitachi and Fujitsu systems.

==RockZap control statements==
<var class="product">RockZap</var> control statements appear in columns 1 to 72 in fixed length,
80 byte records.
Statements that begin with an asterisk are treated as
comments and are ignored, except for the two special inline parameter statements
<var>* !VERIFY</var> and <var>* !NOVERIFY</var>.
Control statements can begin in any column,
but line continuation is not allowed.

===VER===
The <var>VER</var> statement identifies a range of bytes to be matched with the
load module contents.
<var>VER</var> statements must follow a <var>NAME</var> statement.
A <var>VER</var> statement must be present for each range of bytes that will be
replaced in the load module.
This is to ensure that the ZAP can be backed out later if necessary.

The format of the <var>VER</var> statement is:
VER offset verify-values comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT specified in the previous <var>NAME</var> statement, or from the start of the load module if no CSECT was specified.</td></tr>

<tr><th nowrap>verify-values</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values are the expected contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">verify-values</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>VER</var> statements:
VER 00 010203,040506 Verify bytes at offset 0.

VER 01ca 47f0,c0e9

VER 23EC D20310004000,90ECD000,07FC


===REP===
The <var>REP</var> statement identifies a range of bytes to replace the current
contents of a load module.
The <var>REP</var> statement must be preceded by <var>VER</var>
statements that cover the entire range of bytes that will be replaced.

The format of the <var>REP</var> statement is:
REP offset replace-value comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT in the previous <var>NAME</var> statement.</td></tr>

<tr><th nowrap>replace-value</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values will replace the contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">replace-value</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>REP</var> statements:
REP 00 FFFFFF,FFFFFF Replace bytes at offset 0.

REP 01ca 47f0,c0e8

REP 23EC D203101C4000,90ECD008,07FE


===NAME===
The <var>NAME</var> statement identifies a load module, and optionally a CSECT, that defines the context for the <var>VER</var> and <var>REP</var> statements that follow.
<var>NAMEX</var> is a synonym for <var>NAME</var> that allows compatibility with the Fujitsu
OSIV ZAP utility.

The format of the <var>NAME</var> statement is:
NAME module [csect]

Where:
<table>
<tr><th>module</th>
<td>The name of the load module. Under CMS the filetype must be <var>MODULE</var>. Under z/OS this is the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section in the load module. A <var class="term">csect</var> value is optional. If the CSECT name is missing, subsequent verify and replace displacements are calculated from offset 0 in the load module.</td></tr>
</table>

Note: You can use the <var>[[#MODULE|MODULE]]</var> parameter to override the module name in <var>NAME</var> statements. 

===DUMP or DUMPT===
The <var>DUMP</var> statement prints all or part of the contents of a load
module or CMS text library to SYSPRINT.
Specifying <var>DUMPT</var> has the same effect as <var>DUMP</var>.

The format of the <var>DUMP</var> or <var>DUMPT</var> statement is:
DUMP[T] name [csect [offset [length]]]

Where:
<table>
<tr><th>name</th>
<td>The name of the load module or text library. Under CMS, specify the filename (only) of a file whose filetype must be <var>MODULE</var> or <var>TXTLIB</var>. Under z/OS, specify the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section. A <var class="term">csect</var> value is optional. If the CSECT clause is missing, the entire load module or text library contents are dumped.</td></tr>

<tr><th>offset</th>
<td>The hexadecimal starting offset within the CSECT. This is optional, and it can only be specified when a <var class="term">csect</var> name is specified. Use the <var class="term">offset</var> parameter when you want to dump only a part of a CSECT. If the offset is omitted, it defaults to 0.</td></tr>

<tr><th>length</th>
<td>The number of bytes (in hexadecimal) of the CSECT to dump. This is an optional parameter, and it can only be specified if a <var class="term">csect</var> value and starting <var class="term">offset</var> value are specified.</td></tr>
</table>

===* !VERIFY===
The special statement <var>* !VERIFY</var> (and <var>* !NOVERIFY</var>) lets you control whether individual ZAPs are verified before being applied.

The main purpose of these statements is to override whether the current portion of the zap requires verify data. This can be useful when a single ZAP in an input stream containing many ZAPs has no verify data.

The asterisk and space are necessary so that other ZAP utilities treat
the statements as comments.

Use <var>* !VERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !VERIFY</var> statement are verified (the <var>VER</var> data must match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
 Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use
the <var>* !NOVERIFY</var> statement instead, and only when needed. 

===* !NOVERIFY===
The special inline statement
<var>* !NOVERIFY</var> (and <var>* !VERIFY</var>) lets you control
whether individual ZAPs are verified before being applied.
The main purpose of these statements is to override whether the current
portion of the zap requires verify data.
This can be useful when a single ZAP in an input stream containing many ZAPs has no verify
data or the verify data is known to be incorrect.

Use <var>* !NOVERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !NOVERIFY</var> statement are not verified (the <var>VER</var> data may be missing or not match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use the <var>* !NOVERIFY</var> statement instead, and only when needed. 

==Using RockZap under z/OS==
Job Control requirements for <var class="product">RockZap</var> are the same as for IMASPZAP. Most <var class="product">RockZap</var> storage is allocated above the 16 megabyte line, so the default region size should be sufficient.

===RockZap DD statements===
Required statements:
<ul>
<li>SYSLIB points to the load library PDS (Partitioned Data
Set) containing the load module you want to ZAP. The load library cannot be a PDSE (Partition Data Set Extended) dataset.</li>

<li>SYSIN contains the ZAP control statements and must
have the DCB attributes of <code>RECFM=F</code> or <code>RECFM=FB</code>, and <code>LRECL=80</code>.</li>

<li>SYSPRINT is the report data set.</li>
</ul>

===RockZap sample JCL===
//ROCKZAP JOB CLASS=A,MSGCLASS=A
//ZAP EXEC PGM=ROCKZAP,PARM='RockZap parms'
//STEPLIB DD DSN=ROCKZAP.V106.LOAD,DISP=SHR
//SYSLIB DD DSN=loadlib,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
zap control statements
/*


==Using RockZap under CMS==
The format of the <var>ROCKZAP</var> command is:
ROCKZAP fn [ft [fm]] ( options


<var class="product">RockZap</var> is invoked as a CMS command.
Simply enter <code>ROCKZAP</code> followed by the
name of the input file.
The default filetype is <code>ZAP</code>, and the
default filemode is <code>*</code>.

Options are supplied in any order following the left parenthesis.
See [[#options|RockZap options]] for a list of options.

<var class="product">RockZap</var> writes the report and any modified load modules to the disk
accessed as the "A" disk.
Make sure that the "A" disk is accessed in Read/Write mode.

===Using RockZap with CMS text libraries===
When <var class="product">RockZap</var> processes a text library, the resulting text library or object files usually contain fewer records than the original.
No information is lost and the
resulting text library or object file is logically the same as the original.
Text records in the object file are always written with the maximum amount of object code
per record. Often, fewer records are required than are typically written by the
compiler or assembler that originally generated the object.

This object file "normalization" is similar to how a linkage editor processes an object
file.
<var class="product">RockZap</var> performs this normalization so that ZAPs can be applied more efficiently.

==RockZap return codes==
<table class="thJustBold">
<tr><th>0</th>
<td>ZAPs were processed successfully. Any modified load modules are written back to disk.</td></tr>

<tr><th>4</th>
<td>ZAPs were processed successfully, but one or more warning messages were produced. This usually indicates a CSECT was missing from one or more of the load modules. Check the <var class="product">RockZap</var> report for the name of the module and CSECT. If any load modules were modified, they are written back to disk.</td></tr>

<tr><th>8</th>
<td>One or more errors occurred. Check the <var class="product">RockZap</var> report for details.</td></tr>

<tr><th>12</th>
<td><var class="product">RockZap</var> was unable to open the input file. Make sure the filename is correct and that the file or PDS member is present.</td></tr>

<tr><th>40</th>
<td><var class="product">RockZap</var> could not open the report file (SYSPRINT). For z/OS, make sure a DD statement for SYSPRINT is present. For CMS, the internal FILEDEF for SYSPRINT may have failed. Make sure the "A" disk is accessed in read/write mode.</td></tr>
</table>

==Deprecated options==
The following program options are no longer necessary.
It is recommended
that you not use them, and that if you discover them in old JCL or EXECs,
you correct them to use the newer recommended approaches.

===NOVERIFY===
The <var>NOVERIFY</var> option lets you apply ZAPs that have no verify data.
Use the <var>NOVERIFY</var> option with caution.
Once a ZAP is applied using <var>NOVERIFY</var>,
the original contents of the load module are lost.

Note: Since the <var>* !NOVERIFY</var> statement can provide the functionality needed for applying a portion of a zap without verify data, it is strongly recommended that you not use the <var>NOVERIFY</var> option, which might extend to other portions of the zap with incorrect verify data.


===VERIFY===
The <var>VERIFY</var> option ensures that all replace data has been successfully
verified before updating the load module.
<var>VERIFY</var> is a <var class="product">RockZap</var> default, and it need not be specified.

Note: Since it is recommended that you do not use the <var>NOVERIFY</var> option, you might want to avoid the <var>VERIFY</var> option as well, thus eliminating any tendency to control requirement of verify data at the job step level.


[[Category:RKTools]]

RockZap

2022-02-17T22:20:34Z

Tom: /* RockZap features */

==Introduction==
<var class="product">RockZap</var> is a load module maintenance facility, similar to z/OS IMASPZAP
or the CMS ZAP command. Prior to version 7.5 of Model 204, <var class="product">RockZap</var> was named <code>SirZap</code>.

<var class="product">RockZap</var> modifies load modules (or for CMS, both
load modules and text libraries) based on
information from control statements supplied by the user.
<var class="product">RockZap</var> is not
a plug compatible replacement for the IBM ZAP utilities, but it provides
functional and performance enhancements for load module maintenance.

<var class="product">RockZap</var> is distributed as part of a software maintenance agreement
between Rocket Software Inc. and its customers.
<var class="product">RockZap</var> is provided for
the purpose of applying maintenance to Rocket Model 204 products, but
you need not limit use of <var class="product">RockZap</var> to those products.

===Versions===
This wiki page
assumes that a site is running <var class="product">RockZap</var> version 1.6 or later.
Any documented feature or facility that requires a later version
of <var class="product">RockZap</var> will be clearly marked to indicate this.
If a feature or parameter is not
indicated as requiring any specific version of <var class="product">RockZap</var>, it can
be assumed that it is available in all versions covered by this
document; that is, versions 1.6 and later of <var class="product">RockZap</var>.

===Messages===
<var class="product">RockZap</var> messages are documented in [[:Category:RockZap messages]].

===Downloading===
<ol>
<li>Using your [[Rocket M204 user ID]] and password, log in to the [https://model204.rocketsoftware.com/maint/objlist Model 204 object file download page].</li>

<li>Click the Download object file link to the right of the RockZap object file.</li>
</ol>

==RockZap features==
RockZap provides the following features:
<ul>
<li><var class="product">RockZap</var> can save significant amounts of elapsed time and CPU for long
ZAP input streams.
This is because <var class="product">RockZap</var> applies all ZAPs in the input
stream before writing a module back to disk.
(IMASPZAP and CMS ZAP both
write parts of the load module back to disk each time a new <var>NAME</var>
statement is encountered, reducing performance significantly.)</li>

<li><var class="product">RockZap</var> detects and reports ZAPs that are already applied.
Using
IMASPZAP or CMS ZAP, the user must inspect long CSECT dumps produced by
the ZAP utility in order to determine if the ZAP is already applied, or
simply in error.</li>

<li><var class="product">RockZap</var> allows the module name on all <var>NAME</var> statements to be overridden using the <var>MODULE</var> option.
This provides the ability to have the same set of <var>VER</var>s and <var>REP</var>s applied to different load modules without making global changes to the <var>NAME</var> statements.
</li>

<li><var class="product">RockZap</var> can "back out" or remove ZAPs without requiring
modification to the ZAP control statements.
By using the BACKOUT
option, ZAPs can be removed from the load module and replaced by the
original Verify data.</li>

<li><var class="product">RockZap</var> limits error reporting to the specific statements in error, and it
reports only the information necessary to diagnose and correct the
error.</li>

<li><var class="product">RockZap</var> only writes modified load modules.
If the ZAPs are already
completely applied, <var class="product">RockZap</var> does not write the load module back to disk.</li>

<li><var class="product">RockZap</var> enforces stricter rules on ZAP input statements.
Verify statements are required for all replaced bytes.
This ensures that the
load module contents are known before they are modified, and that a ZAP
can be removed or "backed out" if necessary.
You can override this feature,
however, using the <var>[[#* !NOVERIFY|* !NOVERIFY]]</var> statement.</li>

<li><var class="product">RockZap</var> 1.7 and later support LARGE z/OS datasets.</li>

</ul>

==Differences between RockZap and IMASPZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> only modifies direct access load libraries.
<var class="product">RockZap</var> does not
modify PDSEs or any other types of direct access data sets.</li>

<li>The following SPZAP statements are not supported but are ignored
when encountered in the input stream: SETSSI, IDRDATA, and CHECKSUM.</li>

<li>The following IMASPZAP statments are not supported and will cause
<var class="product">RockZap</var> to terminate when they are encountered:
CONSOLE, ABSDUMP, ABSDUMPT, and RECORD.</li>
</ul>

==Differences between RockZap and CMS ZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> does not support CMS LOADLIBs.</li>

<li>The following ZAP statements are not supported but are ignored
when encountered in the input stream: COMMENT and LOG.</li>
</ul>

==CMS installation==
<var class="product">RockZap</var> is distributed as a single load module in VMFPLC2 format.
A set of object decks is also included in case linkedit is required.
(This might be necessary for some older CMS versions).

[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

The <var class="product">RockZap</var> load module is linked <code>AMODE=31</code>.
If <var class="product">RockZap</var> must be relinked
on your system, use the following commands:
LOAD ROCKZAP (RESET ROCKZAP RMODE 24 AMODE 31
GENMOD ROCKZAP (FROM APPL

Note: You can omit the <var>RMODE</var> and <var>AMODE</var> parameters if you are running in a non-XA environment.


==IBM z/OS installation==
[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

<code>ROCKZAP</code> can be copied to SYS1.LINKLIB or SYS1.LPALIB, and it is reentrant.

<div id="options"></div>
==RockZap options==
z/OS users supply <var class="product">RockZap</var> options in the <code>PARM</code> parameter of the EXEC job control statement.

For example, to force uppercase output and to
backout ZAPs, use the following EXEC statement:
//ROCKZAP EXEC PGM=ROCKZAP,PARM='UPPER,BACKOUT'


CMS users specify options following a left parenthesis on the <var>ROCKZAP</var>
command line.

For example, to force uppercase output and to backout the
ZAPs in the file <code>LOCAL ZAP A1</code>, specify the following:
ROCKZAP LOCAL ( BACKOUT UPPER


===BACKOUT===
The <var>BACKOUT</var> option removes a ZAP without requiring any modification to
the ZAP input statements.
<var>BACKOUT</var> reverses the effect of a ZAP by
replacing the original <code>Verify</code> data in the module.

If the ZAPs were applied with IMASPZAP, CMS ZAP, or with <var class="product">RockZap</var> using the <var>* !NOVERIFY</var> statement, <var class="product">RockZap</var> might not be able to perform a backout because all the original <code>Verify</code> data might not be present.

===EXTRACT filetype===
The <var>EXTRACT</var> option lets you extract individual object files from
a CMS text library.
<var>EXTRACT</var> can only be used when the <var>TXTLIB</var> option is also
specified.

<var>EXTRACT</var> requires a parameter that specifies the file type
of the object files it creates. One object file is created for each
member of the text library. The text library member name is used as the CMS file name.

===MODULE===
The <var>MODULE=modname</var> option allows the module name on each <var>NAME</var> statement to be overridden with a single load-module name. This means that you can use the same <var>ROCKZAP</var> jobstream to apply the same zaps to different load modules in the designated load library (SYSLIB) without making changes to any of the <var>[[#NAME|NAME]]</var> control statements.

For example, <code>PARM='MODULE=ONLINE'</code> applies the zaps to the module named <code>ONLINE</code> in the designated load library, regardless of the load-module name on each <var>NAME</var> statement. Then, using the same job stream, <code>PARM='MODULE=ONLINTST'</code> applies the same zaps to the module named <code>ONLINTST</code>, again, regardless of the load-module name on each <var>NAME</var> statement.

Note: If you are applying zaps to a <var class="product">Model 204</var> load module, you must specify a value for <var>MODULE</var>. 

The <var>MODULE</var> option was introduced in version 1.6 of <var class="product">RockZap</var>.

===REPORT===
Under the <var>REPORT</var> option, <var class="product">RockZap</var> runs normally but does not update any load modules. This is useful if you have a production load module you do not want to modify, but you do want to know whether or not a particular set of ZAPs are applied.

===TXTLIB txtlib===
The <var>TXTLIB</var> option is valid under CMS only.
<var>TXTLIB</var> specifies that the
ZAPs should be applied to a CMS text library instead of a load module.

You must provide the name of the text library following the <var>TXTLIB</var>
parameter.
The first parameter of the name statement (the module name)
is ignored when using the <var>TXTLIB</var> option.
Only the CSECT name is used for text libraries.
No load modules are inspected or modified when the
<var>TXTLIB</var> option is specified.

===UPPER===
The <var>UPPER</var> option forces all <var class="product">RockZap</var> output to uppercase.
This is usually unnecessary, except on certain Japanese terminals and
when sending output to uppercase-only printers.
<var>UPPER</var> is the default setting for Hitachi and Fujitsu systems.

==RockZap control statements==
<var class="product">RockZap</var> control statements appear in columns 1 to 72 in fixed length,
80 byte records.
Statements that begin with an asterisk are treated as
comments and are ignored, except for the two special inline parameter statements
<var>* !VERIFY</var> and <var>* !NOVERIFY</var>.
Control statements can begin in any column,
but line continuation is not allowed.

===VER===
The <var>VER</var> statement identifies a range of bytes to be matched with the
load module contents.
<var>VER</var> statements must follow a <var>NAME</var> statement.
A <var>VER</var> statement must be present for each range of bytes that will be
replaced in the load module.
This is to ensure that the ZAP can be backed out later if necessary.

The format of the <var>VER</var> statement is:
VER offset verify-values comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT specified in the previous <var>NAME</var> statement, or from the start of the load module if no CSECT was specified.</td></tr>

<tr><th nowrap>verify-values</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values are the expected contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">verify-values</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>VER</var> statements:
VER 00 010203,040506 Verify bytes at offset 0.

VER 01ca 47f0,c0e9

VER 23EC D20310004000,90ECD000,07FC


===REP===
The <var>REP</var> statement identifies a range of bytes to replace the current
contents of a load module.
The <var>REP</var> statement must be preceded by <var>VER</var>
statements that cover the entire range of bytes that will be replaced.

The format of the <var>REP</var> statement is:
REP offset replace-value comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT in the previous <var>NAME</var> statement.</td></tr>

<tr><th nowrap>replace-value</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values will replace the contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">replace-value</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>REP</var> statements:
REP 00 FFFFFF,FFFFFF Replace bytes at offset 0.

REP 01ca 47f0,c0e8

REP 23EC D203101C4000,90ECD008,07FE


===NAME===
The <var>NAME</var> statement identifies a load module, and optionally a CSECT, that defines the context for the <var>VER</var> and <var>REP</var> statements that follow.
<var>NAMEX</var> is a synonym for <var>NAME</var> that allows compatibility with the Fujitsu
OSIV ZAP utility.

The format of the <var>NAME</var> statement is:
NAME module [csect]

Where:
<table>
<tr><th>module</th>
<td>The name of the load module. Under CMS the filetype must be <var>MODULE</var>. Under z/OS this is the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section in the load module. A <var class="term">csect</var> value is optional. If the CSECT name is missing, subsequent verify and replace displacements are calculated from offset 0 in the load module.</td></tr>
</table>

Note: You can use the <var>[[#MODULE|MODULE]]</var> parameter to override the module name in <var>NAME</var> statements. 

===DUMP or DUMPT===
The <var>DUMP</var> statement prints all or part of the contents of a load
module or CMS text library to SYSPRINT.
Specifying <var>DUMPT</var> has the same effect as <var>DUMP</var>.

The format of the <var>DUMP</var> or <var>DUMPT</var> statement is:
DUMP[T] name [csect [offset [length]]]

Where:
<table>
<tr><th>name</th>
<td>The name of the load module or text library. Under CMS, specify the filename (only) of a file whose filetype must be <var>MODULE</var> or <var>TXTLIB</var>. Under z/OS, specify the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section. A <var class="term">csect</var> value is optional. If the CSECT clause is missing, the entire load module or text library contents are dumped.</td></tr>

<tr><th>offset</th>
<td>The hexadecimal starting offset within the CSECT. This is optional, and it can only be specified when a <var class="term">csect</var> name is specified. Use the <var class="term">offset</var> parameter when you want to dump only a part of a CSECT. If the offset is omitted, it defaults to 0.</td></tr>

<tr><th>length</th>
<td>The number of bytes (in hexadecimal) of the CSECT to dump. This is an optional parameter, and it can only be specified if a <var class="term">csect</var> value and starting <var class="term">offset</var> value are specified.</td></tr>
</table>

===* !VERIFY===
The special statement <var>* !VERIFY</var> (and <var>* !NOVERIFY</var>) lets you control whether individual ZAPs are verified before being applied.

The main purpose of these statements is to override whether the current portion of the zap requires verify data. This can be useful when a single ZAP in an input stream containing many ZAPs has no verify data.

The asterisk and space are necessary so that other ZAP utilities treat
the statements as comments.

Use <var>* !VERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !VERIFY</var> statement are verified (the <var>VER</var> data must match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
 Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use
the <var>* !NOVERIFY</var> statement instead, and only when needed. 

===* !NOVERIFY===
The special inline statement
<var>* !NOVERIFY</var> (and <var>* !VERIFY</var>) lets you control
whether individual ZAPs are verified before being applied.
The main purpose of these statements is to override whether the current
portion of the zap requires verify data.
This can be useful when a single ZAP in an input stream containing many ZAPs has no verify
data or the verify data is known to be incorrect.

Use <var>* !NOVERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !NOVERIFY</var> statement are not verified (the <var>VER</var> data may be missing or not match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use the <var>* !NOVERIFY</var> statement instead, and only when needed. 

==Using RockZap under z/OS==
Job Control requirements for <var class="product">RockZap</var> are the same as for IMASPZAP. Most <var class="product">RockZap</var> storage is allocated above the 16 megabyte line, so the default region size should be sufficient.

===RockZap DD statements===
Required statements:
<ul>
<li>SYSLIB points to the load library PDS (Partitioned Data
Set) containing the load module you want to ZAP. The load library cannot be a PDSE (Partition Data Set Extended) dataset.</li>

<li>SYSIN contains the ZAP control statements and must
have the DCB attributes of <code>RECFM=F</code> or <code>RECFM=FB</code>, and <code>LRECL=80</code>.</li>

<li>SYSPRINT is the report data set.</li>
</ul>

===RockZap sample JCL===
//ROCKZAP JOB CLASS=A,MSGCLASS=A
//ZAP EXEC PGM=ROCKZAP,PARM='RockZap parms'
//STEPLIB DD DSN=ROCKZAP.V106.LOAD,DISP=SHR
//SYSLIB DD DSN=loadlib,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
zap control statements
/*


==Using RockZap under CMS==
The format of the <var>ROCKZAP</var> command is:
ROCKZAP fn [ft [fm]] ( options


<var class="product">RockZap</var> is invoked as a CMS command.
Simply enter <code>ROCKZAP</code> followed by the
name of the input file.
The default filetype is <code>ZAP</code>, and the
default filemode is <code>*</code>.

Options are supplied in any order following the left parenthesis.
See [[#options|RockZap options]] for a list of options.

<var class="product">RockZap</var> writes the report and any modified load modules to the disk
accessed as the "A" disk.
Make sure that the "A" disk is accessed in Read/Write mode.

===Using RockZap with CMS text libraries===
When <var class="product">RockZap</var> processes a text library, the resulting text library or object files usually contain fewer records than the original.
No information is lost and the
resulting text library or object file is logically the same as the original.
Text records in the object file are always written with the maximum amount of object code
per record. Often, fewer records are required than are typically written by the
compiler or assembler that originally generated the object.

This object file "normalization" is similar to how a linkage editor processes an object
file.
<var class="product">RockZap</var> performs this normalization so that ZAPs can be applied more efficiently.

==RockZap return codes==
<table class="thJustBold">
<tr><th>0</th>
<td>ZAPs were processed successfully. Any modified load modules are written back to disk.</td></tr>

<tr><th>4</th>
<td>ZAPs were processed successfully, but one or more warning messages were produced. This usually indicates a CSECT was missing from one or more of the load modules. Check the <var class="product">RockZap</var> report for the name of the module and CSECT. If any load modules were modified, they are written back to disk.</td></tr>

<tr><th>8</th>
<td>One or more errors occurred. Check the <var class="product">RockZap</var> report for details.</td></tr>

<tr><th>12</th>
<td><var class="product">RockZap</var> was unable to open the input file. Make sure the filename is correct and that the file or PDS member is present.</td></tr>

<tr><th>40</th>
<td><var class="product">RockZap</var> could not open the report file (SYSPRINT). For z/OS, make sure a DD statement for SYSPRINT is present. For CMS, the internal FILEDEF for SYSPRINT may have failed. Make sure the "A" disk is accessed in read/write mode.</td></tr>
</table>

==Deprecated options==
The following program options are no longer necessary.
It is recommended
that you not use them, and that if you discover them in old JCL or EXECs,
you correct them to use the newer recommended approaches.

===NOVERIFY===
The <var>NOVERIFY</var> option lets you apply ZAPs that have no verify data.
Use the <var>NOVERIFY</var> option with caution.
Once a ZAP is applied using <var>NOVERIFY</var>,
the original contents of the load module are lost.

Note: Since the <var>* !NOVERIFY</var> statement can provide the functionality needed for applying a portion of a zap without verify data, it is strongly recommended that you not use the <var>NOVERIFY</var> option, which might extend to other portions of the zap with incorrect verify data.


===VERIFY===
The <var>VERIFY</var> option ensures that all replace data has been successfully
verified before updating the load module.
<var>VERIFY</var> is a <var class="product">RockZap</var> default, and it need not be specified.

Note: Since it is recommended that you do not use the <var>NOVERIFY</var> option, you might want to avoid the <var>VERIFY</var> option as well, thus eliminating any tendency to control requirement of verify data at the job step level.


[[Category:RKTools]]

RockZap

2022-02-17T22:16:34Z

Tom: /* Differences between RockZap and IMASPZAP */

==Introduction==
<var class="product">RockZap</var> is a load module maintenance facility, similar to z/OS IMASPZAP
or the CMS ZAP command. Prior to version 7.5 of Model 204, <var class="product">RockZap</var> was named <code>SirZap</code>.

<var class="product">RockZap</var> modifies load modules (or for CMS, both
load modules and text libraries) based on
information from control statements supplied by the user.
<var class="product">RockZap</var> is not
a plug compatible replacement for the IBM ZAP utilities, but it provides
functional and performance enhancements for load module maintenance.

<var class="product">RockZap</var> is distributed as part of a software maintenance agreement
between Rocket Software Inc. and its customers.
<var class="product">RockZap</var> is provided for
the purpose of applying maintenance to Rocket Model 204 products, but
you need not limit use of <var class="product">RockZap</var> to those products.

===Versions===
This wiki page
assumes that a site is running <var class="product">RockZap</var> version 1.6 or later.
Any documented feature or facility that requires a later version
of <var class="product">RockZap</var> will be clearly marked to indicate this.
If a feature or parameter is not
indicated as requiring any specific version of <var class="product">RockZap</var>, it can
be assumed that it is available in all versions covered by this
document; that is, versions 1.6 and later of <var class="product">RockZap</var>.

===Messages===
<var class="product">RockZap</var> messages are documented in [[:Category:RockZap messages]].

===Downloading===
<ol>
<li>Using your [[Rocket M204 user ID]] and password, log in to the [https://model204.rocketsoftware.com/maint/objlist Model 204 object file download page].</li>

<li>Click the Download object file link to the right of the RockZap object file.</li>
</ol>

==RockZap features==
RockZap provides the following features:
<ul>
<li><var class="product">RockZap</var> can save significant amounts of elapsed time and CPU for long
ZAP input streams.
This is because <var class="product">RockZap</var> applies all ZAPs in the input
stream before writing a module back to disk.
(IMASPZAP and CMS ZAP both
write parts of the load module back to disk each time a new <var>NAME</var>
statement is encountered, reducing performance significantly.)</li>

<li><var class="product">RockZap</var> detects and reports ZAPs that are already applied.
Using
IMASPZAP or CMS ZAP, the user must inspect long CSECT dumps produced by
the ZAP utility in order to determine if the ZAP is already applied, or
simply in error.</li>

<li><var class="product">RockZap</var> allows the module name on all <var>NAME</var> statements to be overridden using the <var>MODULE</var> option.
This provides the ability to have the same set of <var>VER</var>s and <var>REP</var>s applied to different load modules without making global changes to the <var>NAME</var> statements.
</li>

<li><var class="product">RockZap</var> can "back out" or remove ZAPs without requiring
modification to the ZAP control statements.
By using the BACKOUT
option, ZAPs can be removed from the load module and replaced by the
original Verify data.</li>

<li><var class="product">RockZap</var> limits error reporting to the specific statements in error, and it
reports only the information necessary to diagnose and correct the
error.</li>

<li><var class="product">RockZap</var> only writes modified load modules.
If the ZAPs are already
completely applied, <var class="product">RockZap</var> does not write the load module back to disk.</li>

<li><var class="product">RockZap</var> enforces stricter rules on ZAP input statements.
Verify statements are required for all replaced bytes.
This ensures that the
load module contents are known before they are modified, and that a ZAP
can be removed or "backed out" if necessary.
You can override this feature,
however, using the <var>[[#* !NOVERIFY|* !NOVERIFY]]</var> statement.</li>
</ul>

==Differences between RockZap and IMASPZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> only modifies direct access load libraries.
<var class="product">RockZap</var> does not
modify PDSEs or any other types of direct access data sets.</li>

<li>The following SPZAP statements are not supported but are ignored
when encountered in the input stream: SETSSI, IDRDATA, and CHECKSUM.</li>

<li>The following IMASPZAP statments are not supported and will cause
<var class="product">RockZap</var> to terminate when they are encountered:
CONSOLE, ABSDUMP, ABSDUMPT, and RECORD.</li>
</ul>

==Differences between RockZap and CMS ZAP==
<ul>
<li><var class="product">RockZap</var> requires that every byte in the load module that is replaced
is also verified, unless the <var>* !NOVERIFY</var> statement is used.</li>

<li><var class="product">RockZap</var> does not support CMS LOADLIBs.</li>

<li>The following ZAP statements are not supported but are ignored
when encountered in the input stream: COMMENT and LOG.</li>
</ul>

==CMS installation==
<var class="product">RockZap</var> is distributed as a single load module in VMFPLC2 format.
A set of object decks is also included in case linkedit is required.
(This might be necessary for some older CMS versions).

[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

The <var class="product">RockZap</var> load module is linked <code>AMODE=31</code>.
If <var class="product">RockZap</var> must be relinked
on your system, use the following commands:
LOAD ROCKZAP (RESET ROCKZAP RMODE 24 AMODE 31
GENMOD ROCKZAP (FROM APPL

Note: You can omit the <var>RMODE</var> and <var>AMODE</var> parameters if you are running in a non-XA environment.


==IBM z/OS installation==
[[#downloading|Obtain]] and [[Web help download object files#How should the RockZap object file be linked?|link]] the <var class="product">RockZap</var> object file.

<code>ROCKZAP</code> can be copied to SYS1.LINKLIB or SYS1.LPALIB, and it is reentrant.

<div id="options"></div>
==RockZap options==
z/OS users supply <var class="product">RockZap</var> options in the <code>PARM</code> parameter of the EXEC job control statement.

For example, to force uppercase output and to
backout ZAPs, use the following EXEC statement:
//ROCKZAP EXEC PGM=ROCKZAP,PARM='UPPER,BACKOUT'


CMS users specify options following a left parenthesis on the <var>ROCKZAP</var>
command line.

For example, to force uppercase output and to backout the
ZAPs in the file <code>LOCAL ZAP A1</code>, specify the following:
ROCKZAP LOCAL ( BACKOUT UPPER


===BACKOUT===
The <var>BACKOUT</var> option removes a ZAP without requiring any modification to
the ZAP input statements.
<var>BACKOUT</var> reverses the effect of a ZAP by
replacing the original <code>Verify</code> data in the module.

If the ZAPs were applied with IMASPZAP, CMS ZAP, or with <var class="product">RockZap</var> using the <var>* !NOVERIFY</var> statement, <var class="product">RockZap</var> might not be able to perform a backout because all the original <code>Verify</code> data might not be present.

===EXTRACT filetype===
The <var>EXTRACT</var> option lets you extract individual object files from
a CMS text library.
<var>EXTRACT</var> can only be used when the <var>TXTLIB</var> option is also
specified.

<var>EXTRACT</var> requires a parameter that specifies the file type
of the object files it creates. One object file is created for each
member of the text library. The text library member name is used as the CMS file name.

===MODULE===
The <var>MODULE=modname</var> option allows the module name on each <var>NAME</var> statement to be overridden with a single load-module name. This means that you can use the same <var>ROCKZAP</var> jobstream to apply the same zaps to different load modules in the designated load library (SYSLIB) without making changes to any of the <var>[[#NAME|NAME]]</var> control statements.

For example, <code>PARM='MODULE=ONLINE'</code> applies the zaps to the module named <code>ONLINE</code> in the designated load library, regardless of the load-module name on each <var>NAME</var> statement. Then, using the same job stream, <code>PARM='MODULE=ONLINTST'</code> applies the same zaps to the module named <code>ONLINTST</code>, again, regardless of the load-module name on each <var>NAME</var> statement.

Note: If you are applying zaps to a <var class="product">Model 204</var> load module, you must specify a value for <var>MODULE</var>. 

The <var>MODULE</var> option was introduced in version 1.6 of <var class="product">RockZap</var>.

===REPORT===
Under the <var>REPORT</var> option, <var class="product">RockZap</var> runs normally but does not update any load modules. This is useful if you have a production load module you do not want to modify, but you do want to know whether or not a particular set of ZAPs are applied.

===TXTLIB txtlib===
The <var>TXTLIB</var> option is valid under CMS only.
<var>TXTLIB</var> specifies that the
ZAPs should be applied to a CMS text library instead of a load module.

You must provide the name of the text library following the <var>TXTLIB</var>
parameter.
The first parameter of the name statement (the module name)
is ignored when using the <var>TXTLIB</var> option.
Only the CSECT name is used for text libraries.
No load modules are inspected or modified when the
<var>TXTLIB</var> option is specified.

===UPPER===
The <var>UPPER</var> option forces all <var class="product">RockZap</var> output to uppercase.
This is usually unnecessary, except on certain Japanese terminals and
when sending output to uppercase-only printers.
<var>UPPER</var> is the default setting for Hitachi and Fujitsu systems.

==RockZap control statements==
<var class="product">RockZap</var> control statements appear in columns 1 to 72 in fixed length,
80 byte records.
Statements that begin with an asterisk are treated as
comments and are ignored, except for the two special inline parameter statements
<var>* !VERIFY</var> and <var>* !NOVERIFY</var>.
Control statements can begin in any column,
but line continuation is not allowed.

===VER===
The <var>VER</var> statement identifies a range of bytes to be matched with the
load module contents.
<var>VER</var> statements must follow a <var>NAME</var> statement.
A <var>VER</var> statement must be present for each range of bytes that will be
replaced in the load module.
This is to ensure that the ZAP can be backed out later if necessary.

The format of the <var>VER</var> statement is:
VER offset verify-values comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT specified in the previous <var>NAME</var> statement, or from the start of the load module if no CSECT was specified.</td></tr>

<tr><th nowrap>verify-values</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values are the expected contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">verify-values</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>VER</var> statements:
VER 00 010203,040506 Verify bytes at offset 0.

VER 01ca 47f0,c0e9

VER 23EC D20310004000,90ECD000,07FC


===REP===
The <var>REP</var> statement identifies a range of bytes to replace the current
contents of a load module.
The <var>REP</var> statement must be preceded by <var>VER</var>
statements that cover the entire range of bytes that will be replaced.

The format of the <var>REP</var> statement is:
REP offset replace-value comments

Where:
<table>
<tr><th>offset</th>
<td>The hexadecimal displacement from the start of the CSECT in the previous <var>NAME</var> statement.</td></tr>

<tr><th nowrap>replace-value</th>
<td>Pairs of hexadecimal characters optionally separated by commas. The values will replace the contents of the load module at the specified offset. Uppercase or lowercase hexadecimal data are acceptable.</td></tr>

<tr><th>comments</th>
<td>Any characters after the first blank after the last <var class="term">replace-value</var> character are ignored by <var class="product">RockZap</var>.</td></tr>
</table>

The following are all valid <var>REP</var> statements:
REP 00 FFFFFF,FFFFFF Replace bytes at offset 0.

REP 01ca 47f0,c0e8

REP 23EC D203101C4000,90ECD008,07FE


===NAME===
The <var>NAME</var> statement identifies a load module, and optionally a CSECT, that defines the context for the <var>VER</var> and <var>REP</var> statements that follow.
<var>NAMEX</var> is a synonym for <var>NAME</var> that allows compatibility with the Fujitsu
OSIV ZAP utility.

The format of the <var>NAME</var> statement is:
NAME module [csect]

Where:
<table>
<tr><th>module</th>
<td>The name of the load module. Under CMS the filetype must be <var>MODULE</var>. Under z/OS this is the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section in the load module. A <var class="term">csect</var> value is optional. If the CSECT name is missing, subsequent verify and replace displacements are calculated from offset 0 in the load module.</td></tr>
</table>

Note: You can use the <var>[[#MODULE|MODULE]]</var> parameter to override the module name in <var>NAME</var> statements. 

===DUMP or DUMPT===
The <var>DUMP</var> statement prints all or part of the contents of a load
module or CMS text library to SYSPRINT.
Specifying <var>DUMPT</var> has the same effect as <var>DUMP</var>.

The format of the <var>DUMP</var> or <var>DUMPT</var> statement is:
DUMP[T] name [csect [offset [length]]]

Where:
<table>
<tr><th>name</th>
<td>The name of the load module or text library. Under CMS, specify the filename (only) of a file whose filetype must be <var>MODULE</var> or <var>TXTLIB</var>. Under z/OS, specify the name of a PDS member in the load library.</td></tr>

<tr><th>csect</th>
<td>The name of the control section. A <var class="term">csect</var> value is optional. If the CSECT clause is missing, the entire load module or text library contents are dumped.</td></tr>

<tr><th>offset</th>
<td>The hexadecimal starting offset within the CSECT. This is optional, and it can only be specified when a <var class="term">csect</var> name is specified. Use the <var class="term">offset</var> parameter when you want to dump only a part of a CSECT. If the offset is omitted, it defaults to 0.</td></tr>

<tr><th>length</th>
<td>The number of bytes (in hexadecimal) of the CSECT to dump. This is an optional parameter, and it can only be specified if a <var class="term">csect</var> value and starting <var class="term">offset</var> value are specified.</td></tr>
</table>

===* !VERIFY===
The special statement <var>* !VERIFY</var> (and <var>* !NOVERIFY</var>) lets you control whether individual ZAPs are verified before being applied.

The main purpose of these statements is to override whether the current portion of the zap requires verify data. This can be useful when a single ZAP in an input stream containing many ZAPs has no verify data.

The asterisk and space are necessary so that other ZAP utilities treat
the statements as comments.

Use <var>* !VERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !VERIFY</var> statement are verified (the <var>VER</var> data must match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
 Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use
the <var>* !NOVERIFY</var> statement instead, and only when needed. 

===* !NOVERIFY===
The special inline statement
<var>* !NOVERIFY</var> (and <var>* !VERIFY</var>) lets you control
whether individual ZAPs are verified before being applied.
The main purpose of these statements is to override whether the current
portion of the zap requires verify data.
This can be useful when a single ZAP in an input stream containing many ZAPs has no verify
data or the verify data is known to be incorrect.

Use <var>* !NOVERIFY</var> anywhere within the ZAP input stream.
ZAPs following the <var>* !NOVERIFY</var> statement are not verified (the <var>VER</var> data may be missing or not match the module contents) before the ZAP is applied.

Since the <var>* !NOVERIFY</var> statement is new in <var class="product">RockZap</var> version 1.6, you might have <var class="product">RockZap</var> JCL or
EXECs that use the <var>NOVERIFY</var> program option to accomplish this purpose, but at
a dangerous job step level.
Note: It is strongly recommended that you not use the <var>NOVERIFY</var> program option, but do use the <var>* !NOVERIFY</var> statement instead, and only when needed. 

==Using RockZap under z/OS==
Job Control requirements for <var class="product">RockZap</var> are the same as for IMASPZAP. Most <var class="product">RockZap</var> storage is allocated above the 16 megabyte line, so the default region size should be sufficient.

===RockZap DD statements===
Required statements:
<ul>
<li>SYSLIB points to the load library PDS (Partitioned Data
Set) containing the load module you want to ZAP. The load library cannot be a PDSE (Partition Data Set Extended) dataset.</li>

<li>SYSIN contains the ZAP control statements and must
have the DCB attributes of <code>RECFM=F</code> or <code>RECFM=FB</code>, and <code>LRECL=80</code>.</li>

<li>SYSPRINT is the report data set.</li>
</ul>

===RockZap sample JCL===
//ROCKZAP JOB CLASS=A,MSGCLASS=A
//ZAP EXEC PGM=ROCKZAP,PARM='RockZap parms'
//STEPLIB DD DSN=ROCKZAP.V106.LOAD,DISP=SHR
//SYSLIB DD DSN=loadlib,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
zap control statements
/*


==Using RockZap under CMS==
The format of the <var>ROCKZAP</var> command is:
ROCKZAP fn [ft [fm]] ( options


<var class="product">RockZap</var> is invoked as a CMS command.
Simply enter <code>ROCKZAP</code> followed by the
name of the input file.
The default filetype is <code>ZAP</code>, and the
default filemode is <code>*</code>.

Options are supplied in any order following the left parenthesis.
See [[#options|RockZap options]] for a list of options.

<var class="product">RockZap</var> writes the report and any modified load modules to the disk
accessed as the "A" disk.
Make sure that the "A" disk is accessed in Read/Write mode.

===Using RockZap with CMS text libraries===
When <var class="product">RockZap</var> processes a text library, the resulting text library or object files usually contain fewer records than the original.
No information is lost and the
resulting text library or object file is logically the same as the original.
Text records in the object file are always written with the maximum amount of object code
per record. Often, fewer records are required than are typically written by the
compiler or assembler that originally generated the object.

This object file "normalization" is similar to how a linkage editor processes an object
file.
<var class="product">RockZap</var> performs this normalization so that ZAPs can be applied more efficiently.

==RockZap return codes==
<table class="thJustBold">
<tr><th>0</th>
<td>ZAPs were processed successfully. Any modified load modules are written back to disk.</td></tr>

<tr><th>4</th>
<td>ZAPs were processed successfully, but one or more warning messages were produced. This usually indicates a CSECT was missing from one or more of the load modules. Check the <var class="product">RockZap</var> report for the name of the module and CSECT. If any load modules were modified, they are written back to disk.</td></tr>

<tr><th>8</th>
<td>One or more errors occurred. Check the <var class="product">RockZap</var> report for details.</td></tr>

<tr><th>12</th>
<td><var class="product">RockZap</var> was unable to open the input file. Make sure the filename is correct and that the file or PDS member is present.</td></tr>

<tr><th>40</th>
<td><var class="product">RockZap</var> could not open the report file (SYSPRINT). For z/OS, make sure a DD statement for SYSPRINT is present. For CMS, the internal FILEDEF for SYSPRINT may have failed. Make sure the "A" disk is accessed in read/write mode.</td></tr>
</table>

==Deprecated options==
The following program options are no longer necessary.
It is recommended
that you not use them, and that if you discover them in old JCL or EXECs,
you correct them to use the newer recommended approaches.

===NOVERIFY===
The <var>NOVERIFY</var> option lets you apply ZAPs that have no verify data.
Use the <var>NOVERIFY</var> option with caution.
Once a ZAP is applied using <var>NOVERIFY</var>,
the original contents of the load module are lost.

Note: Since the <var>* !NOVERIFY</var> statement can provide the functionality needed for applying a portion of a zap without verify data, it is strongly recommended that you not use the <var>NOVERIFY</var> option, which might extend to other portions of the zap with incorrect verify data.


===VERIFY===
The <var>VERIFY</var> option ensures that all replace data has been successfully
verified before updating the load module.
<var>VERIFY</var> is a <var class="product">RockZap</var> default, and it need not be specified.

Note: Since it is recommended that you do not use the <var>NOVERIFY</var> option, you might want to avoid the <var>VERIFY</var> option as well, thus eliminating any tendency to control requirement of verify data at the job step level.


[[Category:RKTools]]

EDIT command

2022-01-26T22:31:40Z

Tom: /* Editor commands */

==Summary==
<dl>
<dt>Privileges
<dd>Any user
<dt>Function
<dd>Invokes the <var class="product">Model 204</var> full-screen editor or line editor
</dl>

==Syntax==
EDIT
[({TERMINAL [SCREEN | LINE] | SCREEN [TERMINAL] | LINE [TERMINAL]})]
[procnumber1 [,procnumber2 | ,procname1]
| [procname1 [,procname2 | ,procnumber1]]


Where:
<table>
<tr><th>procnumber1</th>
<td>The number of an existing procedure. One of these:
<ul>
<li>A temporary procedure (a negative number or zero).</li>

<li>A permanent procedure. </li>
</ul>
If neither <var class="term">procnumber1</var> nor <var class="term">procname1</var> is specified, <var class="product">Model 204</var> creates a temporary procedure (0).</td></tr>

<tr><th>procnumber2</th>
<td>The number of a new temporary procedure (a negative number or zero).
</td></tr>

<tr><th>procname1</th>
<td>If specified after <var class="term">procnumber1</var>, the name under which the procedure is saved after editing. See [[#Procedure names|Procedure names]], below, for naming rules.

If specified immediately after <code>EDIT</code>, this is the name of an existing temporary or permanent procedure to be used as input for the current editing session.</td></tr>

<tr><th>procname2</th>
<td><var class="term">procname2</var> is the name of a new procedure (1 to 255 characters). See [[#Procedure names|Procedure names]], below for naming rules. </td></tr>
</table>

===Syntax notes===
You invoke the Full Screen Editor by entering:
EDIT (SCREEN) name


where <var class="term">name</var> identifies the procedure to be edited. If this is entered from a line-at-a-time terminal, however, an error message is issued stating that a full-screen terminal is required. You invoke the Line Editor by entering:
EDIT (LINE) name


If neither <var>SCREEN</var> nor <var>LINE</var> is specified, <var class="product">Model 204</var> invokes the appropriate Editor for your terminal type.

===Procedure names===
The name of a new procedure may contain any letters, numbers, or symbols except:
<table>
<tr class="head"><th>Character name </th>
<th>Keyboard display</th> </tr>

<tr> <th><var>Carriage return</var></th>
<td></td> </tr>

<tr> <th><var>Comma </var></th>
<td>( , ) </td> </tr>

<tr> <th><var>Equal sign </var></th>
<td>( = )</td> </tr>

<tr> <th><var>Semicolon </var></th>
<td>( ; )</td> </tr>

<tr> <th><var>Single quote </var></th>
<td>( ' )</td> </tr>

<tr> <th><var>Space</var></th>
<td></td> </tr>
</table>

In addition: 
<ul>
<li>In version 7.6 and earlier, the procedure name cannot begin with a zero or a minus sign.</li>

<li>As of version 7.7:
<ul>
<li>Most of the above characters are permitted if <var>CUSTOM=42</var> is turned on. Names containing special characters must be enclosed in single quotes for all procedure commands. See [[CUSTOM parameter#Using CUSTOM=(42)|Using CUSTOM=(42)]] for details.</li>

<li>The procedure name can begin with a zero. And the procedure name "0123" is different from the procedure name "00123".

However, names with only zeroes are treated as temporary procedure 0, so <code>E 000</code> is identical to <code>E 0</code>. </li>

<li>Alphanumeric procedure names can begin with a minus sign character (<tt>-</tt>), which is interpreted as a hyphen. For example, <code>-1myproc</code> and <code>-myproc</code> are valid procedure names.

Numeric procedure names that begin with a minus sign are treated as temporary procedures, and leading zeroes after the minus sign are ignored if they are followed by a non-zero digit (<code>E -1</code> is identical to <code>E -001</code>). </li>
</ul></li>
</ul>

While procedure names up to 255 characters are technically valid, very long names will create challenges in maintaining the procedures due to the procedure name needing to fit on the same line as commands that reference the procedure. Rocket recommends keeping procedure names shorter than 210 characters. 
Note: [[SirLib]] users must keep procedure names shorter than 229, and even then, SirPro will not be able to display procedure names longer than the supported screen width.


==Examples==
EDIT
EDIT (SCREEN) PROC1
EDIT XUPDTE
EDIT -1


==Usage notes==
<ul>
<li>The <var>EDIT</var> command invokes either the Full Screen Editor or the Line Editor. <var>EDIT</var> can optionally specify the name or number of an existing procedure to be edited, and can specify a new name or number for the edited procedure. Specifying 0 or a negative number edits a temporary procedure. If no name or number is supplied, temporary procedure 0 is assumed.</li>

<li>You can invoke either of the <var class="product">Model 204</var> Editors from within a procedure and have the Editor go directly to your terminal for input. Entering the following command directs an editing session to your terminal:
EDIT (TERMINAL) procname
</li>

<li><var class="product">Model 204</var> selects either the Full Screen Editor or the Line Editor for the user running the procedure. The Editor reads input from the terminal until you end the session with an <var>END</var>, <var>GO</var>, or <var>QUIT</var> command. If <var>END</var> or <var>QUIT</var> is entered, <var class="product">Model 204</var> reads the next line of input from the procedure containing the <var>EDIT</var> command. If <var>GO</var> is entered, <var class="product">Model 204</var> reads the next line of input from the edited procedure, as if the <var>EDIT</var> command were followed by an <var>INCLUDE</var> command.</li>

<li>The <var>TERMINAL</var> option can be combined with the <var>SCREEN</var> or the <var>LINE</var> option. If an <var>EDIT (SCREEN)</var> command is issued from within a procedure, <var class="product">Model 204</var> displays a message that the <var>SCREEN</var> option requires the <var>TERMINAL</var> option. If an <var>EDIT</var> command without the <var>TERMINAL</var> option is issued within a procedure, the line editor is invoked. It reads editor commands from the invoking procedure. Including the <var>TERMINAL</var> option in an <var>EDIT</var> command issued from the terminal has no effect on the operation of the <var>EDIT</var> command.</li>

<li>When it processes <var>EDIT</var> against a permanent procedure, <var class="product">Model 204</var> ends any update unit in progress and begins a non-backoutable update unit. For more information about <var class="product">Model 204</var> update units, see [[File integrity and recovery]].</li>
</ul>

==Editor commands==

The following tables summarize the available full-screen editor and line editor commands. In all commands that refer to procedure name (procname), a procedure number can be specified to refer to a temporary procedure. For more information, see the [[:Category: Model 204 editor|Model 204 editor]] topics.
<table>
<caption> Full Screen Editor commands </caption>
<tr class="head"><th>Command</th>
<th>Action</th></tr>

<tr> <th><var>[+] n</var></th>
<td>Scrolls forward n lines in a procedure.</td> </tr>

<tr> <th><var>-n</var></th>
<td>Scrolls backward n lines in a procedure.</td> </tr>

<tr> <th><var>=</var></th>
<td>Repeats the command most recently executed.</td> </tr>

<tr> <th><var>[SET] ARBCHAR [OFF]</var></th>
<td>Sets an arbitrary (wild) character for search string.</td> </tr>

<tr> <th><var>BACKWARD</var></th>
<td>Scrolls backward n screens in a procedure.</td> </tr>

<tr> <th><var>BOTTOM</var></th>
<td>Scrolls to last line of a procedure.</td> </tr>

<tr> <th><var>CLEAR</var></th>
<td>Clears the prefix area, aborts pending prefix commands, and cancels any specified targets.</td> </tr>

<tr> <th><var>[IN filename] END [procname]</var></th>
<td>Exits from the Editor and saves the edited procedure.</td> </tr>

<tr> <th><var>{SET] FILL {NULL | BLANK}</var></th>
<td>Sets a fill character.</td> </tr>

<tr> <th><var>FORWARD</var></th>
<td>Scrolls forward n screens in a procedure.</td> </tr>

<tr> <th><var>[IN filename] GET procname</var></th>
<td>Inserts a saved procedure in the procedure being edited.
</td> </tr>

<tr> <th><var>[IN filename] GO [procname]</var></th>
<td>Exits from the Full Screen Editor, saves the edited procedure, and includes the procedure.</td> </tr>

<tr> <th><var>[SET] LINEND {OFF | char}</var></th>
<td>Sets the line-end character.</td> </tr>

<tr> <th><var>[-] LOCATE /string [[IN] RANGE]</var></th>
<td>Locates the specified string in a procedure</td> </tr>

<tr> <th><var>[SET] PREFIX {RIGHT | LEFT}</var></th>
<td>Controls the position of the prefix area on the screen.
</td> </tr>

<tr> <th><var>QUIT [QUIT] </var></th>
<td>Exits from the Editor; does not save the edited procedure.
</td> </tr>

<tr> <th><var>[SET] REPEAT {OFF | char}</var></th>
<td>Sets the repeat character for search strings.</td> </tr>

<tr> <th><var>REPLACE /string1/string2/ [n |*] [VERIFY] [[IN] RANGE]</var></th>
<td>Locates and replaces the specified string in a procedure.
</td> </tr>

<tr> <th><var>[IN filename] SAVE [procname] [[IN] RANGE] 
</var></th>
<td>Saves the edited procedure. </td> </tr>

<tr> <th><var>[SET] SCALE {OFF | ON}</var></th>
<td>Controls the display of the column scale on the screen.
</td> </tr>

<tr> <th><var>TOP</var></th>
<td>Scrolls to the first line of a procedure. </td> </tr>
</table>


The table below lists the Line Editor commands. 
<table>
<caption>Line Editor commands</caption>
<tr class="head"><th>Command</th>
<th>Action</th> </tr>

<tr> <th><var>[n] (commands)</var></th>
<td>Repeats a series of commands n times.</td> </tr>

<tr> <th><var>[n] C</var></th>
<td>Moves the pointer n characters right or left in the procedure.
</td> </tr>

<tr> <th><var>[n] D</var></th>
<td>Deletes n characters in the procedure.</td> </tr>

<tr> <th><var>[procname] END</var></th>
<td>Exits from the Line Editor and saves the edited procedure.
</td> </tr>

<tr> <th><var>[procname] GO</var></th>
<td>Exits from the Line Editor, saves the edited procedure, and includes the procedure.</td> </tr>

<tr> <th><var>[procname] I</var></th>
<td>Combines procedures.</td> </tr>

<tr> <th><var>I/string/</var></th>
<td>Inserts a string before the current pointer.</td> </tr>

<tr> <th><var>[n] J</var></th>
<td>Initializes the pointer at the first character in a procedure or moves it forward or backward n lines.</td> </tr>

<tr> <th><var>[n] [H] K</var></th>
<td>Deletes n lines from the procedure.</td> </tr>

<tr> <th><var>[n] L</var></th>
<td>Moves pointer n lines forward or backward in the procedure.
</td> </tr>

<tr> <th nowrap><var>[n] R/string1/string2/</var></th>
<td>Replaces a specified string in the procedure.</td> </tr>

<tr> <th><var>[n] S/string/</var></th>
<td>Searches for an occurrence of a specified string in the procedure.</td> </tr>

<tr> <th><var>[n] [H] T</var></th>
<td>Displays a portion of the procedure being edited.</td> </tr>

<tr> <th><var>Xline</var></th>
<td>Replaces a line in the procedure.</td> </tr>

<tr> <th><var>Yline</var></th>
<td>Inserts a line before the line at which the pointer is positioned.</td> </tr>

<tr> <th><var>Z</var></th>
<td>Positions the pointer after the last character in the procedure. </td> </tr>
</table>

[[Category: User commands]]
[[Category:Commands]]

WebSocket (Socket function)

2019-12-10T19:35:26Z

Tom: /* Usage notes */

{{Template:Socket:WebSocket subtitle}}

This page is [[under construction]].
==Syntax==
{{Template:Socket:WebSocket syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%Socket</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.

The WebSocket method initiates 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}}

WebSocket (Socket function)

2019-12-10T18:25:05Z

Tom: /* Syntax terms */

{{Template:Socket:WebSocket subtitle}}

This page is [[under construction]].
==Syntax==
{{Template:Socket:WebSocket syntax}}
===Syntax terms===
<table class="syntaxTable">
<tr><th>%Socket</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}}