Release notes for Model 204 version 7.7
These release notes list the enhancements and other changes contained in Model 204 version 7.7.
******THIS IS A DRAFT DOCUMENT.******
These release notes list the enhancements and other changes contained in Model 204 version 7.7, 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.7 release. Before beginning your installation, please read through this information about product installation and changes.
New features
Long password support
Logon passwords, maintained in CCASTAT, can now contain as many as 127 characters.
This feature includes support for:
- LOGON command
- LOGONCP command, used to change a password
- LOGCTL C USERID command
- $Sir_Login function
- Mixed-case passwords (if the CUSTOM parameter includes the value 11)
- CCASTAT data sets created with or without password expiration support
- Long passwords (password phrases) for use with the external security interfaces: ACF2, RACF, or TOPSECRET
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.
Large checkpoint data sets
Support is added for large data sets (as many as 16 million tracks) for the Model 204 Checkpoint facility CHKPOINT or CHKPNTS data sets. For details, see ROLL BACK processing, Pass 2.
Operating system and hardware requirements
Operating system requirements
- IBM z/OS
- Versions supported: z/OS version 1.07 through 2.2.
- zHPF support requires version 2.1.
- Large (1 MB) page support requires version 1.9.
- Extended address volumes (EAV) requires version 1.12.
Version 1.07 is sufficient for all functionality except for the following features:
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, contact Technical Support. - IBM z/VM
- Versions supported: z/VM version 5.4 through 6.3.
- IBM z/VSE
- Versions supported: z/VSE version 5.1 and 5.2.
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:
- large (1 MB) page support
- IBM's High Performance FICON (zHPF) support
Model 204 compatibility with operating systems
For information on Model 204 certification with IBM operating systems, see Model 204 system requirements.
SOUL (User Language) enhancements
New and changed classes and methods
New exception class: Write Error
WriteError exceptions are thrown by the Close, WriteBlock, WriteRecord, and WriteRecords methods in the Dataset class if they encounter a full output Dataset object.
New default certificate-signing algorithm
Janus Network Security as well as the StringList methods AppendSignedCertificate and AppendSignedClientCertificate 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:
| Method | Description |
|---|---|
| SHA384digest | SHA-384 digest |
| SHA512digest | SHA-512 digest |
New LoadMsgctl method
The new LoadMsgctl method lets you view what Model messages have been affected by MSGCTL commands. The method also displays the current attributes of those messages.
In addition, to better understand the effect of the MSGCTL command, the RKTools SIRIUS file will contain a procedure you can use to display the MSGCTL commands that have been specified in the Online session.
New DigestAlgorithm values
Values SHA384 and SHA512 are added to the DigestAlgorithm enumeration.
Method variable invocation
Method variables can now be invoked using %var() or %obj:var(), as in JavaScript.
X509CertificateToXmlDoc method support for unknown elements
A certificate's <RelativeDistinguishedName> element can contain a wide variety of attributes that X509CertificateToXmlDoc 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 <unknown> elements with an <ObjectIdentifier> element that indicates the ASN.1 object identifier.
Note: You are advised not to refer to such an <unknown> element in your programs, since future updates to the X509CertificateToXmlDoc 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, contact Rocket Software technical support.
Resulting element length in "ToXmlDoc" String methods
Prior to version 7.7 of Model 204, the DerToXmlDoc, X509CertificateToXmlDoc, X509CrlToXmlDoc, and RSAPrivateKeyToXmlDoc methods failed if input to them created any element in the result XmlDoc 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.
New XHTML entities for square-bracket characters
[ and ] are newly supported as XMHTL entities (notably in the U method). This provides a better approach to specifying square brackets (such as for XPath expressions) than the formerly recommended use of Static %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:
*/pers[@name="Hector"]
Code like this was recommended under version 7.5 of Model 204:
%lsq is string len 1 static initial('['):u %rsq is string len 1 static initial(']'):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 (-), which is interpreted as a hyphen. For example, 00123, -1myproc, and -myproc are valid procedure names.
See the PROCEDURE command for details.
Assert statement support for Info expressions
The SOUL Assert statement allows the optional parameter Info to provide additional output information. As of version 7.7, the Info 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 Assert failure.
A simple example is:
assert %x gt 0, info ('abc' with 'def')
Note: This enhancement introduces a slight backward incompatibility: An Assert statement like assert %x gt 0, info ( whose Info value begins with an opening parenthesis but has no closing parenthesis compiled without error prior to version 7.7. From 7.7 on, such a statement produces a compilation error because the compiler expects an expression after the open parenthesis.
Janus product enhancements
Janus Network Security ciphers and private keys
Support for certificates signed using 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 Janus Network Security application as well as its associated and related methods, including:
Janus Web Server rules
The following changes have been made in version 7.7:
- Janus Web used to automatically implement 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.
- You can now specify a method name in the command for a JANUS WEB ON rule. See JANUS WEB ON (method name substitution) for details.
- The automatic JANUS WEB ALLOW rule, which allowed any user to access the port without requiring a login, is changed to the following to force login for any URL on a Janus Web port:
JANUS WEB portname ALLOW * USER *
This rule applies, in version 7.6 (by zap maintenance) and in version 7.7, unless overridden by user-added rules. - As described below in JANUS WEB (additional rule support), the JANUS WEB command ALLOW and DISALLOW rules are updated to include support for RESTful and WebDAV HTTP methods.
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 Authorization and WWW-Authenticate headers.
Fast/Unload enhancements
Integration of Fast/Unload with the Online load module
Starting with version 7.7 of Model 204, Fast/Unload is entirely linked with the Model 204 Online load module, maintenance zaps applied to the Online load module will include all Fast/Unload maintenance, and the version number of Fast/Unload is the same as the version number of Model 204.
Previously (for all versions of Fast/Unload through version 4.7), the standalone FUNLOAD load module was downloaded and linked separately and independently from Model 204.
zIIP exploitation
If you have an authorization zap that contains the base zIIP support product of Model 204 and contains the Fast/Unload HPO product, your standalone PGM=FUNLOAD jobs will run on a zIIP processor, if one is available. See Fast/Unload HPO.
New #VIEW function
The #VIEW204 function returns the value of the Model 204 parameter you specify as an argument.
PUT statement enhancements
Length prefix for PUT output values
New PUT statement syntax is added to insert a one-byte or two-byte binary integer, containing the byte length of a PUT value, in the output stream before the value.
This addition provides better readability and lower CPU cost than the techniques currently used to achieve the same result.
COUNTED keyword for AS clause
The AS clause of a PUT statement will now allow the COUNTED keyword:
... PUT info .. AS [type] COUNTED[1|2]
For example, PUT FIRST.NAME AS COUNTED2 puts the first occurrence of field FIRST.NAME as a string value, preceded by a two-byte binary integer containing the length of that occurrence.
This feature will allow FUEL code such as the following:
%VAL = ITEM.CODE(%OCC) %LEN = #LEN( %VAL ) PUT %LEN AS FIXED(2) PUT %VAL
To be replaced by the more readable and more efficient:
PUT %VAL AS COUNTED2
#function as PUT "info" argument
New in this version, a #function call is allowed as the PUT info 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 #STRIP lets you designate a #STRIP first-argument value to be nullified. That is, when the value of the first argument is equal to the value of the fourth argument, #STRIP 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 COUNTED option for PUT, because a length-prefixed format allows a reliable, unambiguous representation of a series of null strings.
Combining the new fourth argument, the new COUNTED option, and the new 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
LK, N, and P strip-type options are added to the #STRIP function:
- The new LK option lets you strip leading zeroes from numeric value output.
LK, together with other new Fast/Unload PUT 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 by the more readable and efficient:
PUT #STRIP(ITEM.NUMBER(%OCC), 'LK', '0', '_') AS COUNTED2
- The new N option prevents leading-character stripping, trailing-character stripping, or both.
For an example, see New #STRIP fourth argument, above.
- The new P option strips all but one leading pad-argument characters from the #STRIP first argument returned value, if that value contains a non-zero length string of only pad characters.
P, together with other new Fast/Unload PUT features, provides a simpler alternative to FUEL code such as the following, which outputs a numeric value with leading zeroes stripped:
%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 by the more readable and efficient:
PUT #STRIP(ITEM.NUMBER(%OCC), 'P', '0', '_') AS COUNTED2
Note: A FUEL IF statement oddity is that the precedence of AND and OR are the same.
New and changed commands
DISPLAY MODMAP (new parameter: UEX)
The DISPLAY MODMAP command now has a UEX parameter that displays the entry point addresses of all defined user exits.
FREE command
The FREE command now indicates success or failure with the following messages:
M204.0509: No action taken by FREE command; ddname not allocated M204.0510: FREE command successful; ddname freed
JANUS DEFINE (new parameter: SSLTRUST)
The JANUS DEFINE command now has an SSLTRUST 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)
The JANUS WEB command ALLOW/DISALLOW rules are updated to include support for these HTTP methods:
- The RESTful (Representational State Transfer) methods CONNECT, DELETE, OPTIONS, PATCH, and TRACE.
- The WebDAV (Distributed Authoring and Versioning) methods PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, and UNLOCK.
JANUS WEB ON (method name substitution)
You can now specify a method name in the command for a JANUS WEB ON rule. To do this, specify an M after the escape (") character, as in:
JANUS WEB WEBPORT ON /TEST/* OPEN FILE TEST CMD 'I "M.*'
A GET request for URL /test/foo would result in the file TEST being opened and the command I GET.FOO being issued. A POST for the same URL would result in the command I POST.FOO being issued.
Note: This behavior is a change from past releases, when "M was simply converted to M.
LOGINCP or LOGONCP (new)
Because colons are now valid password characters, the LOGINCP (LOGIN and Change Password) command replaces the former technique for changing passwords using LOGIN.
Before version 7.7, with LOGIN, you specified oldpassword:newpassword in response to the M204.0347: Password prompt.
With the LOGINCP 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
LOGONCP is a synonym for LOGINCP.
ZHPF (new parameters: filename and *)
The ZHPF command checks zHPF ability for the file currently opened by the user.
As of Model 204 7.7, you can specify parameters to ZHPF:
- filename, to check a specific file
- An asterisk (*), to check local files opened by all users
New and changed parameters
CUSTOM (new values)
The following values have been added to the CUSTOM parameter in this release:
- The CUSTOM=23 value always truncates the userid to 10 characters.
- The CUSTOM=41 value allows recording of data on successful RACF user logins. The login data is shown in RACFRW batch reports.
- The CUSTOM=42 value allows the editing of procedure names containing the following special characters: comma, equal sign, space, single quote, semicolon.
LFSCB (new default/minimum value)
The default (and minimum) value of LFSCB is now 8 bytes.
LITBL (new default/minimum value)
The default (and minimum) value of LITBL is now 8 bytes.
MINDEBCL (new)
The new system parameter, MINDEBCL, 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 MP/204 Online, the MPDELAY and MPDELAYZ 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, setting NUMBUFG greater than 0 in version 7.7 forces NUMBUF to 0 (no buffer pool buffers reside below the bar). Not setting NUMBUFG 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 SCHDOFL and SCHDOFLZ is 0. Before Model 204 7.7, their minimum allowed value was 1.
SCHDOFLS (new)
For z/OS system customers using Model 204 zIIP support, the new SCHDOFLS system parameter helps you to regulate the zIIP processor workload.
SCHDOFLS specifies both of the following:
- The target number of threads on the zIIP offload queue before a non-SRB MP subtask is dispatched to help the zIIP subtasks.
- If started, how aggressively non-SRB MP subtasks pick up work from the zIIP offload queue.
This parameter applies to z/OS only.
SCHDOPT (change to X'20' bit processing)
The SCHDOPT 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, 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 SCHDOFLZ*AMPSUBZ.
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 SERVSIZE is changed from zero to 65536. If SERVSIZE 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 SERVSIZE was not set but was 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.
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 NUMBUFG parameter greater than 0) will force all buffer pool buffers above the bar — no below-the-bar buffers will exist. In this case, the NUMBUF and MINBUF parameters will be forced to 0, and the other parameters that affect BTB storage (MAXBUF, SPCORE, LDKBMWND, and NLRUQ) will be ignored.
If you set NUMBUFG 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.
These limits are increased to 4095 per request:
- The total number of images for all blocks (formerly 256)
- The maximum number of menus and screens combined (formerly 256)
Statistics enhancements
BLKO
The performance statistic BLKO now reports invisible users as 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 MONITOR command, the QUE column now reports BLKO instead of OFFQ for invisible users and displays new values OFFO and OFFI. OFFO is invisible and blocked out; OFFI is invisible and blocked in. BLKO now means blocked out and on some queue. BLKI now means blocked in and on some queue.
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 LOUTPB value for 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, LOUTPB was automatically reset to the limit that supported back-paging.
Back-paging will now be disabled for any terminal with a MODEL 6 screen geometry that requires more than 6142 bytes.
ECF calls to the IBM IDCAMS utility
The new IDCAMS option for the External Module 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
If the new system parameter ECPRIV 4 bit is set, the job invoked by a privileged External Call Facility statement runs under the job's external authorizer (ACF2, RACF, or Top/Secret) profile, rather than that of the user that invoked an External Call.
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, Debugger build 64, the most recent version of the Debugger Client sends its build and tag number to the mainframe, and this information is displayed in message MSIR.1077.
This information is not sent if the Debugger Client build number is less than 64.
Enforcing use of a minimum version of the Debugger Client
A new system parameter, MINDEBCL, lets you specify the minimum build number of a Debugger Client that can be used with an Online. Normally, when you use the TN3270 or Janus Debugger, no restrictions are placed on which version of the Debugger workstation client is used. Versions of the Client are identified by a build number, which is displayed in the Audit Trail tab when the client starts:
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.
On Debugger Client build 65 and higher, you can also get the build number from the Client function &&buildNumber().
Build 64 (and higher) of the Debugger Client transmits its build number to the mainframe side when a debugging session is initiated. The mainframe side uses this information to construct the MSIR.1077 message:
MSIR.1077: Begin debug session, user 3, client: Build: 65, Tag: 1 (Janus debugger session)
Since Client builds before 64 do not transmit their build number, the mainframe side views all Client versions prior to build 64 as build 63.
If you set MINDEBCL to a positive value and try to use a version of the Debugger Client whose build number is less than MINDEBCL, you see the following error on the Audit Trail (and on the terminal if you are using TN3270 DEBUG ON):
MSIR.1079: Debugger Client Build: xx < MINDEBCL: yy debugger client connection refused
The debugging session is rejected. An error message is also shown by the Client.
Debugger Client Build 65
Shortly after the GA release of Model 204 7.7, Build 65 of the Debugger Client will be released. It has better error message display for various connection errors and also for MINDEBCL violations. Although earlier Client builds work fine with Model 204 7.7 and MINDEBCL, you are encouraged to upgrade to Build 65 when it is released to get the improved error reporting. Build 65 also will work fine with Model 204 releases prior to 7.7.
Compatibility issues
APSYPAGE parameter cannot be non-zero
(Applies to the IBM z/OS system.)
The APSYPAGE parameter was disabled (but still allowed) in version 7.6. As of version 7.7, if APSYPAGE 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 APSYPAGE.
Unlabeled FDV statement compilation errors
Version 7.7 introduced 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
- KU is no longer 4K addressable from KOMM. It has been relocated to KOMM+1100 and must be addressed using grande (‘G’) instructions.
- KHEOC has been renamed to KGEOC.
- KUUSRNO has been renamed to KBUSRNO.
- 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 usingL R1,KUPVT.
As of version 7.7, that reference would requireLG R1,KUGVT.
For context, see Converting user-written functions.
JANUS WEB ON -- "M substitution
In the command for a JANUS WEB ON rule, "M can now be used to specify a method name.
This behavior is a change from past releases, when "M was simply converted to M. See JANUS WEB ON (method name substitution) for details.
IODEV=37 is no longer supported
Line-at-a-time terminals used on IBM z/OS via the IBM Network Terminal Option (2741s, teletypes, and teletype-compatibles) are no longer supported.
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.
New and updated messages
See New and updated messages in Model 204 version 7.7 for details.