Sirius Mods Version 7.1

Supported Model 204 Versions

All or Multiple Products

Mixed case options for $Field_*

The $Field_Image, $Field_List, and $Field_ListI functions now allow the options argument to be specified in any combination of uppercase or lowercase letters.

Argument name provided on request cancellation messages

Many internal Sirius methods (that is, those in the System namespace) provide an error message if an argument is invalid. Previously, for named arguments, an argument number was provided to identify the argument. Now, the name of the argument is provided in the error message.

SIRPRMPT=2 for step name in command line prompt

MAXBG system parameter

The MAXBG parameter is a user0 parameter that specifies the maximum number of background or independent daemon requests that may be running at once. Before Sirius Mods 7.0, the only way to create a background daemon request was with the $commbg function. Under Sirius Mods and later, independent daemon requests can also be created using the Daemon class RunIndependently method. Daemons running either as a result of RunIndependently or $commbg are both counted the same way against the MAXBG limit.

If a $commbg request would exceed the MAXBG limit (or there are no daemon threads immediately available to run the request) the request is enqueued and run later when daemon threads are available and the number of running background/independent requests drops below MAXBG. If a RunIndependently request would exceed the MAXBG limit, the request is cancelled.

Initial clause for Longstring variables

As of Sirius Mods 7.0, the Initial clause may be used for Longstring variables. The length of the initial value must be 255 or less.

FUNCOPTS system parameter X'02' bit

As of Sirius Mods 7.0, the X'02' bit of the FUNCOPTS system parameter causes all $list functions that encounter CCATEMP full conditions to act as if the LISTFC $sirparm were set to 1, that is, to cancel the request with a CCATEMP full condition.

NOCHECK parameter for $sir_login

A new option, NOCHECK, can be specified on a $sir_login invocation to indicate that the user should be logged in without checking whether the userid is defined in CCASTAT or the external authorizer database.

A NOCHECK login is a trusted login, since for such a login there is no userid lookup and therefore no password to check. NOCHECK is similar to GUEST, except NOCHECK doesn't even do a lookup for the user. This means a NOCHECK login is more efficient than a GUEST login, especially if an external authorizer is being used. The downside with a NOCHECK login is that the user cannot gain additional privileges if the userid happens to be defined in CCASTAT or the external authorizer database.

Janus Debugger and Sirius Debugger

Assembler language replaces User Language

• Downloading a User Language dump file (SIRDEBUG) to install the server-side support for the debuggers is no longer necessary.
• The Windows Installer program (setup.exe) for the Debugger workstation client, which was distributed within the SIRDEBUG procedure file for Sirius Mods prior to version 7.0, is now downloadable from the Sirius web site.
• As of version 7.0 of the Sirius Mods, users of Janus Debugger and Sirius Debugger are no longer required to license Janus SOAP and Janus Sockets.
• Multiple breakpoints can be set with one commmand, either on all lines that match a search string or regex, or on executable statements that follow comment lines that begin with *Break.
• Maximum number of breakpoints per request increased from 40 to 1000.

New mappable commands for Client GUI

breaks

Sets breakpoints on lines after comments that have the form *break.

breaksAt

Sets breakpoints on lines that match a search string.

runWithoutDaemons

Runs until end-of-request, or untill an error or breakpoint is encountered; does not pause at daemon code.

stepOut

Steps out of a subroutine or method.

turnOffDebugging

Allows the GUI to stop debugging, equivalent to a SIRIUS DEBUGG OFF command.

Improved GUI display of variables

• The current occurrence value can be displayed for any active FEO loop.
• The Debugger will recognize %variable names that include question marks (?) and single-quotation marks (').
• Screen and ScreenField objects are added to the list of Sirius system classes whose class Variables you can display in the Debuggr Client.

Enhancements to SIRIUS DEBUG command

DebuggerTools DebugOff method

Janus Sockets

HttpRequest class Get method can send content

• An AddXML call added Post data to the request.
• An AddLongString call added Post data to the request.
• The MultiPartFormEncoding property set to True enabled multipart form encoding.

With Sirius Mods 7.1 and later, these methods are allowed before a Get method call.

Janus SOAP ULI

User Language Enumerations

It is now possible to define Enumeration classes in User Language. This is done via the Enumeration statement/block, which is very similar to the Class statement/block.

The Enumeration block can contain Public, Private, Public Shared, and Private Shared blocks, just like any other class. However, because enumeration classes don't really describe objects, there can be no instance variables. That is, the Public and Private blocks cannot contain Variable declarations.

Instead, the Public block must contain one or more Value declarations:

Note: The value in a value clause is unusual in that the case (lower or upper) of the characters in its value are saved and used in the implicit ToString method.

User Language defined enumerations can be used just like system enumerations. That is, variables can be declared with the enumeration class and enumeration values can be assigned to an enumeration variable. More commonly, enumerations can be used as method parameters. And, typically, literal values are used as the arguments when invoking such a method.

Enumeration values are not strings, so they are case insensitive. Like system enumerations, User Language enumeration variables can be in a state where they have no value, that is, they can be null. In fact, that is the initial value of any enumeration variable. As with system enumerations (as of Sirius Mods 7.1), this default initial value can be changed with the Initial clause on the variable declaration.

Enumeration methods

Automatic methods

There are several methods that are automatically provided for User Language enumeration classes. Some of these are identical to common methods available in most system enumerations. These methods are:

Copy

Performs a “copy” of the enumeration value. Since enumeration variables simply have values, a Copy or DeepCopy is no different from an assignment, so enumerations are always copyable and deep copyable.

DeepCopy

Performs a “copy” of the enumeration value. Since enumeration variables simply have values, a Copy or DeepCopy is no different from an assignment, so enumerations are always copyable and deep copyable.

Ordinal

Returns the ordinal position of the Value clause associated with the value of the enumeration. For example, if an enumeration was declared as

enumeration shot public value rock value paper value scissors end public end enumeration the ordinal for a value of Rock is 1, for Paper 2, and Scissors 3. By default, the Ordinal method behaves as if it is a private method. That is, it can only be accessed inside the class. This can be overridden by specifying Allow Ordinal in the Public block.

ToString

Returns a string representation of the enumeration value. The value returned uses the same case for the characters as was used on the Value declaration.

Initial/Default values for Enumeration variables

As of Sirius Mods 7.1, enumeration variables, including Booleans, can have a compile-time initial value as specified by an Initial clause:

As of Sirius Mods 7.1, default values can also be specified for Enumeration parameters, including Booleans. The following method indicates a default value of Share for a LockStrength enumeration parameter:

Construct statement rules enforced at run-time

There are three basic inheritance-specific rules for constructors:

• It is invalid to refer to a base class member until the constructor for that base class has been entered, that is, until a Construct statement has been issued for that base class.
• It is invalid to invoke multiple Construct statements against the same base class for the same object instance.
• When exiting from an extension class constructor, Construct statements must have been issued for all base classes for the object.

Before Sirius Mods 7.1, these rules were enforced at compile-time. The benefit of this was that a program that compiled successfully was known to follow the rules. Unfortunately, to make it practical for the compiler to ensure that the inheritance-specific constructor rules were being followed, a variety of other restrictions had to be added to constructors. In practice, some of these restrictions proved to be impediments to solving certain problems.

As a result, Sirius Mods 7.1 removed almost all of these restrictions and changed the checks for rules violations to run-time checks. This allowed more flexibility in writing constructors but, unfortunately, eliminated the compile-time checks for rules conformance. The one perhaps somewhat arbitrary rule that still remains is that a Construct statement must be physically placed inside a constructor.

Implicit class for virtual constructors

It is possible to have a non-constructor shared function return an instance of a class, for example:

• They can run code before the object is instantiated. In fact, in some cases, they might not actually instantiate an object but return a reference to an existing instance. Such a method may not truly be a factory method.
• Before Sirius Mods 7.0, they had to be invoked by the class name in parentheses or by an object variable in the class.

Sirius Mods 7.0 allows virtual constructors to be invoked in much the same way that regular constructors are invoked, that is, without specifying the class name if the class name can be determined from context. For example, the above example of the NewFromUrl virtual constructor can be changed to the following:

Because the naming rules for virtual constructors are now identical to that for regular constructors, the two can be used interchangeably, and one can be changed to the other as requirements change, without breaking existing applications.

Is [Not] Defined | Visible tests

Two new forms of tests (and their negations) are available as of Sirius Mods 7.0 for any field in a Model 204 file. The tests are useful for User Language code which is (or may be) in the context of a Model 204 group (of files) when that code contains field references which may be nonsensical in one or more members of the group. They can be used to bracket field accesses, and certain updating statements, in group context to avoid request cancellations when using File classes.

Examples of the tests are shown below with If blocks:

These tests, like the Is Present test, can only be used in a record context, such as a For Each Record loop. The syntax is:

fld

is either the name of a field or is a fieldname variable (%%var) containing the name of a field.

Is Defined

This test returns the value “1” if the field is defined in the current file (as given by the $CurFile function); otherwise it returns the value “0”.

Is Not Defined

This test returns the value “0” if the same Is Defined test would return 1, and returns the value “1” if Is Defined would return 0.

Is Visible

This test returns the value “1” if the field is defined in the current file (as given by the $CurFile function) and does not have the INVISIBLE field attribute in that file; otherwise it returns the value “0”.

Is Not Visible

This test returns the value “0” if the same Is Visible test would return 1, and returns the value “1” if Is Visible would return 0.

Note: If a fieldname variable is used in any of the above tests and it contains a string which is not defined in the current file nor any member of the current group (when the reference is in group context), the request is cancelled.

Stringlist class enhancements

Named Parameters for Print Method

The Print method now supports named parameters. The new Print method template is:

RegexSplit method

Added in Sirius Mods 7.0, this method repeatedly applies a regular expression, or “regex,” to a given input string until it has tested the entire string. This splits the string into the substrings that are matched by the regex (the "separators") and the substrings that are not matched. By default, the method saves each unmatched substring as a separate item in the StringList method object. The leftmost unmatched substring is the first item in the StringList, the next leftmost is the second item, and so on.

A simple application of the method default is to extract only the data items from a string of comma-separated data items. If the specified regex is a comma, each of the resulting StringList items will contain one of the data items.

The StringList that is returned by a default invocation of RegexSplit will contain at least as many items as there are instances of matched substrings. Upon each match, the input string characters preceding the matched ones (and since the previous matched ones) are saved as a StringList item. If there are consecutive matching substrings (no unmatched characters between the matching ones), the corresponding StringList item for the second matching substring is empty.

RegexSplit also has non-default options that let you save the following in the StringList:

• only the matched substrings
• both the matched and unmatched substrings
• only the substrings that are matched by capturing groups in the specified regex
• the unmatched substrings and the substrings matched by capturing groups

Enhancements to support for regex methods

Version 7.0 of the Sirius Mods 7.0 included significant enhancements to the Sirius support for regular expressions (“regex”). Detailed information on these changes can be found in the “Regex rules” section of the Janus SOAP Reference Manual. Highlights of the changes include:

• Reduced PDL requirement.
• “Lazy,” or “non-greedy,” matching (the lazy quantifiers like *?, +?, ?? etc.) is now supported. This support mimics that provided in the Perl language.
• As in Perl, \w and \W multi-character escape sequences are supported (except within values in replacement-string arguments in those methods and $functions that have such arguments).
• The handling of square bracket characters ([, ]) is now supported in Sirius regex as it is in Perl, except when Sirius methods or $functions use the Options='C' argument (XML Schema mode).
• Multi-character escape sequences (for example, \s, \c) are now legal within a character class — but not as either side in a range.
• A character class may now contain an unescaped hyphen (-) as a simple character, if it occurs as the first character (or the second, if the first is ˆ) or as the last character. An escaped hyphen (\-) remains legal.
• The Status argument return value for a regex expression compilation error is changed from -1 to -1nnn, where the absolute value of the return minus 1000 gives the 1-based position of the character being scanned when the error was discovered. An error occurring at end-of-string will have a 1-based value equal to the length of the string + 1.

Patch method

The Patch method applies a given patch file (in the form of a StringList) to a base file (also a StringList), and it returns a StringList that is the base file updated by the differences contained in the patch file. If the base file is the same in the original diff and in the Patch method, the Patch method thus returns a copy of the original updated version of the base file.

Note: The patch file StringList you use is assumed to be in well-formed, line-oriented diff output format. Only diff, diff -u, or diff -U 0 commands are supported, and any further processing of the output is likely to cause a cancellation of the method request.

Conversion to StringList form must preserve the output format exactly. The reference source used for this format is the GNU diff manual, Comparing and Merging Files

FindImageItemUp method

The FindImageItemUp method is a variation of the existing FindImageItem method. Like FindImageItem, FindImageItemUp locates a StringList item that exactly matches the contents of an image item or of a value converted to the image item format at the offset and length of the image item. The difference between FindImageItem and FindImageItemUp is the direction of the search: FindImageItem searches from the starting point in ascending. item number order, while FindImageItemUp searches in descending item number order.

Daemon class enhancements

Support was added in Sirius Mods version 7.0 for asynchronous and independent running of daemon requests. This included two new daemon methods, RunAsynchronously and RunIndependently. As the names suggest, both of these methods return immediately, before the daemon has completed processing its input commands. With RunAsynchronously, when the daemon commands are all processed, the daemon goes back to waiting for the master to tell it what to do next. To do this, the master thread has to make sure the daemon thread has completed processing by issuing the (also added in Sirius Mods 7.0) WaitAsynchronous method o against the daemon object:

With RunIndependently, when the daemon commands are all processed, the daemon logs off. This means that a daemon thread for which RunIndependently is issued can no longer be controlled by its master thread (as the method name would suggest). In fact, upon return from the RunIndependently method, the daemon object is set to null, so any further methods invoked against it would result in request cancellation.

RunAsynchronously can be used to allow a thread to do parts of large, complex tasks in parallel. The master thread could be doing some of the work at the same time a daemon thread is asynchronously doing some of it. In fact, multiple daemon threads can be running asynchronously at the same time for a given master thread. When the master thread is done with its work, it can then do a WaitAsynchronous for each daemon running asynchronously until all the work is completed. If the work being run in parallel is very CPU intensive, there is not likely to be any benefit in running work asynchronously unless the ONLINE is using multiple tasks (MP/204 authorized and AMPSUBS>0). On the other hand, if the work being performed asynchronously is I/O intensive, a significant reduction in the time required to perform the work can be achieved over doing all the I/O serially in the master thread. Work involving network delays is an ideal candidate for running asynchronously, especially if multiple such delays are present in a batch of work.

RunAsynchronously subroutine

This method runs on the daemon thread the command or set of commands specified by its first argument. Unlike the Run method, this method returns immediately and the thread issuing the RunAsynchronously method can run in parallel with the daemon thread.

Usage Notes

• Issuing RunAsynchronously against a transactional daemon results in request cancellation.
• If the daemon thread and its daemons hold record locks that conflict with the parent thread's family (excluding the daemon thread and its daemons), RunAsynchronously results in request cancellation.
• After a RunAsynchronously method, the daemon thread is considered to be running asynchronously until a WaitAsynchronous method is issued against the daemon object. This is the case, even if the daemon thread has completed processing all of the input commands.
• While the daemon thread is running asynchronously, methods that require interaction with the daemon thread cause request cancellation. These methods include Run, RunAsynchronously, RunIndependently, Open, and LastCommandErrorCount.
• The WaitAsynchronous method can be used to retrieve any output from the commands run via RunAsynchronously. This includes the terminal output and any output or info object.
• If the daemon object associated with an asynchronously running daemon is discarded either explicitly or implicitly, the daemon thread is bumped by the parent thread. An implicit discard can happen at request end for non-global daemon objects or at user logout.

RunIndependently subroutine

This method runs on the daemon thread the command or set of commands specified by its first argument. Unlike the Run method, this method returns immediately and the thread issuing the RunIndependently method can run in parallel with the daemon thread. Unlike the RunAsynchronously method, this method makes the daemon thread completely independent of the parent thread so that the output from the commands can never be retrieved.

Usage Notes

• Issuing RunIndependently against a transactional daemon results in request cancellation.
• If the daemon thread and its daemons hold record locks that conflict with the parent thread's family (excluding the daemon thread and its daemons), RunIndependently results in request cancellation.
• After a RunIndependently method, the daemon object is set to null. This is because the daemon thread runs completely independently of the parent thread once a RunIndependently method is invoked so there is nothing useful the parent thread can do with such a daemon object, anyway.
• Even if the parent thread of an independently running daemon logs off, the daemon thread can continue to run.

WaitAsynchronous function

This callable method waits for the completion of the commands issued on a daemon thread by the RunAsynchronously method and retrieves various outputs from those commands.

Usage Notes

• If WaitAsynchronous is issued against a daemon object that is not currently running asynchronously (RunAsynchronously was issued against it), the request is cancelled. Note that this does not mean that the daemon must actually still be running — if the daemon thread has run all the commands in the RunAsynchronously call, not only is WaitAsynchronous allowed, it is required before anything else can be done with the daemon. And, in any case, it's the only way of retrieving the outputs from the asynchronous request.
• The output Stringlist and parameters from WaitAsynchronous are identical to the output Stringlist and parameters for the Run method.
• The inputs and outputs from the combination of RunAsynchronously and WaitAsynchronous are identical to the inputs and outputs from the Run method. As such, it should be a relatively simple task to split a Run into a RunAsynchronously and WaitAsynchronous, allowing the daemon processing to be performed in parallel with parent thread processing or the processing on another daemon thread. For example, if a request has the following:
  %out1 = %daem1:run(%cmds1, %inobj1, %outobj1). %out2 = %daem2:run(%cmds2, %inobj2, %outobj2). it can be easily split up into:
  %daem1:runAsynchronously(%cmds1, %inobj1). %daem2:runAsynchronously(%cmds2, %inobj2). %out1 = %daem1:waitAsynchronous(%outobj1). %out2 = %daem2:waitAsynchronous(%outobj2). and the processing on the two daemons would be performed in parallel with each other. Note that if the daemons hold or require record locks that might conflict with each other, such a split will not work.

Enhancements to File classes

File classes may now be extended

Beginning with Sirius Mods 7.0, it is possible to extend a file class in a specific context. For example, the following Class statement extends the RecordSet class for file FOOBAR:

AddRecordSetNew, AndRecordSetNew, and RemoveRecordSetNew

These new methods are available in the RecordSet class. They are functionally equivalent to the AddRecordSet, AndRecordSet, and RemoveRecordSet methods, with the exception that they produce new instances of the RecordSet class and they do not modify either of the input objects. This makes them useful if you want to perform one of the indicated operations without modifying any of the input objects. This could be accomplished before Sirius Mods 7.1 by copying the method object and then performing the required operation on the copied object. The new methods eliminate the need to do a Copy for this purpose.

These new methods might be especially useful in data-mining type applications where RecordSets might be combined in many different ways. In this case, there is a need to preserve the input RecordSets, while there is also a premium on performance, since so many operations might be performed on each RecordSet.

Clear subroutine

Clear removes all of the records in a RecordSet object, without discarding the object. It provides functionality identical to the User Language CLEAR LIST statement, but it does so for RecordSet objects. Usage Notes

• If an active For loop references a RecordSet object, either via a direct reference to the RecordSet object or via a RecordSetCursor instantiated against the RecordSet, and that RecordSet is cleared by the Clear method, its record will be closed.
• Any RecordSetCursor object instantiated against a RecordSet object that is cleared has its State property set to the new CursorState enumeration value of NoRecord, as described below.

CursorState enumeration value “NoRecord”

Screen classes

Screen objects, the Screen and Screenfield classes, are new with this release. Screen objects are designed to make writing and maintaining User Language full-screen applications easier. Since Screen objects allow screen definition to take place during User Language request evaluation instead of compilation, you can take advantage of the current screen size, and a single application can support many different screen sizes without changing User Language code or resorting to special $functions to manipulate a traditional screen layout.

The Screen class provides an object-oriented equivalent of the Model 204 full-screen feature. An instance of a Screen object is equivalent to a screen you might define with the User Language full-screen feature.

The Screen methods specify layout and certain visual attributes of each screen: where screen items are to appear on the video display, and how they are to be highlighted or colored.

Screen objects are composed of screen fields and not screenlines as in the full-screen feature, and multiple screen fields may form the equivalent of a single screenline (or row). These screen fields are themselves objects: instances of the ScreenField class.

The Screen and Screenfield classes are documented in the Janus SOAP Reference Manual.

Janus SOAP Xml API

Null string SelectionNamespace value now means “no namespace”

In versions prior to 7.0 of the Sirius Mods, the following assignment statement:

However, experience has shown that this aspect of the XPath recommendation creates some difficulty in the coding of XPath expressions in Janus SOAP. If a section of User Language code has the information about the namespace of a node it needs to select, it must use two different forms, depending on whether the the node is in a namespace; for example:

To make it easier to handle situations like this, we have extended the XPath specification, allowing a prefix in an XPath expression to be associated with the null string. When such a prefix is used in an XPath expression, it matches Element or Attribute nodes which are not in a namespace. Now the above code can simply be written as:

XmlDoc IsSelectionPrefix method

This function of the XmlDoc class returns the Boolean value “True” if the string argument is currently associated (either to the null string or to a namespace URI) as a prefix which can be used in an XPath expression. Otherwise it returns “False”.

XmlDoc DeleteSelectionPrefix method

This subroutine of the XmlDoc class removes any XPath selection association for its string argument.

XmlNode Next and Previous methods

Added in version 7.0 of the Sirius Mods, the Next and Previous methods, both in the XmlNode class, return the XmlNode which is:

• for a non-Attribute node, the next and previous, respectively, sibling (in document order) of the method object. This is exactly the same as the node returned by SelectSingleNode with an argument of 'following-sibling::node()' or 'preceding-sibling::node()'[1], respectively.
• for an Attribute node, the next and previous, respectively, Attribute node that would be produced when the Element containing the method object is serialized in “normal” (that is, not ExclCanonical) order.

XPathNodeID method

Added in version 7.0 of the Sirius Mods, the XPathNodeID method was designed to provide information when sending an error message to an XML client application so it can identify which node in the request XML doc is invalid.

However, if the returned XPath expression refers to elements and/or an attribute which have non-null namespace URIs, prefixes are employed in the usual way, but they must be associated with URIs. And so, after the first item in the Stringlist is a series of pairs of items, the first in each pair being a prefix used in the expression, and the second being the URI associated with it.

ExclCanonical and WithComments options on Serial method

As of version 7.0 of the Sirius Mods, these options are added to the Serial method so that it can be used to create a Longstring “extract” from an XML document, in support of digital signatures. In order to work with digital signatures, the information being signed must be represented in a unique format.

Since there are many equivalent ways that a string serialization can represent the information in a portion of an XML document, the W3C has produced a specification, Exclusive XML Canonicalization This, in turn, is based on another specification, XML Canonicalization.

“Exclusive XML Canonicalization” deals specifically with the placement of namespace declarations in a document. Other than control on the placement of namespace declarations, the “Exclusive XML Canonicalization” specification adopts various other features of the “XML Canonicalization” specification, to ensure that the information in a portion of an XML document is serialized uniquely. For example, it specifies that “Empty Element” tags are not to be used.

Exclusive XML canonicalization can be obtained with the ExclCanonical option of the Serial method, by itself or in combination with the WithComments option, which causes all Comment nodes in the subtree to be serialized.

AddTrailingDelimiter argument of Serial method

Added in version 7.0 of the Sirius Mods, this optional named Boolean argument determines whether a final newline character is added to the result of Serial when one of the “newline” options (LF, CR, or CRLF) is used.

The default value of AddTrailingDelimiter is True; if it is specified as False, then the final newline character is not added. This is the same purpose as the argument of the same name of the Stringlist CreateLines method.

This feature may be useful if a digital signature must be created which includes newline characters between XML tags, but the XmlDoc does not contain those newline Text nodes.

LinefeedNoTrailingTabs option of deserialization methods

As of version 7.0 of the Sirius Mods, the following option may be used in the XML deserialization methods:

As one example of its use, this option may be useful if an input XML document is deserialized and a digital signature is needed of a subtree in it, when the input subtree contains a linefeed and one or more tabs separating markup, and the linefeed must be kept but the tabs discarded for the signature.

Support for numeric comparisons in XPath predicates

Prior to version 7.0 of the Sirius Mods, the only form of comparison permitted in Janus SOAP XPath predicates was of a locationPath expression to a quoted string; for example:

The support of comparisons has been extended in version 7.0, allowing comparisons to numeric literals (which are unquoted); for example:

Document deserialization relinquishes CPU

Prior to version 7.0 of the Sirius Mods, if a user is deserializing (WebReceive, ParseXml, or LoadXml) a very large document, other might experience degraded response time. This could be especially noticable in a non-MP Model 204 environment. Now the deserialization operation will periodically relinquish the CPU, if there are other users of equal or greater priority ready to run.

LoadXml now supports Stringlist items longer than 6K

Prior to version 7.0 of the Sirius Mods, if the first argument to the LoadXml method were a Stringlist, only the first 6,124 bytes of each of the Stringlist items were processed. Now the entire value of each Stringlist item is processed by LoadXml.

XmlDoc restored after parse errors

Prior to version 7.0 of the Sirius Mods, in the XML parsing methods, if the ErrRet option was specified and there was an XML document parsing error, all nodes and properties of an XmlDoc were initialized, losing all information in the XmlDoc.

Now if there is a parse error and ErrRet is specified, all properties are retained; this change applies to the LoadXml and WebReceive functions, and to the ParseXml function of the HttpResponse class. Also, for the LoadXml method, if the method object is XmlNode, the nodes present in the XmlDoc prior to the LoadXml are preserved.

XML parsing cancels request if CCATEMP full

Prior to version 7.0 of the Sirius Mods, if a CCATEMP full condition occurred during parsing of an XML document, the request was not cancelled if the ErrRet option was present.

Now, when this condition occurs, the request is always cancelled. This change applies to the LoadXml and WebReceive functions, and to the ParseXml function of the HttpResponse class.

InvalidCharacterPosition function

The InvalidCharacterPosition shared function in the XmlDoc class was first available with Sirius Mods 6.9:

Sirius Functions

$ListFindI_Up

The $ListFindI_Up function is a variation of the existing $ListFindI function. Like $ListFindI, $ListFindI_Up locates a $list item that exactly matches the contents of an image item or of a value converted to the image item format at the offset and length of the image item. The difference between $ListFindI and $ListFindI_Up is the direction of the search: $ListFindI searches from the starting point in ascending. item number order, while $ListFindI_Up searches in descending item number order.

SirFact

SirTune

SYSPARM data

As of version 7.0 of the Sirius Mods, SirTune issues an internal VIEW SYSTEM CWAIT command and saves the output to the sample dataset. This data can then be used to produce the SYSPARM report by the SirTune Report Writer.

System method quads

As of version 7.0 of the Sirius Mods, the SirTune data collector can distinguish system methods from each other. Before this release, all system methods would show up as “$CLASS_METHOD” in the QUAD reports.

Compatibility

A sample dataset collected by SirTune version 7.0 and later requires version 1.6 or later of the SirTune Report Writer.

Return to top of page

Sirius Mods Version 7.0

Return to top of page

UL/SPF Version 6.9

SirPro

Updates from the previous release include:.

• Dynamic widening of many more screens.

SirMon

Updates from the previous release include:.

• New statistics added to the System Overview Screen, designed to enhance the monitoring of non-terminal threads, like Janus and MQ.
• Addition of a Janus Port monitoring section.
• Major upgrade of the background monitor, which provides for e-mail warnings when system thresholds are exceeded. E-mail warnings are available only to sites with Janus Sockets.
• New statistics in anticipation of new releases of Model 204.

Janus SSL

Updates from the previous release include:.

• Support for intermediate certificates in the Janus SSL certificate management application.
• Many useability fixes to the Janus SSL certificate management application interface.

Return to top of page

Sirius Mods Version 6.9

Supported Model 204 Versions

Sirius Mods version 6.9 supports Model 204 V6R1 only.

Improved application maintainability

FUNCOPTS system parameter X'02' bit

The X'02' bit of the FUNCOPTS system parameter causes all $list functions that encounter CCATEMP full conditions to act as if the LISTFC $sirparm were set to 1, that is, to cancel the request with a CCATEMP full condition.

Argument name provided on request cancellation messages

Many internal Sirius methods (that is, those in the System namespace) provide an error message if an argument is valid. Previously, for named arguments, an argument number was provided to identify the argument. Now, the name of the argument is provided in the error message.

Fast/Reload

Although this fix has been provided via maintenance to all supported releases, it is worth noting that the handling of float values in Fast/Reload has been improved. The most significant aspect of this is that using UAI/LAI to reorganize a file with, in particular, FLOAT LEN 4 fields, and changing them to FLOAT LEN 8, now produces values which are correct according to standard Model 204 float handling. The explanation of float field processing has been elaborated in the Fast/Reload Reference Manual.

Janus Debugger and Sirius Debugger

• The DebuggerTools system object now supports the AmDebugging and Break methods.
• The Janus Debugger may be used against a Janus Web Legacy Support thread if you also have a license for the Sirius Debugger.
• From the Debugger GUI, you can now modify the current. value of a scalar variable in the program you are debugging.
• The information that identifies the procedure file and name to which. a selected source code line belongs will now also identify the APSY subsystem within which the procedure was invoked, if any.
• Wildcards on “Until” processing. You can use a single trailing wildcard. asterisk (*), for example, P.M*, to identify the procedure at which you want the Debugger to pause program execution.
• The default for the DEBUGPAG User 0 parameter has been changed from 10 to 100.

Janus SOAP ULI

Narrowing Assignments and Class Tests

Version 6.9 of Sirius Mods introduces support for narrowing assignments and class tests. As discussed in the Janus SOAP Reference Manual, care should be exercised when using these features. For this reason, by default, class tests and narrowing assignments are not allowed for any class. However, if class tests or narrowing assignments are unavoidable for a class, an Allow Narrow clause must be placed in the Public block of that base class.

One might wish to do narrowing assignments on the basis of the class of the object pointed to by an object variable. The Is Instance Of keywords are provided to facilitate testing whether the underlying object referenced by an object variable is of a specific class. This kind of code is strongly discouraged, and is a formula for long-term code maintainability problems.

The Is Instance Of keywords must be followed by the name of a class that is an extension class of the type of the object variable that precedes the keywords. Note that no system classes are currently Allow Narrow.

Janus SOAP Stringlist Class

The Janus SOAP Stringlist class has been enhanced by the addition of several functions that support the use of regular expressions (“regex&rdquo) to select and update data.

RegexCapture method

This function applies a regular expression, or “regex,” to a given input string, and it obtains those characters in the string that match the “capturing groups” in the regex. Any parenthesized sub-expression in the regex is a capturing group by default — unless its opening or closing parenthesis is escaped (preceded) by a backslash (\), or unless the opening parenthesis is followed by a question mark (?). Each captured set of characters is appended to the method object Stringlist as a separate item.

RegexLocate and RegexLocateUp methods

These functions use a regular expression (regex) to locate a string in the method StringList. They return the item number of the first item that the regex matches. Both functions proceed item-by-item through the StringList. RegexLocate starts by default from item 1, the first item in the StringList, or it starts from the item you specify. RegexLocateUp starts from the item n you specify and proceeds “upward” to item n-1, then n-2, and so on.

RegexReplaceCorresponding method

This function searches a given string for matches to one of multiple regular expressions contained in a list, and it replaces found matches with or according to one of multiple replacement strings contained in a list that corresponds to the regex list.

The regex list items are treated as mutually exclusive alternatives, and the function stops as soon as an item matches and the replacement is made. A “global” option is also available to continue searching and replacing within the given string using the matching regex item until no more matches are found.

RegexSubset method

This function returns a StringList that is a subset of the method StringList. The subset contains copies of all the items in the method StringList that are matched by a specified regex.

Janus SOAP Xml Classes

The following sections describe changes in the Janus SOAP Xml* classes (the XML API) in this release.

DefaultURI function

This function gets the Uniform Resource Identifier (URI) associated with the default namespace declaration which is in scope at a node which is the head of an XPath result.

InvalidCharacterPosition function

The following shared function in the XmlDoc class:

New DefaultURI argument to AddSubtree and InsertSubtreeBefore

The DefaultURI named argument may be specified to the AddSubtree or InsertSubtreeBefore functions, to control the URI of the default namespace of some of the Element nodes copied to the XmlDoc of the object method. Most of this section will describe the argument using AddSubtree, but it applies equally to InsertSubtreeBefore.

The DefaultURI argument takes a string value. It is optional; if it is omitted, the normal operation of AddSubtree occurs: every node added to the XmlDoc is. added with the same URI property as it has in the source XmlDoc.

When the DefaultURI argument is specified, its value is the URI that is used for all unprefixed elements in the source subtree that are not in the scope of a default namespace declaration that is also within the source subtree. You can use the DefaultURI property of the AddSubtree method object if you wish the copied subtree to “inherit” the default namespace of that node.

As mentioned, the DefaultURI argument is also available to the InserSubtreeBefore function, and it operates in the same fashion, although in the example of “inheriting” the default namespace declaration, you need to obtain the DefaultURI property of the parent of the method object.

If the DefaultURI argument is specified, the value of the Namespace property of the method object of AddSubtree must be On.

Relaxation of Namespace property and AddSubtree/InsertSubtreeBefore

In previous versions of the Sirius Mods, the AddSubtree operation (and InsertSubtreeBefore) are both allowed between two different XmlDocs only if the Namespace property of both XmlDocs is the same.

This has been relaxed, so that the following cases are also allowed:

• The source XmlDoc has Namespace=None and the target XmlDoc has Namespace=Ignore.
• The source XmlDoc has Namespace=None and the target XmlDoc has Namespace=On, if the DefaultURI argument is specified.

New SortCanonical option for serialization methods

All serialization methods now accept the SortCanonical option, to indicate that namespace declarations (based on the prefix being declared) and attributes (based on the namespace URI followed by the local name) are serialized in sorted order. This can be useful, for instance, when using the Serial method to serialize a portion of an XML document for a signature.

The sort order for namespace declarations and attributes is from lowest to highest, and it uses the Unicode code ordering (for example, numbers are lower than letters).

Janus Sockets Telnet Server Support

Sirius Mods version 6.9 adds Telnet Server support to Janus Sockets.

Janus Telnet support allows you to set up one or more telnet servers within a Model 204 Online. JANUS commands are used to define and start a TCP/IP listening port for each Janus Telnet Server. The Janus Telnet Server only supports the tn3270 subset of the telnet protocol. That is, it will only serve clients that provide 3270 emulation via telnet. Janus Telnet servers can be accessed with telnet, or more specifically a tn3270 client of your choice, to gain 3270 access to Model 204. A tn3270 client will typically be running on an end-user's workstation.

Nowadays, almost all access to mainframe applications is via tn3270. Typically, clients connect to a tn3270 server provided by the TCP/IP stack for the operating system. While most of these stacks are now provided by IBM, there are still a few third-party stacks available, most of which provide their own telnet servers. For Model 204 access, most tn3270 clients first connect to a service such as VTAM or CMS, which then provides access to Model 204. Using the Janus Telnet Server offers distinct advantages over using the telnet server provided by the TCP/IP stack.

Sirius Functions

New wait time parameter for $Bind

$RegexMatch: Whether string matches regex

$RegexReplace: Replace matching strings

Matches are obtained according to the “rules” of regular expression matching.

Updated mathematical functions

Sirius Mods version 6.9 includes high-performance, high-precision versions of many mathematical functions. These functions replace the extra-cost IBM Scientific Subroutine Library, or the relatively inneficient versions available via the IBM Language Environment feature.

The following functions are added to the Sirius Functions. With the exception of $MIN and $MAX, they are functionally equivalent to the versions documented in the Model 204 User Language Manual. The Sirius Functions version of $MIN and $MAX accept as many as eight parameters instead of the the maximum of five supported in the CCA version.

$ABS(x)

Absolute value

$ARCCOS(x)

Inverse cosine

$ARCSIN(x)

Inverse sine

$ARCTAN(x)

Arctangent

$ARCTAN2(x,y)

Arctangent of x/y

$COS(x)

Cosine of x radians

$COSH(x)

Hyperbolic cosine

$COTAN(x)

Cotangent of x radians

$ERF(x)

Error function

$ERFC(x)

Complement error function

$GAMMA(x)

Gamma function

$IXPI(x,y)

Integer base raised to integer exponent

$LGAMMA(x)

Log gamma function

$MAX(x1,x2,x3,x4,x5,x6,x7,x8)

Maximum of specified arguments

$MIN(x1,x2,x3,x4,x5,x6,x7,x8)

Minimum of specified arguments

$PI

Value of pi

$RXPI(x,y)

Real base raised to integer exponent

$RXPR(x,y)

Real base raised to real exponent

$SIN(x)

Sine of x radians

$SINH(x)

Hyperbolic sine of x radians

$SQRT(x)

Square root of positive argument

$TAN(x)

Tangent of x radians

$TANH(x)

Hyperbolic tangent of x radians

SirTune

As of Sirius Mods 6.9, SirTune data collector functionality is integrated into the Sirius Mods product. You no longer need to install SirTune as a separate product. The SirTune Report Generator (SIRTUNER), however, is still installed separately. Refer to the SirTune V1.6 section of the Product News for more information.

Compatibility/Bug fixes

This chapter lists any compatibility issues with prior versions of the Sirius Mods and any bugs which have been fixed in this version of the Sirius Mods but had not, as of the date of this release, been fixed in the immediately prior version (6.8).

Backwards incompatibilities with Janus SOAP XML Processing

XPath with “!=” and Element with more than 1 child

The processing of the not equals comparison in XPath predicates was, in some cases, incorrect. If the comparison was done to an Element with more then one child and in fact the value of the Element was different from the literal being compared, the Element was not included in the result, although it should be.

Fixed XPath “following” and “xx-sibling” axes

These behaviors, which did not conform to the XPath standard, have been fixed:

• Previously, using XPath's following axis (for example, following::*) resulted in the incorrect selection of extra nodes, in particular, Attribute and descendant nodes of the step's context node(s). Selecting these nodes is explicitly excluded by the XPath standard.
• Previously, using the following-sibling and preceding-sibling axes with an Attribute context node (for example, '@x/following-sibling::*' or '@x/preceding-sibling::*'),. which by the standard should not select any nodes, might incorrectly select nodes.

In version 7.0 of the Sirius Mods, the ability to navigate from one Attribute node to its sibling (and in turn, the rest of the sibling Attribute nodes), will be provided by the Next and Previous methods (which can be used from nodes other than Attribute nodes, as well).

Corrected XPath results with unusual axes

Prior to this correction, errors might occur in some cases using these axes:

and in some unusual cases using these axes:

Fixes in Sirius Mods 6.9 but not in 6.8

Reject invalid EndTag in Xml* deserialization methods

Accept UTF-16 input in Xml* deserialization methods

Return to top of page

SirTune Version 1.6

SirTune Data Collector Integrated with Sirius Mods

As of this version, which coincides with Sirius Mods 6.9, the version numbering of the principal SirTune components diverges: SirTune data collector functionality (formerly the SIRTUNE module) is integrated into the Sirius Mods product, and you no longer install it as a separate product. The SirTune report generator (SIRTUNER) and data logger for CMS users (SIRTUNED), however, are not part of the Sirius Mods and are still installed separately.

The SirTune data collector will assume the version number of the Sirius Mods version of which it is a part. The SIRTUNER report generator and SIRTUNED data logger will continue their own version numbering (currently version 1.6) and release schedule independent of the Sirius Mods.

The complete SirTune documentation is still contained in the SirTune Reference Manual.

New Features

The principal new feature in this release is the incorporation of the SirTune data collector into the Sirius Mods product.

Data collector invocation

Under previous releases of SirTune the SIRTUNE module was invoked instead of the Model 204 load module during initialization. The requisite JCL statement for z/OS was as follows:

Since the SIRTUNE module is no longer created, this format is no longer correct — and it will prevent the integrated SirTune program from running. The EXEC statement in your JCL should directly invoke the Model 204 load module:

If your site is authorized for SirTune, the SirTune data collector gets initialized by default, with these exceptions:

• Setting the new SIRTUNE parameter to 0 disables initialization.
• Under z/OS, if no SIRTUNED DD statement is present, SirTune does not get initialized.

SIRTUNEI PGM statement is ignored

The SIRTUNEI dataset does not require modification to run with the integrated SirTune module. However, the PGM statement is ignored.

Introducing the SIRTUNE parameter

The SIRTUNE parameter statement is added to allow control over whether the SirTune data collector is initialized at the start of a Model 204 run.

The SIRTUNE parameter,which is only allowed as a parameter in the EXEC JCL statement or CMS EXEC statement, can be set to 0 or 1. Setting it to 0 disables initialization of the integrated SirTune data collector. Setting it to 1, the default, enables it.

The SYSPARM report

The new SYSPARM report provides the values of all system and scheduler parameters in the ONLINE associated with the sample dataset. This report provides identical output to a VIEW SYSTEM CWAIT command issued in the ONLINE associated with the sample dataset. Formatting this report requires version 1.6 or later of the SirTune report writer (SIRTUNER). In addition, the data presented by this report is only provided in sample datasets collected with the SirTune data collecter version 7.0 and later. For sample datasets created with earlier SirTune data collectors, the REPORT SYSPARM report will be empty.

Compatibility

You can use the new version of SirTune without modifying any of your existing SirTune configuration information. SIRTUNEI configuration statements and the SIRTUNED dataset may be used as-is with Sirius Mods version 6.9. Note: The SIRTUNEO dataset is obsolete under Sirius Mods version 6.9 and later. It is ignored if it is allocated. SirTune CPU authorization and patch usage messages will be written to the Model 204 journal with the normal Sirius Mods initialization messages.

It is possible to run an earlier version of SirTune with Sirius Mods version 6.9 or later, but such configurations are not recommended, since older versions of SirTune will no longer be upgraded to work with new versions of Sirius Mods or Model 204.

A sample dataset collected by SirTune version 7.0 and later requires version 1.6 or later of the SirTune Report Writer.

Return to top of page

Fast/Unload Version 4.3

Support For Lob Fields and Long Values

Fast/Unload Version 4.3 adds the ability to operate on BLOB and CLOB (collectively called “Lob”) fields, which were introduced with V6R1 of Model 204. The following features support this:

• Adding CLOB or BLOB to the NEW field declaration statement, for example, to create a Lob field by concatenating “old” non-Lob fields.
• Support for #functions that may both accept arguments and produce results in excess of 255 bytes.
• Support for FUEL %variables that may contain strings longer than 255 bytes.
• Support for Lobs and for string values longer than 255 bytes in specified statements, #functions, and directives.
• Reporting Table E page usage for each Lob field.

Changed FUEL statements

The NEW statement, which allows you to define a field name that does not exist in the input file(s), now allows you to specify that the field is either a BLOB or CLOB field. This is primarily useful for a UAI type unload, allowing you to create values in the new field that are loaded by LAI as Lob occurrences.

Changed and New #functions

In version 4.3 of Fast/Unload, three #functions have been changed to support strings longer than 255 bytes, and one #function has been added.

#CONCAT supports long string arguments and result

The arguments of #CONCAT may now be string values that exceed 255 bytes in length (as the contents of %variables or Lob fields).

The result of #CONCAT may now be a string longer than 255 bytes.

#LEN supports a long string argument

The first argument of #LEN may now be a string value that exceeds 255 bytes in length (as the content of a %variable or Lob field).

#SUBSTR supports a long string argument and result

The first argument of #SUBSTR may now be a string value that exceeds 255 bytes in length (as the content of a %variable or Lob field).

The result of #SUBSTR may now be a string longer than 255 bytes.

#FLOAT8: Get 8-byte float, padding 4-byte input with 0

The #FLOAT8 function accepts a numeric argument, and it returns the value of the argument as an 8-byte floating point value. If the argument is a 4-byte floating point value, then the conversion is done by appending binary zeroes; otherwise, it is done by the normal FUEL conversion to an 8-byte floating point value.

Numeric operations in FUEL and in User Language are based on decimal, not binary, interpretation of floating point values, so this #function is seldom used. However, #FLOAT8 may be useful in unusual situations, in particular to perform a file reorganization that expands a FLOAT LEN 4 field to a FLOAT LEN 8 field, using the “raw” floating point conversion (such as can be done in a structured file reorganization using the X'0080' mode bit in FLOD).

Other FUEL changes

%Variables containing strings longer than 255

The value of a %variable may now be a string longer than 255 bytes. This can arise as the result of:

%v1 = %v2

assignment from another %variable that contains a string longer than 255 bytes

%v = fld

assignment from a Lob field

%v = #SUBSTR(...)

assignment from a substring of a string value longer than 255 bytes

%v = #CONCAT(...)

assignment from the concatenation of strings, whose lengths total more than 255 bytes

Permitted use of long string values and Lobs

A long string value may be used in the following contexts:

• as an argument of #CONCAT
• as the argument of #LEN
• as the first argument of #SUBSTR
• as the right-hand side of an assignment to a %variable
• as the right-hand side of a CHANGE or ADD[C] statement, when the field on the left-hand side is a Lob

If the value of a %variable is used in any other context and it is a string longer than 255 bytes, the FUEL program is terminated. Note that, since the EXISTS and MISSING clauses of the IF and ELSEIF statements do not reference the value of a %variable, you may use them to test a %variable even if it contains a string longer than 255 bytes.

The value of a Lob field may only be used in the contexts discussed above that allow a string longer than 255 bytes, even if the actual length of the Lob field occurrence does not exceed 255. Use of a Lob field in an invalid context causes the compilation of the FUEL program to fail; it never begins execution.

The following contexts allow reference to any field, Lob or not:

• The UNLOAD(C) statement
• The DELETE(C) statement
• The EXISTS and MISSING clauses of an IF/ELSEIF statement
• The #IF/#ELSEIF directives
• Preceding the number sign (#) “qualifier,” which specifies the number of occurrences of the field

Statistics improvements

For each Lob field, the total number of pages used in Table E is shown.

Note that the length statistics given for a Lob field, just like other fields, is based on the field occurrence values: in this case,. the number of bytes in Table E used by each field occurrence value (that is, unused bytes in Table E pages are not included in the length statistics).

Float Rules

The handling of floating point values has been extensively reviewed and some changes made in Fast/Unload Version 4.3. The handling of floating point values in Fast/Unload essentially mirrors that of User Language. Complete documentation of the rules for handling of floating point values can be found in the Fast/Unload Release Notes V4.3.

Backwards compatibility with Fast/Unload 4.2

This section lists any differences in processing that result from execution with Fast/Unload version 4.3, as compared with the same inputs to Fast/Unload version 4.2 at current maintenance levels.

Type of fields created by NEW statement

In version 4.2, if you define a field in a UAI unload with the NEW statement, and then load the file with the LAI command of Fast/Reload without a preceding DEFINE FIELD command for the field, the field will be defined as FRV KEY CODED UPDATE AT END. Anyone using the NEW statement for a field probably provides a DEFINE FIELD command for that field in the LAI job stream, so our default choice didn't matter.

Now that the NEW statement allows specifying some attributes of a field (that is, CLOB or BLOB), the default field type is changed to NFRV NKEY NCOD UPDATE IN PLACE.

IS FIXED/FLOAT with +/$

In version 4.2, if you force a type conversion with the plus sign (+) or dollar sign ($) while using the IS FIXED/FLOAT clause on an IF/ELSEIF statement, you can cause the result to be independent of the value of a field occurrence or %variable. Sirius believes that such FUEL code is likely to be a coding error, so these constructs are now illegal in FUEL.

Float handling

The handling of floating point values in Fast/Unload has been extensively reviewed in version 4.3. Although it it is not expected to affect anyone's current use of Fast/Unload, many small fixes have been made to float handling that can produce different results. Customers that use floating point fields are encouraged to upgrade to version 4.3.

Fixes in Fast/Unload 4.3 but not in 4.2

This section lists other fixes to features existing in Fast/Unload version 4.2 but which, in the absence of customer problems, have not been fixed in that version (as of the date of the release).

Fast/Unload User Language Interface

Only one of these updates impacts the “data“ output (for example, the FUNOUT DD): For the very first addition in the file of an ORDERED field (that is, creating the first index entry for that field), if a UAI OINDEX/INVIS is being performed, the index entry may be missing from the unload. In addition, some of the Table B statistics in the unload may be incorrect, such as the number of Table B pages in use, and the number of base records in the file. This problem is fixed in version 4.3 of Fast/Unload, together with a fix in the Sirius Mods (for example, ZAP66D6, or the commercially released version 6.7 or later).

Float handling fixes

The handling of floating point values in Fast/Unload has been extensively reviewed in version 4.3. Although it is not expected to affect anyone's current use of Fast/Unload, many small changes have been made which can produce different results.

The principal problem was that, prior to version 4.3, the results of a FUEL program could be incorrect, for many cases, if a FLOAT LEN 4 field is explicitly referenced in the program.

Return to top of page

UL/SPF Version 6.8

Simplified Product Packaging

• You can see the UL/SPF version number in the top line of all Help screens.
• Many more screens take advantage of dynamic screen-resizing, allowing more information to be displayed on the larger 3278/3279 Model types.

Products distributed in the SIRIUS file are SirDBA, SirFile, SirLib, SirMon, SirPro, SirScan, SirFact, and UL/SPF. In addition, all of the sample code and applications for Janus Web Server, Janus SOAP, and Janus Sockets formerly distributed in the JANUS file are now included in the SIRIUS file.

SirLib

As of Version 6.8, SirLib attempts to allow the updating of procedures even when APSYs are using the procedure file. In addition, a number of improvements have been made to the product's stability, screen layouts, and feedback to users. Specific changes include:

Soft updates

Under Version 6.8, before SirLib applies changes to a procedure, it checks to see if the new version would be identical to the procedure to be replaced. If it is, then no change is made to that procedure in the target file. Soft updates allow for much more accurate tracking of change history.

Running while procedures are locked

SirLib Version 6.8 lets you attempt to Reconfigure a procedure file while an APSY subsystem is locking procedures in it. This feature is very useful if you know that the updates you wish to apply do not affect procedures locked by APSY, for example if you are only updating “inner” procedures.

SirMon

SirMon Overview

More statistics are packed on the Overview screen, as well as on the associated threshold screen and the background monitoring function. These stats include:

• New measures for CCALOG usage
• A number of stats to monitor non-terminal thread usage (sdaemons, web threads, external-call facilty, and MQ threads), and a number of measures to show the status of DNS lookup performance and possible problems

SirMon Background Monitor

The background monitoring feature is enhanced so that users can be notified of critical resource usage problems by e-mail or by a cell phone message, via a Janus Sockets call (requires Janus Sockets). Notifications were previously hard-coded in such a way that users could not easily configure warnings.

A large number of new statistics have been added to SirMon, many of them related to the support in Model 204 V6R1 for LOBs and Table E, as well as the monitoring of non-terminal Janus threads, MQ, and the External Call Facility. There are new statistics at the file, user, and system level. Any of the new stats can be added to custom views.

SirPro

Fixes and enhancements in SirPro Version 6.8 include:

• General stability improvements.
• Fixes to the Copy, Rename, Move, and Delete functions so they operate correctly in group context.
• Support for dynamic screen sizing for users of large screen sizes, including support for Model 6 custom sizes.

SirFact

Fixes and enhancements in SirFact Version 6.8 include:

• Improvements to 3270 displays, including non-wrapping of long lines and support for Model 6 custom sizes.

Return to top of page

Sirius Mods Version 6.8

Supported Model 204 Versions

Sirius Mods version 6.8 supports Model 204 V5R1 and V6R1 only.

All or Multiple Products

COMPOPT parameter

As of Sirius Mods version 6.8, the system parameter COMPOPT facilitates migration to mixed-case User Language. COMPOPT is a Model 204 bitmask parameter that must be set in the CCAIN (User 0 input) stream.

Sdaemon enhancements

Sdaemons running on behalf of other threads, via the $comm functions or Daemon objects, will no longer suffer record locking conflicts with other threads in the same thread family. Two threads are in the same family if one is a synchronous child daemon of the other via a $comm function or a Daemon object. In addition, all families with common threads are considered to be a single family. So, if thread A is a synchronous parent of thread B, which is a synchronous parent of thread C, threads A, B, and C are all considered part of the same family. Furthermore, if in this example, thread B had two other synchronous children (via Daemon objects), threads D and E, then threads A, B, C, D, and E would all be considered part of the same family.

Before Sirius Mods 6.8, threads in a family could get record locking conflicts with each other. This greatly limited what could be done on daemon threads. The one condition under which two threads in the same family can still suffer a record locking conflict is if they both try to update the same record, which would require both threads to have an exclusive pending update lock on the record being updated. However, even this possibility of a record locking conflict is eliminated for transactional daemons (Transactional daemons).

Terminal MODEL 6 support

Support has been added for terminal models beyond the standard Mod 2 (24 X 80), Mod 3 (32 X 80), Mod 4 (43 X 80), and Mod 5 (27 X 132). The new terminal models are supported by setting the terminal model to 6:

RESET MODEL 6

There's really no such thing as a Model 6 terminal, but setting the terminal model to 6 tells Model 204 to issue a Write Structured Field Query to the terminal to have the terminal indicate its geometry (number of rows and columns) to Model 204. In this way, Model 204 can dynamically set a terminal's geometry, whether it's one of the standard geometries (Mod 2, 3, 4, or 5) or not. Many terminal emulators allow alternate 3270 sizes to be set. This makes it possible to set the terminal geometry to match the optimal combination of font size and physical screen size for a particular workstation, rather than trying to set the emulator font size to work well with one of a limited number of screen geometries.

To facilitate User Language applications for varying screen sizes, the VIEW command for the MODEL parameter has been enhanced to show the screen geometry in addition to the model number for model 6 terminals:

> V MODEL
MODEL     6 34*142    TERMINAL MODEL

To enable model 6 support, the SIRTERM system parameter must be set in the CCAIN stream.

If a terminal is using a non-standard screen geometry via model 6 support, the Model 204 editor and command line will correctly use the available screen space. Many UL/SPF subsystems such as SirScan, SirMon, and SirPro will also take advantage of the additional available screen space.

Janus SOAP LDAP Helper

The following features are new or changed in the LDAP Helper methods (the Ldap class):

BaseObject parameter for Find methods

The BaseObject parameter is added to the LDAP Helper Find methods. This optional, NameRequired, string contains one or more comma-separated attribute=value pairs that direct the Find method search to a particular domain in the target LDAP directory tree. For example:

BaseObject='dc=hawaii,dc=edu'

Such a string may be required by your target LDAP server to provide an LDAP base “distinguished name,” which ensures that the entries your search string locates are unique.

No limit on length of returned data

Change of behavior with binary attribute values

In version 6.7 of the Sirius Mods, if the result of one of the Find methods contained binary data that was not a valid XML string, a Model 204 snap was issued and the user was restarted. In version 6.8, such data simply causes a request cancellation, with a message that displays a fragment of the value including the invalid character.

Janus SOAP ULI

Collection keyword now optional

The keyword “collection” is now optional on declarations of ArrayList and NamedArrayList collections. Instead of coding “collection arrayList” or “collection namedArrayList,” you may now simply use “arrayList” or “namedArrayList”:

%monkeys     is arrayList of object monkey

Record, RecordSet, and SortedRecordSet objects deepCopyable

The Record, RecordSet, and SortedRecordSet objects are now deepCopyable. This means that these objects can be contained inside User Language classes and those User Language classes, themselves, could be deepCopyable. Perhaps even more important, this means that these objects can be passed back and forth between master and daemon threads, via the Run, GetInputObject, ReturnObject, and ReturnInfoObject methods. Among other things, this makes it easy to dynamically generate Find statements that run on a daemon thread and then to use the resulting found set on the master thread.

Item method now optional

The Item method name is now optional in any context where it is used for system methods. This has always been true for collections. That is, if %foo is declared as:

%foo    is collection arrayList of object xmlDoc

The following two lines are equivalent:

%foo:item(%i):print
%foo(%i):print

Now, the method name is also optional in the other two places the Item method appears in system classes: in the StringList class and the XmlNodeList class.

Virtual constructors for system classes

A shared method in a class that returns an instance of the class is sometimes referred to as a “factory method” or “virtual constructor,” because it behaves very much like a constructor. In Sirius Mods 6.8, system methods that are virtual constructors can be invoked without specifying the class name or a class variable before the method name, much as constructors can be invoked without the class name. Currently, the only virtual constructor in any system class is the CurrentRecord method in the Record class.

This keyword for classnames

class foo
   public
      subroutine increment
   end public
   public shared
      variable counter is float
   end public
   subroutine increment
      %(this):counter = %(this):counter + 1
   end subroutine
end class

As part of this enhancement, the name This is no longer allowed as a class name.

Daemon object enhancements

Transactional daemons

%pantalaimon   is object daemon
%pantalaimon = new(transactional=true)

If Transactional is set to True, the master and daemon thread will share a single updating transaction. This means that if updates are performed by both the master and daemon thread, these updates are all either committed or backed out when a commit or backout is performed on either the daemon or master thread. If a thread has multiple transactional daemons, then all those daemons share a single updating transaction with the master thread. In addition, if a transactional daemon thread itself has transactional daemon threads, those threads also share a single updating transaction with the ultimate master thread. Effectively, all of a thread's transactional daemons, and all the transactional daemons of those transactional daemons, and so on, make up a transactional family that shares a single updating transaction.

There are a few differences in updating-transaction processing between a transactional daemon thread and other threads:

• Transactional daemon threads will never do an implied commit. Of course, an explicit Commit or Backout statement run on a transactional daemon thread will result in the transaction being committed or backed out, including those updates performed on the master thread or some other thread in the transactional family.
• As an outgrowth of the previous item, transactional daemon threads can perform procedure updates in the middle of an updating transaction, as well as other file maintenance operations such as field definitions.
• Transactional daemon threads cannot perform User Language updates against files that their ultimate master thread does not have open in update mode. The ultimate master thread is the thread's master or the master's master if that thread is, itself, a tranasactional daemon, and so on.

Transactional daemons cannot suffer record locking conflicts with other threads in the family, and they can even update the same records as other threads in the transactional family.

Info parameter on Run method

The Run method has a new, named, output parameter called Info. This parameter allows a second output object for the Run method (in addition to the standard output object, which is the third parameter). While the Info object can be used for any kind of output object, its intent is to separate the “true” output from a daemon request from informational output (return codes, error messages, diagnostics, etc.). While this could be accomplished by making the output object for the Run method be of a class that extends the true output class and some informational class, this solution adds a lot of extra complexity that is best avoided. In the following example, a StringList object is used as the Info output from a Run method — presumably error messages would go on that StringList:

%errors    is object stringList
%result    is object myClass
%daem      is object daemon
%daem:run('MYSUBSYS', , %result, info=%errors)

The daemon thread running the request would return the info object using the ReturnInfoObject method, which is a shared method that has a single required parameter: the object being returned:

%errors    is object stringList
%(daemon):returnInfoObject(%errors)

Since, like any other objects passed between master and daemon, the info object is passed via deep copy, the class of the info object must be deepCopyable.

MasterNumber and ParentNumber methods

The Daemon class has new shared methods (functions) called MasterNumber and ParentNumber.

The ParentNumber function returns the user number of the thread that created the daemon thread, either via a Daemon object or even via a $comm function. If the thread issuing the ParentNumber method is not an sdaemon, or is not performing work for another thread via a Daemon object or a $comm function, the ParentNumber function returns a value of -1. The following code audits a thread's parent user number:

audit 'My parent''s user number is ' %(daemon):parentNumber

The MasterNumber method returns the same value as the ParentNumber method, except in two cases:

• The parent thread, itself, has a parent. In such a case, the MasterNumber method follows the chain of parents to the highest level, that is, to the parent that does not, itself, have a parent.
• The issuing thread is an asynchronous sdaemon. In this case, the MasterNumber value is -1.

The ParentNumber and MasterNumber methods have $function equivalents: $daemonParentNumber and $daemonMasterNumber respectively. The $functions and methods can be used interchangeably regardless of whether the daemons were created with $comm functions or Daemon objects, so the decision of which to use is largely a matter of taste.

Colon allowed in User Language class names

The colon character (:) is now allowed in User Language class names. The following, for example, is a valid class declaration:

class customer:order

No colon-demarcated part of a class name can be the word System. For example, System, System:foo, Foo:system, and Foo:system:bar are all invalid class names.

Janus SOAP Xml Classes

The following sections describe changes in the Janus SOAP Xml* classes (the XML document API) in this release.

Validate method

A major new enhancement for the Xml* classes is the ability to validate an XmlDoc using a schema, according to the XML Schema Recommendation. This can be accomplished with the following method in the XmlDoc class:

%rc = doc:Validate(schemaInput [, options])

Where:

%rc

The return code, which indicates the success of validation.

doc

The method object, which is an “instance” XmlDoc to be validated.

schemaInput

A string or Stringlist that is the serialized schema document for validating the instance.

options

A list of option words.

If you want a reference for XML Schema, there is a wonderful book: Definitive XML Schema, by Priscilla Walmsley.

InvalidChar XmlDoc property

In previous versions of Janus SOAP, it is illegal to add to an XmlDoc a string that contains a “control character,” for example, X'01'. This restriction is specified by the XML Recommendation: if you presented. a document containing such a character to a W3C-compliant XML processor, it would be rejected as erroneous.

However, you can use an XmlDoc to contain data that is not exchanged with other applications, yet whose content cannot be controlled by your application. The Find* methods in the Ldap class are examples of this (see Change of behavior with binary attribute values).

There is now a mechanism to allow invalid characters in an XmlDoc — the InvalidChar property:

doc:InvalidChar = Allow | Disallow

%XmlInvalidChar = doc:InvalidChar

The InvalidChar property applies to updates to Element or Attribute values. This property does not affect updates to Comment or PI nodes. It also does not affect deserialization operations, such as the LoadXml method, although in future versions of Janus SOAP it may be extended to allow invalid Attribute and Element values created with deserialization methods.

If InvalidChar is set to Disallow in the method object of the AddSubtree or InsertSubtreeBefore methods, the request is cancelled if the source XmlDoc “possibly” has any invalid characters.

IsValidString function

You may use the IsValidString function to determine whether a string is a valid XML Element or Attribute value, prior to updating an XmlDoc:

%Boolean = %(XmlDoc):IsValidString(string)

If the result is True:

• The AddAttribute, AddElement, and InsertElementBefore functions may use the string string as their second argument.
• The Value property may use the string string as the right side of an assignment (subject to restrictions on null strings).

Note that the above operations imply that string contains an EBCDIC value.

Invalid character error message

Normally, changes to error messages are not described in the Release Notes, but it is worth noting that the error message produced by AddElement, for example, if you attempt to add an invalid character, now contains a fragment of the value that includes the invalid character.

LoadXml accepts StringList, and LoadFromStringList is obsolete

The LoadXml method now accepts a StringList as its first argument, thus replacing the purpose of the LoadFromStringList method. As a result, the LoadFromStringList method will be obsolesced in the Janus SOAP documentation.

LoadXml for XML fragments

The LoadXml method, previously only available in the XmlDoc class, is now available in the XmlNode class. This allows for deserializing an “XML fragment” as the child or children of a node in an XmlDoc.

An XML fragment is a substring of a serialized XML document, such that

• The fragment, if “wrapped” within a simple element start tag and end tag (such as <w> and </w>, respectively), is a legal XML document.
• The fragment may contain undeclared prefixes. Any such prefixes must be declared at the Element node referred to by the method object of LoadXml; these declarations (along with the default namespace) are inherited by the inserted fragment.

Note that an XML fragment does not provide for inserting an Attribute into an Element node.

Note that if the method object refers to the Root node of an XmlDoc, the LoadXml method in the XmlNode class behaves exactly as the LoadXml method in the XmlDoc class. For example:

%d Object XmlDoc Auto New
%n Object XmlNode
%n = %d:SelectSingleNode.
%n:LoadXml('')

When the Root node is the method object, the serialized input must be a legal XML document (for example, the XmlDoc must be Empty, and the serialized input must contain exactly one top-level element).

Unless the method object refers to the Root node, the input to the XmlNode LoadXml method is always an EBCDIC string or a Stringlist of EBCDIC strings. This differs from the XmlDoc deserialization methods, which allow several forms of input string: EBCDIC, "ASCII", UTF-8, and UTF-16.

Janus Web Server

The following features are new or changed in Janus Web Server:

Keep-Alive support

A new Janus Web Server port definition parameter, KEEPALIVE, tells Janus Web Server to keep an HTTP connection open for a certain number of seconds to allow a client (often a browser) to send another request on the same connection. This can reduce network traffic and, more significantly, HTTP request latency. Both of these benefits are magnified for SSL connections, where each HTTP request requires a TCP/IP and SSL connection establishment handshake.

The KEEPALIVE parameter must be followed by a single number between 1 and 32767 that indicates the number of seconds a TCP/IP connection is to be held open after an HTTP request on that connection. For the connection to be held open, the client/browser must indicate that it supports HTTP keep-alives. Most modern browsers support and take advantage of keep-alives.

Notes:

• A keep-alive connection does not use a server or sdaemon thread while between requests.
• The keep-alive facility only preserves a TCP/IP connection. It does not preserve any application context.
• While the keep-alive mechanism is useful for browser-to-web server requests, especially when embedded content such as style sheets or images are served from the same web server as the HTML pages, keep-alives can be even more useful for server-to-server HTTP requests.
• If both sides of the server-to-server application are Model 204, then the use of the KEEPALIVE setting on a Janus Sockets port is likely to provide tremendous benefit — Janus Sockets client requests easily share connections to the same web server.

INPUTTIMEOUT port definition parameter

A new Janus Web Server port definition parameter, INPUTTIMEOUT, tells Janus Web Server to use a different timeout for input (receiving the web request) than for output. This might be desirable because, while some browsers sometimes delay receiving web output until some user interaction is completed, there should never be a delay between connection establishment and the sending of the HTTP request. As such, it is perfectly safe to set a very aggressive input timeout while maintaining a less aggressive output timeout. Once a complete HTTP request is received, Janus Web Server switches the connection to use the port's TIMEOUT value for the output timeout.

RAWINPUTONLY port definition parameter

A new Janus Web Server port definition parameter, RAWINPUTONLY, tells Janus Web Server to save the raw input stream for an HTTP Post, regardless of the mime-type set by the client. This does the same thing as the RAWINPUTONLY parameter provided for JANUS WEB ON rules in Sirius Mods version 6.7, except that it makes the setting effective for all URLs on the port.

With the introduction of this parameter, the NOTRAWINPUTONLY parameter is made available for JANUS WEB ON rules to override a port-wide (JANUS DEFINE) RAWINPUTONLY setting on a URL basis.

COMPRESS feature is improved

Improvements to the “deflate” compression algorithm used in the Janus Web COMPRESS feature provide significantly better compression in Sirius Mods version 6.8, without any noticeable increase in CPU requirements.

New URL encoding/decoding $functions

$web_url_encode_lstr is now available. It is identical to $web_url_encode with the exception that it is longstring capable. That is, it can take a longstring input and produce the appropriate longstring output.

$web_url_decode and $web_url_decode_lstr provide the inverse functionality to $web_url_encode and $web_url_encode_lstr. That is, instead of converting a string to the EBCDIC representation of its URL encoding, they convert an EBCDIC representation of a URL encoding of a string to that string. As one might guess, $web_url_decode is not longstring capable, while $web_url_decode_lstr is.

Janus Sockets

The following features are new or changed in Janus Sockets:

Domain Name Services enhancements

The JANUS NAMESERVER command has been enhanced to add support for some new Domain Name Services capabilities:

• Support for multiple name servers
• Internal caching of name server responses
• Faster timeout of name server requests

The format of the JANUS NAMESERVER command is now:

JANUS NAMESERVER ip_address port_number -
                 [AND ip_address port_number -
                 [AND ip_address port_number ... ]] -
                 [TIMEOUT numsec] -
                 [CACHE numcache] -
                 [MAXTTL maxsec]

The AND clause allows specification of alternative backup name servers. Initially, all DNS requests go to the primary (first) name server. If a request times out, it is assumed that that name server is having problems, and the second name server is sent the request. If the second name server sends a response, it becomes the primary name server. That is, all subsequent DNS requests are sent to it. If the second name server fails to respond, the third name server is tried; if it responds, it becomes the primary name server. And so on, eventually returning to the first name server.

Note that a negative response from a name server, that is, a response that indicates that the name server does not know the requested host name, does not cause a subsequent name server to be tried. If name servers are properly configured, changing name servers should not affect the success of a hostname lookup.

Additional new JANUS NAMESERVER command parameters available in Sirius Mods 6.8 activate the cacheing of DNS responses. This saves both CPU time and latency and can significantly improve the performance of client applications using the HTTP helper.

TIMEOUT numsec

This sets the maximum number of seconds to wait for a name server response.

CACHE numcache

This parameter indicates that Janus Sockets is to save hostname-to-IP address mappings in the Online address space. Numcache is the maximum number of hostnames to cache in the Online.

MAXTTL maxsec

This parameter indicates the maximum amount of time Janus Sockets is to save a hostname to IP address mapping in its local cache before checking it again with the name server.

The following system statistics can be viewed in SirMon to determine how name server lookups are faring in an Online:

DNSCACHE

The number of entries in the name server cache (the CACHE value on the JANUS NAMESERVER command).

DNSMAXTL

The value of the MAXTTL parameter on the JANUS NAMESERVER command.

DNSCURNS

The current “go to” name server, in dotted IP address format with the port number in parentheses. For example: 198.242.244.9(53).

DNSRTOT

Total number of name lookup requests.

DNSRFAIL

Number of name lookup requests that did not succeed, that is, did not get an IP address.

DNSRSUCC

Number of name lookup requests that succeeded.

DNSRCACH

Number of name lookup requests that found the requested name in the local cache.

DNSRTIMO

Number of requests to name servers that timed out before they got a response.

DNSWTIME

Total time spent waiting for responses from name servers.

Keep-Alive support

A new Janus Sockets client port definition parameter, KEEPALIVE, tells Janus Sockets to keep an HTTP connection to a web server open for a certain number of seconds so Janus Sockets can send another request on the same connection. This can reduce network traffic and, more significantly, HTTP request latency. Both of these benefits are magnified for SSL connections where each HTTP request requires a TCP/IP and SSL connection establishment handshake.

The KEEPALIVE parameter must be followed by a single number between 1 and 32767 that indicates the number of seconds a TCP/IP connection is to be held open after an HTTP request on that connection. For the connection to be held open, the web server must indicate that it supports HTTP keep-alives. Most modern web servers can take advantage of keep-alives.

A keep-alive TCP/IP connection uses a Janus Sockets thread, so it is counted against both the maximum connections for a port and against a site's licensed thread limits. Since often a Janus Sockets application is only used to communicate with a single or handful of web servers, this should not be a problem.

New SirMon statistics

These statistics are added or modified for version 6.8. In addition to the DNS name server statistics already mentioned, several new statistics for monitoring Table E activity are defined only for Model 204 V6R1 or later.

• The following new statistic is retrievable or viewable with $FISTAT, $FISTATL, or SirMon:

  NPTE

  Size of Table E in pages. Same as ESIZE.

• The following new statistic is retrievable or viewable with $USSTAT, $USSTATL, or SirMon:

  FSCBSW

  Full screen reads issued or text web responses sent, including Janus Web and Connect* transactions (rate or total).

• The following new statistics are retrievable or viewable with $SYSTAT or SirMon:

  BUFPAGL

  The number of Table E pages in the buffer pool (like BUFPAGD).

  MODPAGL

  The number of modified Table E pages in the buffer pool (like MODPAGD).

  DKSTBLE

  Number of waits on Table E pages (like DKSTBLD).

SirSafe

The following are new or changed features in SirSafe:

New APSYSEC parameter

The APSYSEC parameter was actually introduced in Sirius Mods 6.7, but it inadvertently was not documented then, so it is announced here. Currently, the only use of this parameter is to allow any system manager to START, STOP, DEBUG, or TEST any susbsystem, without having to add the system manager to the SCLASS authorized to do these things.

The APSYSEC parameter is a bitmask parameter, where the bits mean:

X'01'

System managers are allowed to START, STOP, DEBUG, or TEST any subsystem. This reduces the headache of having to add a system manager to a privileged SCLASS in every subsystem in an Online to enable the system manager to at least start and stop the subsystems — a common thing for system managers to need to do.

Sirius Functions

The following are new or changed features in the Sirius Functions:

More callable functions

The following functions are now callable. Instead of assigning the function result to a %variable, these functions may be invoked without an assignment and with or without a User Language CALL statement:

• $errSet
• $fakeEnt
• $procCls
• $procOpn
• $scrWide
• $scrHide
• $scrSize
• $sirMsgP
• $wakeUp

$GZIP compression is improved

Improvements to the “deflate” compression algorithm used by $GZIP processing provide significantly better compression in Sirius Mods version 6.8, without any noticeable increase in CPU requirements.

$a2e and $e2a

$lstr_base64_encode and $lstr_base64_decode

$lstr_c2x and $lstr_x2c

$daemonMasterNumber and $daemonParentNumber

• The $daemonParentNumber function returns the user number of the thread that created the daemon thread, whether the daemon is associated with a Daemon object or with a $comm function. If the thread issuing the $daemonParentNumber method is not an sdaemon, or is not performing work for another thread via a Daemon object or a $comm function, or if the issuing thread is an asynchronous daemon, the $daemonParentNumber function returns a -1.
• The $daemonMasterNumber method returns the same value as the $daemonParentNumber method, except in the case where the parent thread, itself, has a parent. In such a case, the $daemonMasterNumber method follows the chain of parents to the highest level, that is, to the parent that does not, itself, have a parent.

Return to top of page

SirTune Version 1.5

Maintenance and Support

Multiple authorization criteria

Multiple authorization criteria allow a single copy of the SIRTUNE load module to support a set of CPUs, each with its own expiration date.

Authorization zap checksum

All SirTune authorization zaps now contain a checksum which is stored with the zap. At runtime, SirTune reports an invalid zap, as opposed to “not authorized.”

Additional information from SIRTUNE

The SIRTUNEO output of load module SIRTUNE will include the following new information:

• the date and time of the original run
• the CPU ID
• the customer site ID
• one or more lines displaying patch usage
• the date and time that the authorization zap was generated by Sirius Software
• if SirTune is authorized on the CPU, the expiration date of that authorization

Support for Model 204 V6R1

SirTune 1.5 adds support for the latest release of Model 204.

New features

Data collector record types

The data collector has two new record types: one for end of compilation, and one, for APSY compilations, signaling a switch from precompile mode to non-precompile mode. These record types improve the resilience of the SIRTUNER report writer, but they do not affect the actual reports.

Note: Although this data collector change does not affect the size of the dataset, it does alter the format of the sample dataset: earlier releases of SIRTUNER cannot process a SIRTUNE 1.5 sample dataset.

New SIRTUNER reports

Two new reports, WHATC and QUADC have been added.

• The WHATC report displays the CSECT distribution of the code executed for each “what” value. These reports can also be separated into maintask and subtask activity with WHATCM and WHATCS.
• The QUADC report displays the CSECT distribution of the code executed for each “quad.” These reports can also be separated into maintask and subtask activity with QUADCM and QUADCS.

Additional enhancements

• The load module for the SirTune data collector can now be resident in 31-bit storage, providing additional “below the line” virtual storage relief.
• Support is added for an ONLINE module using RMODE(SPLIT) linkage.

Return to top of page

Sirius Mods Version 6.7

Version 6.7 of the Sirius Mods was released in May, 2005. The major enhancements are summarized below. Please refer to the Notes for Sirius Mods Version 6.7 for more detailed information.

Support for Model 204 V6R1

Sirius Mods Version 6.7 fully supports Model 204 V6R1, with the following qualifications concerning Large Object fields (LOBs):

• Fast/Backup Version 6.7 is required to dump a file created by V6R1. While a Model 204 file created under V6R1 cannot be opened by a previous version of Model 204, Fast/Backup Version 6.7 can restore a file created under V6R1 to a file created prior to V6R1, as long as the dumped file was created with a TABLEE size of 0.
• Sir2000 Field Migration Facility doesn't let you establish a date format for a LOB field.
• A $FUNLOAD request that "accesses" LOB fields requires Fast/Unload 4.3, otherwise Fast/Unload 4.2 with ZAP4210 may be used.
• Fast/Reload supports the loading of files processed under Model 204 V6R1, including files that contain LOBs. The Fast/Reload D statement will process PAI output from a file that has LOB fields defined. LAI supports files with LOBs, but Fast/Unload 4.3 is required for UAI to support LOB fields.
• In User Language, you can move data between LOBs and longstrings via $lstr_set_userBuffer, $lstr_get_userBuffer, and $lstr_add_userBuffer.

All or Multiple Products

Sdaemon performance enhancements

The new system parameter, SDMOPT, enables certain sdaemon performance enhancements for Janus Web and Janus Server requests as well as requests run by Daemon objects.

SCREENS Stat and Connect*

The SCREENS statistic is now set to 1 at the completion of a Model 204 Connect* request. This can be useful in SirMon and SirAud statistics calculations.

MSGCTL NOCAN prevented for some error messages

Certain error messages should not be changed to NOCAN; doing so will cause unpredictable results. In general, you should not change an MSIR message to NOCAN unless there is explicit documentation explaining the circumstances for doing so. In order to prevent some unsafe MSGCTL NOCAN commands, certain error messages reject a MSGCTL NOCAN and instead produce an MSIR.0885 cancelling error message.

Object swapping statistic

A new system and user (login and since-last) statistic, OBJSWAP, reports on the swapping of Janus SOAP ULI objects into and out of CCATEMP. The object swapping statistic displays on CCAAUDIT and can be displayed by SirScan, SirMon and the Model 204 T REQUEST and MONITOR commands. User of AUDIT204 need a Sirius zap, else the user and since-last statistic name for OBJSWAP will be formated as eight blanks and the system statistic name will be eight blanks for Version 5.3 and 6.1 or TCON under Model 204 Version 5.1.

Fast/Reload

The following are new or changed features in Fast/Reload in this release:

• A new keyword, ERRCONT, is added to the OPTIONS statement.

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

• Support for Model 204 Version 6.1 files

  Fast/Reload now supports Model 204 V6R1 files, including loading of LOB fields, either in PAI or UAI format. This support requires Model 204 V6R1 and for table E space to be defined in the target file. Only Fast/Unload Version 4.3 and later is capable of unloading a LOB field in UAI format so that it could be then loaded by Fast/Reload.

• Validation of input record buffer offsets

  Fast/Reload now checks references to the input record buffer to detect attempts to look “off the end” of the current record. This avoids addressing exceptions or correpted data when references based upon a constant or index-register value are invalid. There is a slight performance cost to doing this check, so if there is no chance the checks would ever detect an error, you can turn off the checking with the new NOVALIDATE option on the Fast/Reload OPTIONS statement.

Fast/Unload User Language Interface

New Messages

Messages are now sent to the Model 204 journal/audit trail on every Fast/Unload request made and completed by the Fast/Unload User Language Interface. The message when the requests are started look like:

MSIR.0890: Asynchronous request 2 made by $funload

And the message when the requests are completed look like:

MSIR.0891: Asynchronous request 2 completed, RC = 0

These messages make it much easier to diagnose problems where Fast/Unload User Language Interface is involved.

FUNPARM System Parameter

The new system parameter FUNPARM is a standard Model 204 bitmask-style parameter. The X'01' setting, the only bit currently available, indicates that a synchronous Fast/Unload request is not to be allowed while an updating transaction is active. This is to prevent a Fast/Unload request that might take a long time to complete from being run while a user has resources enqueued for an updating transaction. These resources would, of course, include the blocking of checkpoints.

FUNMAXT System Parameter

The new system parameter FUNMAXT is a numeric parameter (with valid values from 0 to 36000) that indicates the maximum amount of time, in seconds, a Fast/Unload User Language Interface request is to be given to complete. The timer starts from the initiation of the request, either via $Funload, or the new FastUnload and FastUnloadTask methods in the RecordSet class. The default value of FUNMAXT, 0, means that there will be no time limit placed on Fast/Unload User Language Interface requests.

The purpose of FUNMAXT is to prevent user requests being “hung up” indefinitely while queuing for busy Fast/Unload tasks or for unintentionally long running requests.

RecordSet Methods for Fast/Unload

There are two new methods now available as an alternative to $Funload for unloading data using the Fast/Unload User Language Interface. Both of these methods are in the RecordSet class, and both unload the data in the RecordSet object against which they are invoked. These methods are FastUnload and FastUnloadTask, and they are only available to customers licensed for both “Fast/Unload User Language Interface” and Janus SOAP.

The FastUnload Method

The FastUnload method can be used to perform synchronous or asynchronous unloads. FastUnload has four NameAllowed parameters and three NameRequired parameters.

For asynchronous requests, the FastUnload method returns the request number. Request numbers are assigned serially, starting at 1, to $Funload and to the RecordSet FastUnload and FastUnloadTask methods.

For synchronous requests, the FastUnload method returns the return code from Fast/Unload. If the request is cancelled because the timeout period (MaxTime parameter, or FUNMAXT system parameter) is exceeded, the return code is 32. Any errors in the method parameter list, or any environmental errors that would prevent the request from being run, result in the request being cancelled.

The FastUnloadTask Method

The FastUnloadTask method can be used to perform unloads using Fast/Unload where the Fast/Unload output is processed programmatically as it is received. The advantage of the FastUnloadTask approach over the FastUnload method with a StringList output is that it avoids potentially large quantities of data from being moved to and from CCATEMP. The disadvantage of this approach is that User Language processing is likely to be slower than Fast/Unload processing, so using FastUnloadTask is likely to tie up a Fast/Unload task much longer than using FastUnload, which sends its output to a StringList.

The FastUnloadTask method has two NameAllowed parameters and three NameRequired parameters. FastUnloadTask returns a FastUnloadTask object which can be used to retrieve output from Fast/Unload.

The FastUnloadTask Class

The FastUnloadTask class is used for retrieving data from a Fast/Unload task as it is output. The only way to instantiate a FastUnloadTask object is via the FastUnloadTask method of the RecordSet class. FastUnloadTask objects always have one of three states, as described by values of the FastUnloadTaskState enumeration:

Started

This is the initial state of a FastUnloadtask object, and it indicates that no GetNextRecord methods have yet been called.

HaveRecord

Indicates that GetNextRecord has been called, and that the call did, indeed, retrieve another record from Fast/Unload.

Done

Indicates that GetNextRecord has been called, and that the call discovered that there where no more records to retrieve, that is, Fast/Unload had terminated.

The FastUnloadTask class has the following methods:

CurrentRecord Method

This function returns the contents of the current record as a longstring. It has no parameters, and it can only be called when the FastUnloadTask object is in the HaveRecord state. If called in any other state, the request is cancelled.

GetNextRecord Method

This function requests the next record from the Fast/Unload task, and it returns the new state of the FastUnloadTask object as a FastUnloadTaskState enumeration value. It has no parameters, and it can only be called when the FastUnloadTask object is in the Started or HaveRecord state. If called in the Done state, the request is cancelled.

Report Method

This function returns a StringList with the Fast/Unload report data. It has no parameters, and it can only be called when the FastUnloadTask object is in the Done state. If called in any other state, the request is cancelled. This function can only be called if ReportToStringList is set to True in the RecordSet class FastUnloadTask method that created the method object. Otherwise, the request is cancelled.

ReturnCode Method

This function returns the Fast/Unload numeric return code. It has no parameters, and it can only be called when the FastUnloadTask object is in the Done state. If called in any other state, the request is cancelled.

State Method

This function returns the current state of the FastUnloadTask object as a FastUnloadTaskState enumeration value. It has no parameters, and it can be called when the FastUnloadTask object is in any state.

Janus SOAP ULI

The object-oriented extensions supported by the Janus SOAP User Language Interface have been significantly enhanced with Version 6.7. The Notes for Sirius Mods Version 6.7 discuss these changes in more detail. For examples of how to use the Janus SOAP ULI and more in-depth documentation, please refer to the Janus SOAP Reference Manual. The following discussion just presentst the highlights of changes in 6.7.

Inheritance and Polymorphism

Janus SOAP ULI support for inheritance and polymorphism was added in Version 6.7. Inheritance and polymorphism are two closely related but subtly different concepts that are often considered cornerstones of object-oriented programming. Inheritance allows a programmer to create an object class that has all the characteristics of another object class (or that inherits all that classes attributes) and that has additional characteristics or attributes. Such a class is often called an extension class, because it extends the capabilities of what is often called a base class.

Polymorphism allows objects of different classes to be used interchangeably. Since the classes that can be used interchangeably are almost always a base class and one of its extension classes, or are extension classes of the same base class, polymorphism is strongly related to inheritance.

To create an extension class of a base class, simply include the Extends phrase in the first Class statement for the class:

class ropeList extends stringList
 ...
end class

As this example illustrates, it is possible to extend many system classes as well as User Language classes. There are exceptions, however. It is not possible to extend the following types of system classes:

• Collections, that is, ArrayLists and NamedArrayLists
• Enumerations, such as the Boolean class
• File classes, such as the RecordSet class, the Record class, and the RecordSetCursor class
• The XmlNode class

When one class extends another class, members of the base class can be accessed via variables of the extension class. For example, if RopeList extends the system StringList class, and %rope is of the RopeList class, any StringList class member can be accessed by preceding the member name with the StringList class name in parentheses:

%rope:(stringList)add('Added item')

If the creator of the RopeList class wants users of the class to be able to use StringList class members without specifying the class name on each invocation, the Inherit keyword can be specified after the class name in the Extends clause on the Class statement:

class ropeList extends stringList inherit
 ...
end class

If Inherit is specified on the Class statement, the Add method in the previous example can be accessed without specifying the StringList class:

%rope:add('Added item')

Since the main reason to use extension classes is to add functionality to the base class, you may define Public, Private, Public Shared, and Private Shared members in an extension class, and you may access these members like any other member of any other class:

class ropeList extends stringList inherit
   public
      property   first   is longstring
      property   last    is longstring
      subroutine print
      variable   name    is string len 32
   end public
 ...
end class

A member of an extension class may have the same name as a member of a base class. In the example above, the RopeList class has a Print subroutine that has the same name as a StringList class method. In such a case, an unqualified reference to the member such as the following refers to the member in the extension class:

%rope:print

This is called member hiding, because a member in the base class is hidden by a member in the extension class. In such cases, however, it is always possible to access the base class member by indicating the class name in parentheses, before the member name:

%rope:(stringList)print

This accessibility means someone writing an extension class should never assume that a base class member with the same name as an extension class member will never be accessed.

Another way to access a base class member instead of using an extension class member with the same name is to use polymorphism. With polymorphism, one can always assign an extension class variable to a base class variable:

%rope     is object ropeList
%string   is object stringList
 ...
%rope = new
%rope:name = 'Percy'
%string = %rope
%string:print

This assignment is possible because an object of an extension class is also considered to be an object of the base class. Many object-oriented programming textbooks use animals to illustrate this point: if an object is of class Otter, it is also of class Mammal, so there is nothing wrong with assigning it to a Mammal object variable. Once assigned to a base class variable, all member name references access the base class member of that name, even if the extension class has an eponymous member name. If this were not so, someone referencing a member via a base class variable might access a member of a class they didn't even know about.

In addition to allowing unqualified access to base class members (via the Inherit keyword in the Extends clause of the Class statement), it is possible to selectively allow unqualified access to individual base class members. In the following class, any reference to the Print member via a RopeList class variable accesses the StringList member of that name:

class ropeList extends stringList
   public
      property   first   is longstring
      property   last    is longstring
      inherit    print   from stringList
      variable   name    is string len 32
   end public
 ...
end class

The Inherit declaration can also be used to map a base class method to a different extension class name:

class ropeList extends stringList inherit
   public
      property   first   is longstring
      property   last    is longstring
      subroutine print
      inherit    display from stringList print
      variable   name    is string len 32
   end public
 ...
end class

In this example, a reference to the Display member of the RopeList class actually accesses the Print method of the StringList base class. This can be useful if, as in this example, there is a conflict between a base class member name and an extension class member name.

Multiple Inheritance

Janus SOAP ULI allows a class to extend more than a single class. This seems reasonable, as many objects in the real world can be thought of as extensions to more than one base class. For example, one might think of a dog as an extension to a Mammals class and to a Pets class. Or a person's car can be thought of as an extension to an Automobile class and to a Property class.

To extend multiple classes with Janus SOAP ULI, you separate the extended classes with the And keyword in the Class statement Extends clause:

class pet extends animal and property

The Inherit keyword can follow any or all of the extended class names:

class pet extends animal inherit and property

or

class pet extends animal inherit and property inherit

In general, having Inherit keywords on more than one extended class is not recommended, unless those classes are maintained to avoid name collisions. A name collision is generally treated as a compilation error. In the above example, if the Animal and Property classes both had members called Weight, the class declaration would result in a compilation error.

You can prevent name collision errors by specifying the IgnoreDuplicates keyword after the Inherit keyword for a base class for which duplicates are to be ignored:

class pet extends animal inherit and -
                  property inherit ignoreDuplicates

When IgnoreDuplicates is specified for an Inherit base class, any member names in that class that match an earlier Inherit base class member name will not be accessible without qualification, if they are being accessed via extension class variables. For example, a class has the following declaration:

class pet extends animal inherit and -
                  property inherit ignoreDuplicates

If both the Animal and Property classes have a member called Weight, the following call references the Weight member of the Animal class (assuming the Pet class has no Weight member that hides Animal's Weight member):

%tinky   is object pet
 ...
print %tinky:weight

In this case, the Property class's Weight member is accessible by qualifying it with the class name:

%tinky   is object pet
 ...
print %tinky:(property)weight

Repeat inheritance

With multiple inheritance, it is possible to define an extension class where the same base class appears more than once in the inheritance chain. For example, if the class MaleDriver extends the Driver class and the class AmericanDriver extends the Driver class, it might seem logical to create a MaleAmericanDriver class that extends both the MaleDriver and the AmericanDriver class. If this were done, however, the MaleAmericanDriver would end up with the Driver class as a base class twice — once via the MaleDriver class, and once via the AmericanDriver class. This is an example of repeat inheritance.

Repeat inheritance is not currently allowed by the Janus SOAP ULI. Because there are some special cases where repeat inheritance does make sense, Janus SOAP ULI will probably add support for some limited forms of repeat inheritance in a future release.

Inheritance and constructors

An extension class might or might not have any constructors. If an extension class has no constructors, the default (New) constructors for the base classes are called in sequence with no parameters. However, if any of the base class constructors require parameters or don't have the default New constructor, a constructor is required for the extension class. Of course, even if a constructor is not required for an extension class, one can be provided as needed.

In any case, if an extension class has a constructor, that constructor is required to complete the construction of the object for all base classes. This is accomplished with the Construct statement, which is followed by an invocation of the shared New method or by invocation of any other constructor. The Construct statement must be followed by the class name (using the shared method invocation syntax), followed by the constructor name, followed by any constructor parameters.

There are several restrictions concerning extension class constructors. While the rules for extension class constructors might seem complex, they probably will not come into play outside of fairly complicated constructors. Furthermore, any violation of the rules is detected at compile-time with a clear error message indicating the problem.

Restrictions on the placement of Construct statements are intended to ensure that exactly one Construct statement is executed for each base class in an extension class constructor. In addition, there are also some limitations on references to base or extension class members inside the extension class constructor. These restrictions are intended to prevent references to members of classes that are “incomplete” because the relevant constructor has not been run for the object yet. The final restrictions on extension class constructors are that the %this variable cannot be assigned to a variable.

All of the various restrictions on constructors are detected at compile-time, so if an extension class constructor compiles successfully, you can be sure that all the rules have been observed.

Polymorphism

Polymorphism is the ability of an object variable to refer to objects of the variable's class, or to objects of an extension class of the variable's class. For example, if there is a Mammal class and the Otter class extends the Mammal class, an object variable of the Mammal class could refer to a Mammal object or an Otter object (since all Otters are Mammals). An Otter object variable can always be assigned to a Mammal variable:

%tarka     is object otter
%fuzzy     is object mammal
 ...
%tarka = new
 ...
%fuzzy = %tarka

After the assignment, the %fuzzy variable can be used as any other Mammal object variable, even though the referenced object is actually an Otter — again, all Otters are Mammals. Note, however, that the %fuzzy variable cannot be used to invoke Otter-specific methods, because the determination of which method is to be run for a method invocation is done at compile-time, and the compiler has no way of knowing that %fuzzy would end up referencing an Otter object.

Polymorphism can also be used in cases of implied assignments. For example, if there is a method in class Zoo that takes a Mammal input object:

class zoo
  subroutine brushFur(%animal   is object mammal)
end class

It is possible to invoke this method passing an Otter variable as the input parameter:

%tarka     is object otter
%bronx     is object zoo
 ...
%tarka = new
 ...
%bronx:brushFur(%tarka)

This is logically equivalent to assigning %tarka to the %animal input parameter.

A slight variant on this is when a base class method is called via an extension class variable, either via the Inherit keyword in the Extends clause, an Inherit statement in the extension class Public or Private block, or an explicit base class reference on the invocation.

For example, if the Otter class is defined as follows:

class otter extends mammal inherit

And if there is a LiveBirth method in the Mammal class, the following code calls that method:

%tarka     is object otter
 ...
%tarka = new
 ...
%tarka:LiveBirth

Part of this call is equivalent to polymorphic assignment of the %tarka variable of class Otter to the %this variable of class Mammal in the LiveBirth method. Exactly the same kind of implied assignment would be done if the method invocation was via an explicit class specification:

%tarka     is object otter
 ...
%tarka = new
 ...
%tarka:(mammal)liveBirth

All the examples discussed here are explicit or implicit assignments from extension class variables to base class variables. This kind of assignment is sometimes called a widening assignment: an extension class is considered to be a subset of the base class (again, think Otter and Mammal), and assignment from an extension class variable to a base class variable is from a more specific class to a more general class, hence a widening assignment.

Some object-oriented languages also allow what are called narrowing assignments — assignments from a base class variable to an extension class variable. Janus SOAP ULI does not allow such assignments. That is, the following assignment from %fuzzy to %tarka is not allowed and results in a compilation error:

%tarka     is object otter
%fuzzy     is object mammal
 ...
%fuzzy = %(otter):new
%tarka = %fuzzy

While initially this might seem like a rather arbitrary and problematic limitation on polymorphism, there are some good reasons why this is not the case:

• It is exceedingly rare that one would even knowingly try such an assignment, much less need to do such an assignment.
• Such an assignment might fail.

In the above example, it's clear from the code that %fuzzy would reference an Otter object. But, suppose %fuzzy actually contained a reference to a Kangaroo object, which is also a Mammal but is most definitely neither a base nor an extension class of Otter. It would seem clear that the assignment should fail and that, in the general case, the failure of the assignment could only be determined at run-time.

Languages that allow narrowing assignments simply compile the assignments, and if the assignment fails, produce a run-time error. Such languages make it the programmer's job to write code in such a way as to avoid such errors, not the language's job to present arbitrary restrictions to prevent the programmer from doing so.

Unfortunately, in the case of narrowing assignments, almost anything a programmer is likely to do to prevent narrowing assignment errors is likely to have bad code maintainability implications.

Dynamic Dispatch

While inheritance and polymorphism can be useful in and of themselves, they are relatively limited and incapable of dealing with truly complex relationships between base and extension classes. More specifically, they provide no way of having extension-class specific processing performed when needed.

Version 6.7 of the Janus SOAP ULI adds support for dynamic dispatch, frequently refered to as Dynamic Dispatch According to Object Type (DDATOT). Using dynamic dispatch you can declare a function in the Animal class as overridable:

class animal
   public
     ...
     function nextFeeding is float overridable
     ...
   end public
   ...

The actual implementation of this overridable method then provides a default NextFeeding method for all Animal class objects. For example, the following implementation makes the rather silly assumption that most animals need to be fed every eight hours (with seconds as the time units):

function nextFeeding is float overridable
   return %this:lastFeeding + 8 * 60 * 60
end function

Now, any class that extends the Animal class could provide an alternative NextFeeding function:

class bat extends animal
   public
     ...
     function nextFeeding is float -
                           implements nextFeeding in animal
     ...
   end public
   function nextFeeding is float -
                           implements nextFeeding in animal
      ... bat specific next feeding calculations
   end function
   ...

But how does one invoke the appropriate NextFeeding method for a particular object? The answer is, by simply invoking the NextFeeding method in the Animal class:

%creature     is object animal
 ...
print %creature:nextFeeding

When the Nextfeeding method is invoked in the above example, Janus SOAP ULI determines the true class (remember, %creature can reference something of the Animal class, or of any extension class of Animal) of the object referenced by %creature, and it calls the appropriate NextFeeding method for that object.

Note that this actually achieves a narrowing assignment (assignment of a base class variable to an extension class variable), because the object reference from the base class variable is assigned to the %this variable, which is of the extension class, in the extension class method. This is a very structured and specialized narrowing assignment that avoids many of the problems and pitfalls generally associated with narrowing assignments.

For example, in the following code, the Bat class NextFeeding method will be called, because %creature will reference a Bat object:

%creature     is object animal
 ...
%creature = %(bat):new
print %creature:nextFeeding

Any extension class of the Animal class that doesn't implement the NextFeeding method will simply have the Animal class's NextFeeding method run on its behalf.

Suppose there were no sensible default behavior for a method (as is the case, really, for the Nextfeeding function). Suppose it was expected that extension classes would always provide a class-specific implementation of such a method. Then, instead of declaring the method Overridable, the base class could declare the method as Abstract:

public
   ...
   function nextFeeding is float abstract
   ...
end public

The term Abstract here means that the containing class provides no implementation of the indicated method, but instead, it expects an extension class to do so. Now, if a base class has at least one Abstract method declared, what if the method is invoked on an object of the base class only, that is, not for an extension class? The answer is that there is no sensible thing to do, so you are not allowed to create an instance of an object of the base class only.

Declaring an Abstract method for a class makes the class itself an abstract class. This must be indicated on at least the first declaration for the class, by specifying the Abstract keyword following the class name:

class animal abstract
   ...
   public
      ...
      function nextFeeding is float abstract
      ...
   end public
   ...

If a class is abstract, you can declare variables of that class:

%sickAnimal   is object animal

But you cannot create an object instance of that class. That is, if class Animal is abstract, both of the following two New invocations are invalid:

%sickAnimal   is object animal
 ...
%sickAnimal = new
 ...
%sickAnimal = %(animal):new

However, if a class extends the base class and implements all its abstract methods, an object instance of that class can be assigned to an abstract class variable. For example, if the Bat class implemented all the Animal class abstract methods, the following would be perfectly valid:

%sickAnimal   is object animal
 ...
%sickAnimal = %(bat):new

Note that it is possible to declare a class as Abstract even if it has no Abstract methods. You might do this to leave open the possibility of adding abstract methods to the class in the future. Or you might do this if, for whatever reason, it does not make sense to have an instance of a base class — the class only makes sense when extended.

An abstract class can be extended by another abstract class, and an abstract method can be implemented by another abstract method:

class nocturnalAnimal extends animal
   public
     ...
     function nextFeeding is float -
                    implements nextFeeding in animal abstract
     ...
   end public
   ...

In the case of the preceding example, an extension class of the nocturnalAnimal extension presumably implements the Nextfeeding method.

Sometimes, you may want a method that implements an overridable method to augment rather than replace the overridden method's processing, that is, to do some extra processing before or after the overridden method. An apparent way to accomplish this is to simply invoke the overridden method from inside the implementing method:

function nextFeeding is float implements nextFeeding in animal
  ... stuff before base method processing
  %foo = %this:(animal)nextFeeding
  ... stuff after base method processing
end function

Unfortunately, the above syntax would simply result in the recursive calling of the extension class's implementing method — %this references an object of the extension class, so via dynamic dispatch, the extension class's NextFeeding method would be called. To get around this, a special member name, Super, is provided.

The Super member exists only in methods that implement an overridable method, and it refers to the overridden method without dynamic dispatch. To call an overridden method from an implementing method, you use the Super member like this:

function nextFeeding is float implements nextFeeding in animal
  ... stuff before base method processing
  %foo = %this:super
  ... stuff after base method processing
end function

Note that, as usual, the this: can be left off, so %this:super can be written simply as %super. If the method had parameters, they could be included after the Super, as if the Super was the overridden method name. Note also that Super makes no sense for methods that implement abstract methods, since with abstract methods, there is no base class method for the Super member to reference.

For programmers familiar with other object-oriented programming languages, it is worth pointing out that most of the facilities provided for dynamic dispatch by Janus SOAP ULI are no different than those provided by those other languages. However, some of the defaults in some other languages are different. For example:

• In some languages, all methods are assumed to be overridable unless some keyword (usually Final) is specified after their declarations.
• In some languages, a method in an extension class with the same name as an overridable method in a base class is automatically considered to implement the base class method.

  In Janus SOAP ULI, the Implements clause is required in a method declaration for a method to be considered to implement a base class method.

These differences are present in Janus SOAP ULI to facilitate its support for multiple inheritance, and also, independent of multiple inheritance, to improve the maintainability of Janus SOAP ULI code.

A final point: in many programming languages, the use of dynamic dispatch has a severe performance penalty. This is not the case for Janus SOAP ULI. While there is an exceedingly small performance penalty for using dynamic dispatch, this penalty is so small as to be unmeasurable in most cases. Performance cost should not be a consideration when trying to determine whether dynamic dispatch should be used.

Daemon objects

Sirius Mods 6.7 introduces Daemon objects,which provide a facility for issuing Model 204 commands from inside a User Language request, simulating the calling of programs as if they were subroutines. Daemon objects are much like an object-oriented version of the Sirius $COMMxx $functions, which use Sirius sdaemons to run a command on another thread on behalf of the issuing user. Unlike the $COMMxx $functions, however, Daemon objects offer the advantage that they can execute multiple calls per sdaemon login/logout sequence.

The term “daemon” or “daemon thread” is often used to mean “the sdaemon thread that is activated or involved when you employ or operate on a Daemon object.” The user or thread that invokes a daemon is the “master” or “master thread.”

A daemon thread runs a command on behalf of the issuing user, and the thread is only available to that master user. The thread does not, for example, maintain some context and accept requests from different users.

To pass a command to a daemon, you use the Run method with the command as argument. Two examples follow for the %foo Daemon object:

%foo:Run('OPEN FILE MYPROC')

%list = %foo:Run('I REPORT')

To have a daemon thread run multiple commands, you can specify multiple Run method calls, or you can define the commands as items in a Stringlist, and then specify the StringList as the argument in the Run method. The StringList is fed to the daemon as terminal input and executed item by item until that input runs out. For example, if the commands from the examples above were defined in that order as the items in StringList %testproc, the following statement would include the procedure REPORT from the MYPROC file:

%foo:run(%testproc)

You use a StringList argument in this way to pass a User Language request to a daemon.

Although a daemon thread is request-specific, Daemon objects do have persistence. The daemon thread waits for work as long as the Daemon object exists. Since the Daemon object can be Global or Session as well as not, its span of existence can be arbitrarily long or short, depending on how it is being used.

A daemon thread does not share record locks or transactions with its master thread. Commits and Backouts apply only to the thread that issues them.

If a daemon thread does a user restart, the calling thread does not also restart. However, subsequent Runs and other calls to the restarted daemon result in request cancellation. If the calling thread is logged off or restarted, its associated daemon threads are deleted. A daemon is not automatically restarted if the master restarts.

The daemon does a user restart if it is processing a User Language request that calls for terminal input, and no Run method input follows the end of request.

The Daemon methods

Daemon objects provide support for the following methods:

• Methods to create (New constructor and delete (Discard function) a Daemon object. The New constructor creates a new instance, assigning an sdaemon thread to the new object. The Discard function frees the assigned sdaemon thread (possibly via a BUMP) and deletes the Daemon object. Note: any Daemon objects will be discarded and their sdaemon threads released if the master thread is logged off or restarted.
• Properties for a master to retrieve information about the sdaemon thread associated with a Daemon object instance (HaveDaemon, UserNumber, and LastCommandErrorCount).
• A property for any program to determine if it is running on a thread associated with a Daemon object (AmDaemon).
• A function for opening files or groups on the sdaemon thread associated with a Daemon object (Open). The Open method can only open a file or group that is already open on the master thread, and it assigns the daemon thread the privileges from the master thread.
• A function to send commands and an optional input object to the to the sdaemon thread associated with a Daemon object (Run). The input commands can either be contained in a long string or a stringList. The Run function returns a stringList containing any terminal output produced by the input commands. A SOAP ULI program run on a daemon thread may optionally return an object to the master thread. The ability to pass objects between the master thread and a daemon thread makes Daemon objects a much more powerful application tool than the $COMMxx functions.
• A shared method for a daemon thread to retrieve the input object passed from the master thread (GetInputObject). This subroutine creates an object instance on the daemon thread that is a “deep copy” of the input object passed to the Run function that initiated the program on the daemon thread.
• A shared method for a daemon thread to return an output object to the master thread (ReturnObject). This subroutine also uses deep copy to pass an object from the daemon thread back to the master thread where it is returned into the third parameter of the Run function that initiated the program on the daemon thread.

Copying objects

Sirius Mods Version 6.7 introduces generic (Object class) methods for making copies of User Language class objects, and it also introduces adaptations of those methods for making copies of several Sirius system class objects.

“Shallow” and “deep” copying methods are available. The shallow and deep types differ only in how they handle contained objects: A shallow copy of an object includes a copy of the references to to its contained objects. A deep copy includes the references to its contained objects and it includes a copy of the referenced object itself — and if a contained object itself contains objects, deep copy copies those references and objects, and if any of those objects have contained objects, deep copying continues like this until the chain of objects contained in contained objects is exhausted.

For example, if a simple object (%S) contains multiple variable members, one of which is an object variable(%c, which references an object that has no contained object variables), a shallow copy produces a matching object with matching variable members, including %c. Remembering that %c is a reference and not the actual object, the shallow copy of an object that contains an object pointer thus produces a matching object and object pointer. A deep copy of %S produces two objects: one object that matches %S with a pointer to %c, and one object that is a replica of the actual object that %c references.

For simple objects (objects without contained objects), a shallow copy is the same as a deep copy.

Shallow copies may be most useful with collections, say for sorting an ArrayList. To preserve the original order of a given ArrayList, you make a shallow copy of the collection to avoid the expense of making copies of any ArrayList objects, then you sort the shallow copy on whatever criterion you want. A shallow copy method may also in turn be used as a building block for constructing copy methods of arbitrary complexity for hierarchical object structures.

Deep copies provide a facility for copying an entire arbitrarily complex object forest, and they are probably more widely useful than shallow copies. For example, deep copying is essential internally in Sirius system methods that let you pass an object between two threads and reference the object on both threads.

The Object class copy methods

Two methods are added to the Object class: Copy and DeepCopy. Both methods are functions without arguments that return a new instance of the method object to which they are applied.

%cop = %obj:Copy

%dcop = %obj:DeepCopy

Where:

%cop

A shallow copy (member variable by member variable assignment) of method object %obj.

%dcop

A deep copy (member by member assignment plus duplication of any referenced objects) of its method object %obj.

%obj

A “copyable” User Language object. The Public block of such an object's class must include the Allow Copy, AllowDeepCopy, or both keywords to make available the Copy, DeepCopy, or both methods. You specify these keywords as you would a method declaration, but the method is provided by the system rather than the class programmer. Whether an object is copyable is discussed further below.

Usage Notes

• Not all objects may be copied. For example, a Sirius Socket object is an example of a class that is not copyable, because it has a significant amount of information or state that is not held in the object itself. And what does it mean to copy a network connection?
• Not all objects that that it is possible to copy should be allowed to be copied. As a general rule of thumb, any object that holds information external to its own public or private variables is a good candidate for not being allowed to be copyable. For example, consider a class that is used to manage a record. Object private variables might be dependent on the contents of the record, but if you have multiple instances of the object and the class updates the record, the private variables in one instance could end up out of synch with the record due to updates by another source.
• For an object to be copyable, all it's contained objects must themselves be copyable. The compiler ensures that if an object's class contains an object member (or an object member contained in that object member's “descendant objects,”) whose class definition does not specify Allow Copy or Allow DeepCopy, the original object is not copyable or deep-copyable, respectively.
• Allow DeepCopy does not imply Allow Copy. However, inheritance permits an Allow Copy designated class to have its own Copy method defined, and it permits an Allow DeepCopy designated class to have its own DeepCopy method.
• For all Copy and DeepCopy methods (system or generic User Language), the method object may be null (internally, it is defined with the AllowNull keyword). The output of a copy of a null object is a null object.

Copy methods in the Sirius system classes

Not all system classes provided by the Janus SOAP ULI support copy methods. For example, the following classes do not support copy, typically because of their complexity or their dependence on information that is not held in the objects themselves:

• Socket
• Daemon
• XmlNodeList
• File classes (Record, RecordSet, SortRecordSet, RecordSetCursor)
• HTTP Helper classes (HTTPRequest, HttpResponse)
• SMTP Helper (Email)
• LDAP objects

As described in the previous section, the presence or absence of the Copy and DeepCopy methods in the system classes affects the degree of copyability of any User Language classes that contain objects of these system classes. A User Language class that contains a Daemon object, for example, is not copyable. A User Language class that contains a StringList, though, may be copied or deep copied, subject to the copyability of the other members of the class.

The deep copyability of the individual Sirius system classes also determines the objects that are eligible to be used with Sirius system Daemon objects. Only objects that are deep copyable may be passed to and retrieved from Daemon objects, which may be called by a User Language program to execute commands on a separate thread.

DeepDiscard method

Prior to Sirius Mods Version 6.7, the Discard method was available in most classes to explicitly discard an object variable's underlying object. However, a Discard method would not necessarily discard all objects referenced by the object being discarded if those referenced objects either:

• had other references still around
• had a cycle in them (that is, object A references object B references object A)

To explicitly discard not only an object, but all objects referenced directly or indirectly by that object, the DeepDiscard method is now available.

%object:DeepDiscard

A DeepDiscard method is not allowed against a class that is declared with a Disallow Discard clause, or a class that has direct or indirect references to a Disallow Discard class.

For most system classes, DeepDiscard works identically to Discard. The exceptions to this are:

• XmlNode objects are allowed to be DeepDiscard'ed but are not allowed to be Discard'ed. When an XmlNode is DeepDiscard'ed, the underlying XmlDoc object is discarded.
• When an XmlNodeList object is DeepDiscard'ed, not only is the XmlNodeList object discarded, but so is the underlying XmlDoc object.

Booleans Usable in Logical Tests

Boolean enumeration values (True and False) are now usable in contexts where they would be, well, logical. For example, they are allowed as the condition in an If statement:

%recset   is object recordSet in file sirfiled
 ...
find records to %recset
   rectype = 'FILE'
end find
 ...
if %recset:isEmpty then
   print 'No records found!'
end if

In the above example, the isEmpty method returns a Boolean enumeration value,. that is, True or False. Strictly speaking, the If clause expects a numeric zero or non-zero value as its operand, but in this context Janus SOAP ULI now automatically converts a True to a 1 and a False to a 0.

Other places where a Boolean value can be used, that is, where it's automatically converted to the 0 or 1 that User Language expects are:

• As a Repeat statement operand.
• As an operand for a logical operator such as Not, And or Or. This would usually be in an If or Repeat statement.

System and Subsystem methods for system-wide objects

Sirius Mods Version 6.7 adds methods to the Janus System and Subsystem classes that make designated objects available to all users in an Online or of a subsystem. Such objects, referred to as system-wide objects, are made available via deep copy, so only deep copyable objects are eligible.

An object becomes system-wide if and only if it is saved by the System class SetObject method or by the Subsystem class SetObject method. If saved by the System class SetObject method, the “system” in system-wide refers to all users in the Online; if by the Subsystem SetObject method, all users in the current or a specified subsystem.

System-wide objects belong to a namespace that is not the same as that for System and Subsystem longstrings. That is, both a System longstring and a system-wide object may be called by the same name at the same time.

The new methods are one System and one Subsystem class version of each of the following:

SetObject

Makes an object available system-wide with a specified name.

GetObject

Retrieves a copy of the specified system-wide object.

DeleteObject

Deletes the specified system-wide object.

ListOfObjects

Returns a StringList containing information about system-wide objects.

The ability to set and retrieve objects shared between all the users of a subsystem as well as all users in an online provides a high-performance vehicle for sharing information, eliminating the need to cordinate access to records in “work” files.

Internal parameter names

The InternalNames statement is now available to map external parameter names (the names on the method declaration) to internal ones (those used in the method code).

In the following example, the parameter names %petrol and %oil are mapped to internal names %parm.petrol and %parm.oil, respectively:

subroutine add(%petrol is float nameRequired optional,  -
               %oil    is float nameRequired optional)

   internalNames
      %parm.petrol   is %petrol
      %parm.oil      is %oil
   end internalNames
      ...
   %private.petrol = %private.petrol + %parm.petrol
   %private.oil    = %private.oil    + %parm.oil

The parameters are then used to update some (presumably) private class variables.

Named parameters

Named parameters are now supported for both system and User Language methods. For example, the ParseLines method in the StringList class has an optional named parameter called StripTrailingNull:

%list:ParseLines(%string, stripTrailingNull=false)

Named parameters can be either name allowed (can be accessed by name, but don't have to be) or name required (must be accessed by name). For User Language methods, named parameters are indicated by the NameAllowed and NameRequired keywords in the method declaration:

subroutine display(%customerId is string len 10,            -
                 %startYear is float optional nameAllowed,  -
  %showFamily is enumeration boolean optional nameRequired, -
                   %showEmployer is enumeration boolean     -
                                     optional nameRequired, -
                     %showMedical is enumeration boolean    -
                                     optional nameRequired)

Such a method might be invoked as follows:

%company:display(%crn, 2002, showMedical=true,
                 showFamily=true)

or

%company:display(%crn, showMedical=true,
                 showFamily=true, startyear=2002)

Class statistics

The new OBJSTAT User 0 parameter controls the display of journal messages that contain user statistics about Janus SOAP ULI object usage per request. The messages specify server table usage (VTBL and STBL) and object-swapping counts per object class and summed for all classes. These messages provide information that allows one to tune the memory management algorithms used by the Janus SOAP ULI.

You can set OBJSTAT to display object statistics after program compilation, evaluation, or both. OBJSTAT is a typical Model 204 bitmask parameter that is also per-user and resettable. It contains the following bit options, two or more of which you can select by specifying the sum of their bit values:

X'00'

Display no OBJSTAT statistics; this is the default.

X'01'

Display post-compilation object statistics to the journal.

X'02'

Display post-evaluation object statistics to the journal.

X'10'

Display post-compilation object statistics to both the terminal and the journal.

X'20'

Display post-evaluation object statistics to both the terminal and the journal.

Note: X'22' is the same as X'20'; X'10' is the same as X'11'; and X'30' is the same as X'31', X'32', or X'33'.

You can set OBJSTAT in the User 0 stream, and you can reset it with the RESET command (for example, R OBJSTAT X'33') or with the $RESETN function (for example, $RESETN('OBJSTAT', $X2D('33'))).

Compiler directives for modifying object server space allocation

Sirius Mods Version 6.7 adds the MaxObjects, MinObjects, and AddObjects options to the Sirius compiler directive, which adjust the number of Janus SOAP ULI objects for which VTBL/STBL space is allocated at request compile time.

By default, that is, with no compiler directives specified, Janus SOAP ULI scans a request for object references (like, object variable declarations), and it allocates space for at most three (usually two) objects per class per request. This ensures that only a small amount of server table space is used for objects, and no object swapping occurs until more than two or three objects in a class are instantiated at the same time. This approach also prevents an exceptional, object-heavy request from forcing server tables to be huge for all requests.

For an overview of object allocation, including the tools available for monitoring and tuning, please refer to Notes for Sirius Mods Version 6.7 or the Janus SOAP Reference Manual.

New SIRCOMP parameter bits

The X'02' and X'04' bits of the SIRCOMP user parameter now control what happens at end of procedure during a compilation:

• If the X'02' bit is set, and a compilation that was started inside a procedure (the Begin statement was in a procedure) is still active when the last Included procedure is closed (return to command prompt on an interactive thread), the compilation is terminated with an error.
• If the X'04' bit is set, and a compilation that was started inside a procedure is still active when the procedure that contained the Begin is closed, the compilation is terminated with an error.

Both these settings are intended to minimize the problems or annoyances associated with a forgotten End statement in a User Language procedure, or, more commonly, unmatched quotes resulting in an End statement being “swallowed” as part of a literal (producing the classic M204.1248: LOOKING FOR CLOSE QUOTE message). A compilation ended because of the SIRCOMP X'02' or X'04' setting also automatically closes any unclosed quotes or unclosed comment blocks.

Janus SOAP Xml Classes

Several enhancements were made to the Janus SOAP Xml* classes (the XML API) in Version 6.7.

Audit and Trace methods

The Trace and Audit methods for XmlDoc and XmlNode objects are just like the Print method: the result goes to the selected Trace stream (like the Trace statement), or, as US lines, to the audit trail (like the Audit statement). The default indentation width on Print is 3; on Audit and Trace it is 1.

AdjacentText property

Janus SOAP now tolerates the following operations if the value of the XmlDoc's AdjacentText property is Combine:

• DeleteSubtree between Text nodes
• AddText applied to an Element whose last child is a Text node
• InsertTextBefore applied to a Text node
• AddSubtree and InsertSubtreeBefore applied to a source subtree that is a Text node

When one of these operations occurs, the values of the Text nodes are combined to form a new Text node which takes the place of the former Text node(s), which is (are) deleted. This node deletion, as is typical, also causes any XmlNode or XmlNodelist pointers to the former Text nodes to be set to Null.

The default value of AdjacentText is Disallow, which continues the same behavior (request cancellation) that occurs with these cases in version 6.6 of the Sirius Mods.

XmlDecl option on Serial method

The Serial method now allows the string XmlDecl as one of the options in its second argument. When this option is present, the serialized XmlDoc will contain the “XML Declaration” (), if the value of the Version property is not the null string.

Note that this option may only be specified if the top of the subtree being serialized is the Root node.

LoadParameterInfo method

This new XmlDoc class method populates an XmlDoc with information about one or more Model 204 parameters.

Call %doc:LoadParameterInfo([paramOrClass], [classOrParam])

Where: paramOrClass is either one of the following options, and classOrParam is the other:

• A pattern used to select matching parameters,
• One or the combination of both of the strings Base and Sirius. Sirius indicates that information about matching Sirius Mods parameters is obtained. Base indicates that information about the “base” (that is, not created by Sirius) Model 204 parameters is obtained.

Both arguments of this method are optional, default to the null string, and leading and trailing blanks and case are ignored. Either argument option (parameter pattern or Base/Sirius string) can be specified first.

For both types of argument, a null string indicates that all of the respective items are processed. For the parameter-match pattern, an asterisk also indicates that all of the respective items are processed.

The information is returned in an XmlDoc, with element and attribute names which, together with explanations in the Model 204 Command Reference Manual, should be evident.

WspNewline option for deserialization

Whitespace handling has changed in the following, which are the methods that parse an XML document from its serialized form into the internal XmlDoc data structure. Except where noted, these all have an XmlDoc as the method object:

• LoadFromStringlist
• LoadXml
• ParseXml (in the HttpResponse class)
• WebReceive

The changes are as follows:

• A new algorithm is used for the default handling of whitespace during deserialization. This algorithm can also be specified using the WspNewline option. The purpose of WspNewline is to remove the whitespace that was inserted to make the structure of an XML document easier (for a person) to read. The operation of WspNewline is to remove that leading or trailing whitespace in the value of a Text node, if the sequence contains a carriage return or linefeed character.
• Stripping of all leading and trailing whitespace, and conversion of each sequence of whitespace to a single space, is the behavior obtained with the WspToken option. This behavior was formerly specified with the WspNorm option; that option keyword is no longer available.

WspToken was formerly the default for the deserialization methods, but it no longer is. The new default is WspNewline.

Character references for serializing whitespace

Serialization of the tab, carriage return, and linefeed characters has changed (depending on the method and the node type) to use character references as specified in the XML Canonicalization specification (http://www.w3.org/TR/xml-c14n). The EBCDIC and corresponding ASCII encoding of these characters is:

character name	EBCDIC value	ASCII value
tab	X'05"	X'09"
carriage return (CR)	X'0D"	X'0D"
linefeed (LF)	X'25"	X'0A"

When an Attribute node is serialized, a character reference is used for all of these characters, as follows:

character name	character reference
tab		
carriage return (CR)	
linefeed (LF)	


Also, when a Text node is serialized with the Print method, these same character references are used for all of these characters.

When a Text node is serialized with the non-debugging serializers, only CR is serialized (as above) using a character reference. The non-debugging serializers are:

method name	class name(s)
Serial	XmlDoc and XmlNode
WebSend	XmlDoc
Xml	XmlDoc
AddXml	HttpRequest

Support for xml:space attribute

The xml:space attribute is now allowed, and the meaning of this attribute is honored in serialization and deserialization methods.

LoadFromStringlist newlines

The LoadFromStringlist method now inserts a newline character after each item in the StringList as part of concatenation prior to deserialization. This newline is usually removed (as leading or trailing whitespace) by the method's whitespace handling options. However, if Text node values are split between successive StringList items, if xml:space="preserve" is in effect, or if WspPreserve is used to deserialize the Stringlist, the newlines are not removed.

Improved XPath and other performance after some XmlDoc updates

There are some XPath expressions (for example, '//someElement/anotherElement') and some methods (for example, Difference) whose performance can be affected by the order in which nodes were added to the XmlDoc. In some cases, the extra CPU and DKRD consumed for this is necessary for the Janus SOAP algorithms. In other cases, the structure of an XmlDoc doesn't actually require extra CPU and DKRD, but the heuristics used by Janus SOAP are not able to detect this.

In version 6.7, many cases that formerly used extra CPU/DKRD are now handled more efficiently; that is, these Janus SOAP heuristics have improved.

Janus SOAP StringList Class

The following sections describe changes in the Janus SOAP StringList class made in Version 6.7.

ParseLines and CreateLines methods

These methods facilitate moving line-end character delimited data (as typically exists on most non-EBCDIC systems) to StringLists and vice versa. Since line-end delimited data typically comes from non-EBCDIC hosts, these methods are most likely to be used in applications that communicate with such hosts, such as Janus Web Server and Janus Sockets applications.

The ParseLines method takes as input a longstring and an optional line delimiter set, and it breaks the longstring up into StringList items, using the indicated delimiters as the line separators. For example, the following method loads the names of three popular sandwich contents onto separate StringList items:

%contents   is object stringList
  ...
%contents:parseLines('Bacon/Lettuce/Tomato', ' /')

The space before the slash character, is the delimiter-set delimiter character (got that?), that is, the character used to separate multiple delimiters, should there be more than one. As this example illustrates, the ParseLines method can be used for general-purpose parsing, though this was not really its intent, and it is somewhat limited for this purpose.

The main use of ParseLines is expected to be in parsing text received into a longstring via $web_input_content, $web_file_content, or $web_output_content. As such, the default delimiter set for the ParseLines method is X'0D', X'25', and X'0D25' (the EBCDIC carriage-return, line-feed, and carriage-return/line-feed characters).

The CreateLines method is the inverse of ParseLines: it takes the contents of a StringList and converts it into a line-end character delimited string. In the following example, the contents of stringList %sendData are sent over a Janus Sockets connection (using a Socket object) as line-feed delimited lines:

%sock       is object socket
%sendData   is object stringList
  ...
%sock:send( %senddata:createLines($x2c('25')) )

In this example, the delimiter parameter ($x2c('25')) was really unnecessary because it is the default. In this example, one would presume that the socket is in CHAR mode, that is, data is being translated from EBCDIC to ASCII. Obviously, the CreateLines method does nothing that couldn't be done quite easily in User Language — it is just a little more convenient and efficient.

BinaryProcedureEncode and BinaryProcedureDecode methods

These methods facilitate converting data in a longstring into the format used for storing binary data in procedures by Janus Web Server. This format is necessary if binary data is to be stored in Model 204 procedure files, because standard procedure formats are not amenable to storing binary data.

The BinaryProcedureEncode method takes data from a longstring and places it on a StringList, from which it could then be stored in a procedure. In the following example, a GIF (graphical image) is retrieved from another web server using a Janus Sockets HTTP Helper request, and then it is moved onto a StringList with the special binary procedure encoding:

%req       is object httpRequest
%resp      is object httpResponse
%gif       is longstring
%procData  is object stringList
 ...
%resp = %req:get
%gif  = %resp:content(1)
%procData = new
%procData:binaryProcedureEncode(%gif)

The actual saving of the data to a procedure is not shown.

The BinaryProcedureDecode method is the inverse of BinaryProcedureEncode: it takes the contents of a StringList in the Janus Web Server binary procedure encoding and converts it to a longstring. In the following example, a GIF is sent to another web server from a Model 204 procedure:

%req       is object httpRequest
%resp      is object httpResponse
%gif       is longstring
%procData  is object stringList
%rc        is float
 ...
%rc = $procopn('MONKEY.GIF', 'IMAGES')
%procData = new
%procData:appendOpenProcedure
%gif = %procData:binaryProcedureDecode

%req = new
%req:multiPartFormEncoding = true
%req:addField('IMAGE', %gif)
   ...
%resp = %req:post

AppendJournalData method

The AppendJournalData method is an object-oriented replacement for $SIRJGET and is only available to customers licensed for SirScan.

Janus Sockets

Version 6.7 of the Sirius Mods continues the trend of adding high-level object-oriented APIs for common protocols based upon TCP/IP. These APIs require that a customer be licensed for both Janus Sockets and Janus SOAP.

Named parameters on New constructor for Socket object

All but the first parameter (the client port name) for the Socket object New constructor are now Named parameters (parameters passed by name rather than position).

The following example illustrates the use of named parameters on the New constructor to create a new socket instance and to connect it to Sirius Software's secure web site:

%socket is object Socket
%socket = new(host='sirius-software.com', port=443, ssl='SSL')

The LDAP Helper

The Lightweight Directory Access Protocol (LDAP) is a a standardized protocol (based upon Internet RFC 1777) for retrieving information from a directory service. LDAP clients can be used to validate identity and retrieve personalization information from a directory service. Virtually all commercial directory systems, such as Microsoft's Active Directory or IBM's Security Server support LDAP access.

The LDAP Helper for Janus Sockets is a high-level, object-oriented interface to client sockets that simplifies writing LDAP clients in User Language. It requires no understanding of socket level programming or the format of LDAP requests and responses. The LDAP Helper methods allow a User Language program to act as an LDAP client to access and retrieve directory information through an LDAP server. The LDAP server may be running on any platform to which the LDAP client online can make a TCP/IP connection.

Detailed information on how to use the LDAP Helper may be found in the Janus Sockets Reference Manual.

Feature summary

The Janus LDAP Helper provides the following capabilities:

• Read access to X.500 and LDAP v2 directory services.
• One-step connection and login to an LDAP server (with user ID and password passing as well as also anonymous logins).
• Multiple search filters, each in a separate method.
• Text-only retrieval: all returned data is automatically converted from ASCII to EBCDIC.
• Automatic deserializing of returned data into XML in an XmlDoc object.
• A limit of approximately 1300 bytes to the data sent in or returned from a single query of the server.
• Optional retrieval of only the directory entry attribute names, that is, the names without the corresponding attribute values.
• Optional SSL (Secure Sockets Layer) data transmission.

The following LDAP features are not currently supported by Janus LDAP:

• Kerberos user logins.
• Modifying, deleting, or adding directory content.
• Full compliance with LDAP v3 (for example, UTF-8 is not supported).
• Arbitrary, user-constructed search queries (RFC 1960 syntax featuring boolean operators is not supported).
• Restart of aborted transfers.
• Limiting the quantity of the server data returned or the number of entries returned.

Using the LDAP Helper

The Helper makes the information in LDAP directories more easily accessible by removing LDAP protocol concerns from the programmer. To retrieve data from an LDAP server, applications must:

1. Define a Janus CLSOCK port.
   • Use the JANUS DEFINE command to
     • Create a TCP/IP port for your Model 204 LDAP client application.
     • Indicate the remote LDAP server identifier and port number (or a pattern that allows the specific server to be specified by an Ldap class method).
     • Set a timeout value for the LDAP connections.
   • Use the JANUS NAMESERVER command to let you reference remote hosts by name rather than IP address.
   • Use a JANUS CLSOCK command to specify access rules for your port.
   • Use the JANUS START command to start your port.
2. Bind a connection and log in to an LDAP server (in your User Language request, a single Bind method statement performs these actions).
3. Send a search query to the LDAP server, using one of the multiple Find methods, which provide a variety of search filters.
4. Optionally, extract particular data from the data returned from the LDAP server, using the Janus SOAP XML Api.
5. End your session when ready, using the Unbind method to log off from the LDAP server and deactivate the connection.

The SMTP Helper

The Simple Mail Transfer Protocol (SMTP) is a a standardized protocol (based upon Internet RFC 821) for transfering mail from a client application to a store and forward mail server. SMTP standardizes the plumbing between all e-mail services and is one of the most pervasive protocols of the Internet.

The SMTP Helper for Janus Sockets is a high-level, object-oriented interface to client sockets that simplifies composing and sending e-mail messages from User Language programs. It requires no understanding of socket level programming or the format of SMTP requests and responses. The SMTP Helper methods allow a User Language program to act as an SMTP client to compose and forward e-mail messages and attachments through an SMTP server. The SMTP server may be running on any platform to which the SMTP client online can make a TCP/IP connection.

Detailed information on how to use the SMTP Helper may be found in the Janus Sockets Reference Manual.

Feature summary

The Janus SMTP Helper provides the following capabilities:

• Creating and sending general purpose e-mail for SMTP.
• Setting e-mail content using longstrings or stringlists.
• Sending MIME content (attachments and alternative content).
• Sending to multiple recipients.
• Access to status (error or confirmation messages).
• Automatic translation between ASCII and EBCDIC character encodings.

Using the SMTP Helper

The SMTP Helper makes it easy to send mail messages by eliminating the need for programmers to know the communication protocol required to relay messages to an SMTP server. To send e-mail to an SMTP server, applications must:

1. Define a Janus CLSOCK port.
   • Use the JANUS DEFINE command to
     • Create a TCP/IP port for your Model 204 SMTP client application.
     • Indicate the remote SMTP server identifier and port number (or a pattern that allows the specific server to be specified by an SMTP class method).
     • Set a timeout value for the SMTP connections.
   • Use the JANUS NAMESERVER command to let you reference remote hosts by name rather than IP address.
   • Use a JANUS CLSOCK command to specify access rules for your port.
   • Use the JANUS START command to start your port.
2. Create an e-mail request using the SMTP methods. In your User Language request, you must instantiate an e-mail object, then add headers, content, and attachments using the SMTP methods.
3. Send the e-mail object to an SMTP server with the mail method. The mail method connects to the SMTP server, forwards the mail object, closes the connection, and returns the status. The programmer does not need to manage the communication connection.

The SMTP methods

AddBcc subroutine

This callable method adds a "blind carbon copy" recipient to an instantiated email object.

AddCc subroutine

This callable method adds a recipient to an instantiated email object. An email must have at least one recipient before it can be sent with the mail method.

AddRecipient subroutine

This callable method adds a recipient to an instantiated email object.

AddHeader subroutine

This callable method adds a header to the instantiated email object. No validation is performed on the header name or its value, except that content headers are not allowed. "Content-" headers are automatically added whenever either of the SetBody or AddPart methods are invoked.

Port property

This settable property sets or gets the value of the TCP port number for the e-mail object.

Host property

This property sets or gets the value of the TCP host name for the e-mail object.

Mail function

This function forwards the e-mail content to an SMTP server and returns a value indicating the status of the operation.

SetBody subroutine

This subroutine sets the content for the main body of the e-mail. Optional named parameters allow control of the MIME type of the content and base-64 encoding.

AddPart subroutine

This subroutine adds an attachment to the e-mail object. Optional named parameters control the MIME type of the content, base-64 encoding, and a name for the attachment.

GetReplyCode subroutine

This function returns the numeric code of the most recent response from the mail server. If the mail method has not yet been invoked, the reply code will be zero.

GetReplyText subroutine

This function returns the character string associated with the most recent response from the mail server. If the mail method has not yet been invoked, the reply string will be null.

Janus Web Server

$web_put_text and $web_put_bin are longstring capable

$web_put_text and $web_put_bin now accept and correctly process longstring inputs. This is a sight backward incompatibility with previous versions. In addition, $web_put_binary has been introduced as a synonym for $web_put_bin.

New longstring $Web Parameter $functions

Longstring versions of many of the standard $web parameter $functions have been added. Since these $functions return longstrings, they do not have a starting position and length parameter — substringing can be accomplished with standard longstring $functions.

The new $functions are:

$web_parm_lstr

Corresponds to $web_parm.

$web_hdr_parm_lstr

Corresponds to $web_hdr_parm.

$web_form_parm_lstr

Corresponds to $web_form_parm.

$web_isindex_parm_lstr

Corresponds to $web_isindex_parm.

An error was also found in $web_get_cookie_lstr — it allowed but ignored a third and fourth parameter. This error was fixed, but it introduced a backward incompatibility.

New URL_parm equivalents of ISINDEX functions

The term “isindex” has largely fallen into disuse, but the Janus Web Server $functions still use this term. While there is no “official” term for what are called Isindex parameters in the Janus Web Server $functions, the most common term in the industry seems to be “URL parameters.” For compatibility with more widely used terminology, there are now URL_parm equivalents of the Isindex functions:

$web_num_url_parm

Corresponds to $web_num_isindex.

$web_url_parm

Corresponds to $web_isindex_parm.

$web_url_parm_len

Corresponds to $web_isindex_parm_len and $web_isindex_len.

$web_url_parm_line

Corresponds to $web_isindex_parm_line and $web_isindex_line.

$web_url_parm_lstr

Corresponds to $web_isindex_parm_lstr.

$web_url_parm_name

Corresponds to $web_isindex_name

$web_url_parm_num_line

Corresponds to $web_isindex_parm_num_line and $web_isindex_num_line.

Note that the shortened versions of some of the Isindex $functions (for example, $web_isindex_len for $web_isindex_parm_len) are not provided with Url equivalents. This is because they sounded a bit confusing, since the URL has meaning independent of the URL parameters. For example, one might expect $web_url_len to be the length of the URL, not the length of a URL parameter.

RAWINPUT port definition parameter

A new Janus Web Server port definition parameter, RAWINPUT, tells Janus Web Server to save the raw input stream for an HTTP Post, regardless of the mime-type set by the client. This has two basic advantages:

1. The raw input content for an HTTP Post is always available to Janus Web Server applications (via $web_input_content) regardless of the mime-type. This could be useful for debugging or perhaps for logging input content.
2. Janus Web Server can interact correctly with clients that don't set the mime type, regardless of what these clients send.

   For input with no mime-type set, Janus Web Server assumes that the content is application/x-www-form-urlencoded (form Post) encoded. Prior to RAWINPUT, if Janus Web Server discovered, after reading some of the input content, that the client sent data in some format other than application/x-www-form-urlencoded encoding (say, XML format). it was too late, and the request was rejected for having an invalid format.

   With the RAWINPUT parameter set, Janus Web Server first loads the input content into CCATEMP, and then, if the mime type is set to application/x-www-form-urlencoded or not set at all, determines if it has the application/x-www-form-urlencoded format. If not, the request is not rejected, and the Janus Web Server application can still access the data (which is likely to be XML format).

RAWINPUTONLY parameter for JANUS WEB ON rules

A new Janus Web Server ON rule parameter, RAWINPUTONLY, tells Janus Web Server to save the raw input stream for an HTTP Post, regardless of the Post data content-type set by the client, and to not parse the input content into form fields, regardless of the Post data content-type. This is very similar to the port definition RAWINPUT parameter with the exception that:

• It's an ON rule parameter so can be set for specific URLs.
• The port definition RAWINPUT parameter does not prevent Janus Web Server from trying to parse the form parameters if the content-type for the Post was set to application/x-www-form-urlencoded or multipart/form-data. RAWINPUTONLY prevents this parsing, so protects Janus Web Server applications from errors in this parsing. These errors include invalid form data errors and request buffer full errors.

The RAWINPUTONLY parameter for JANUS WEB ON rules is, perhaps, most useful for allowing requests with a large number of parameters to be processed without having to allocate an extremely large request buffer to hold all the posted parameters. In fact, if there are enough form parameters, the maximum request buffer size (65535 bytes) might not be sufficient to hold all the form data in a post. In such a case, the RAWINPUTONLY parameter is the only way to prevent the request from failing with an

MSIR.0353 Insufficient Web request buffer space

If the RAWINPUTONLY parameter is in effect for a URL, the form fields are no longer available with the $Web_form and $Web_parm functions (that is, functions that begin with these words) though the $Web_parm, $web_isindex, and $web_url_parm functions can still be used to access URL parameters. When using RAWINPUTONLY, the only way to process the form parameters is by retrieving the form parameters into a longstring using the $Web_input_content method. To separate the various parameters, this longstring must then be parsed and (usually) URL decoded. If the Post used the default form data encoding of application/x-www-form-urlencoded then each parameter/value pair is separated with an ampersand (&). Processing is considerably more complicated if the encoding is multipart/form-data. For Janus SOAP customers, the StringList class ParseLines method provides a simple, efficient way of parsing a form parameter list with application/x-www-form-urlencoded encoding:

%formParms     is object stringList
 ...
%formParms = new
%formParms:parseLines($web_input_content('TEXT'), ' &')

This produces a StringList that contains items of the format fieldname=value. Assuming that none of the form field names have been URL encoded by the browser (a reasonable assumption for most latin character field names), this StringList is in a format that can be easily, though not prettily, searched. For example, the following code locate's the field named OrderNumber:

%itemNum = %formParms:locate('Order=', , 1, 6)

There are some things worth noting here:

• The search is case sensitive, though the Locate method does have a case-insensitive search flag. Fortunately, almost all browsers return form field names in the case that was specified in the <input> tags. Still, the case-insensitive search parameter could be set for Locate if needed.
• The equals sign is specified to prevent accidental matches on other fields that begin with Order, such as, say, OrderDate. While it can be left off if the programmer is confident there won't be such accidental matches, this is not recommended.
• The column range is also specified to prevent accidental matches. While an equals sign should be URL encoded by the browser, and so an “Order=” in a value (encoded as “Order%3D”) should not cause an accidental match, one could still get an accidental match with, say, “PreviousOrder=”. Specifying the column range has the side-benefit of making the search more efficient by limiting it to the start of each StringList item.

For form field names that are used more than once on a form, the values beyond the first would need to be retrieved by specifying a starting item number (second) parameter on the Locate method.

Once the desired item number is located, the next step is to retrieve the value. In the case of a field name with a known length, this can be done easily with the Item method and the $lstr_substr function:

%itemNum = %formParms:locate('Order=', , 1, 6)
%order = $lstr_substr(%formParms:item(%itemNum), 7)

Unfortunately, the value in %order above will be URL encoded, that is, spaces will be replaced by pluses and any special characters (such as ampersands or equals signs) will be encoded with a percent sign followed by the hexadecimal value of the ASCII code. For example, the string “90% = 9/10” would be encoded as “90%25+%3D+9%2F10”. Even more unfortunately, Janus Web Server does not provide a URL decode function (there is a $Web_URL_encode to do URL encoding), so URL decoding must be done in User Language. Fortunately, such decoding could be easily packaged up in a method or complex subroutine. The following illustrates a shared method in a class called URL that performs this decoding:

class URL
   public shared
      function   decode(%value is longstring) -
                 is longstring
   end public shared

   function   decode(%value is longstring) -
              is longstring
      %pos    is float

      %value = $lstr_translate(%value, ' ', '+')
      %pos = 1
      repeat forever
         %pos = $lstr_index(%value, '%', %pos)
         if not %pos then
            loop end
         end if
         %value = $lstr_substr(%value, 1, %pos - 1) with -
                  $ebcdic($x2c( -
                     $lstr_substr(%value, %pos + 1, 2) -
                  )) with -
                  $lstr_substr(%value, %pos + 3)
         %pos = %pos + 1
      end repeat
      return %value
   end function
end class

With this function available, the value in %order in the previous example can be easily URL decoded:

%itemNum = %formParms:locate('Order=', , 1, 6)
%order = $lstr_substr(%formParms:item(%itemNum), 7)
%order = %(url):decode(%order)

Subsequent releases of the Sirius Mods will provide a native URL decode function, as well as other $functions or methods to simplify processing form parameters in an application using RAWINPUTONLY.

$web_input_content and $web_output_content functions

These two new functions make it possible to examine either the input content sent by the client or the output content currently in the Janus Web Server output stream. Both these $functions return content as a longstring, which can subsequently be parsed and/or logged.

$web_input_content can be used to examine data from the client in the following situations:

• An HTTP Put.
• An HTTP Post, if the mime-type is set to something other than application/x-www-form-urlencoded or multipart/form-data.
• Any HTTP Post, if the RAWINPUT parameter is set on the port definition.

$web_output_content can be used to examine the following:

• Data in the Janus Web Server output stream resulting from Print or Html/Text statements when web capture is on ($web_on).
• Data resulting from $web_proc_send.

$web_output_content cannot examine output data in these cases:

• After a $web_done
• After a $web_proc_send without the MORE parameter
• After a $web_flush

Both $web_input_content and $web_output_content take a single, string, input parameter, which can be set to Binary or Text to indicate whether data is to be left untranslated or to be translated from ASCII to EBCDIC (as text is almost certain to use ASCII encoding).

$web_output_type function

This function makes it possible to determine the current output mime-type setting set by either JANUS WEB ON rules or by the $web_type function. It might prove useful for determining the meaning of the contents of the output stream in code that is shared among many applications, though of course, it is highly dependent on those applications having already set $web_type.

$web_file_content function

This new function is introduced to make it possible to load the contents of a file (in a multipart form file upload) to a longstring. This has several advantages over the existing techniques ($web_proc_receive and $web_list_receive) for loading multipart form file data:

• It is freed of the line-length issues that were problematic for the old functions.
• It provides the uploaded file in exactly the format in which it is stored on the client, in a format that is easy to manipulate (string versus the awkward, binary encoded, procedure format used by the old functions). This gives a Janus Web Server application complete control over how the file is manipulated.
• If the uploaded file is XML, it is in a very convenient format to be passed to the Janus XML API.
• It facilitates the use of the StringList API rather than the old-fashioned $list API.

$web_file_content can be used to retrieve file content as text (translation from ASCII to EBCDIC), or binary (no translation). Binary is the default.

In the following example, the file associated with the form field MYXML is loaded into a longstring and then loaded into an XmlDoc object:

%xml        is longstring
%doc        is object xmlDoc
  ...
%xml = $web_file_content('MYXML')
%doc = new
%doc:loadXml(%xml)

Note: $web_file_content, as well as its close kin $web_input_content and $web_output_content, are ideal for use with the new StringList methods ParseLines and BinaryProcedureEncode.

SirFact

The following sections present an overview of the changes made to SirFact to support the new object-oriented facilities provided by the Janus SOAP User Language Interface. For more detailed information refer to the SirFact Reference Manual.

Displaying structures and objects in FACT

To the existing support for displaying Janus SOAP XML system class objects, Version 6.7 adds support for displaying class members from any system or user-class object.

Note:Some existing FACT syntax is changed by this enhancement.

The format for displaying the contents of a structure variable or of a Janus SOAP system or user class member (variable or method) is as follows:

D %object:member[(parms)]

This format is very nearly the same as the format used in a User Language program to access the objects. Some examples follow:

D %MG:MILEAGE

Displays the value of a (user class) public or private variable: the content of class variable MILEAGE, when %MG is a user class object. Or, it displays the value of variable MILEAGE in structure %MG.

Note: If MILEAGE were a shared variable in class CAR, it could also be displayed by the following command:

D %(CAR):MILEAGE

This use of the class name in parentheses instead of an object variable is valid for system class as well as user class shared variables, but it is not valid for structure variables.

D %RS:COUNT

Displays the value of a system class member: the return from the Count method, when %RS is a RecordSet object variable, for example.

D %SL:ITEM(5)

Displays the value of a system class member: the return from the Item method applied to the fifth item, when %SL is a StringList object variable, for example.

D %NAMES('Bush'):FIRSTNAME

Displays the value of a (user class) NamedArrayList collection method: the content of the return from the FIRSTNAME method, when %NAMES('Bush') is a NamedArrayList collection item.

D %NAMES('Bush'):LIST:COUNT

Displays the value of strung-together class members: the content of the return from the COUNT method, when %NAMES('Bush') is a NamedArrayList collection item of a user class, and LIST is a variable that is a StringList object.

D %DOC

Displays the value of an object variable: the content of %DOC, when %DOC is an instance of a system XmlDoc object.

The information displayed always includes whether or not the %variable is Null. If the object is not Null, the output from the Print method applied to the object is automatically included (for some classes, such as the StringList class or the XmlDoc class). For an XmlNodeList object variable, for example, which has no Print method in its class, the FACT display simply includes whether or not the variable is Null.

As an example, if %L is a StringList object, a d %l command might produce:

%L              = Not null
%L:PRINT        = 'This is a test 1'
                = 'This is a test 2'
                = 'This is a test 3'

This example also demonstrates that the SirFact display

• Uppercases non-quoted command input before processing (this is adjustable if you are using the SirFact$functions to look at dumps).
• Quotes the output values but not informational or error messages.
• Uses the “terminal output” form (adding equal signs and quotation marks) for the Print method result and not its normal format.

  This Print output is truncated at 500 lines, a limit that is adjustable if you explicitly specify the Print method or if you are using the SirFact $functions to look at dumps.

Note: Some methods that produce terminal output (such as most Print methods or, for example, the Janus SOAP XML Serial method) can be invoked explicitly in the DISPLAY command. For example, if %xmlPier is an XmlDoc object, the following commands will provide the same information:

D %XMLPIER
D %XMLPIER:PRINT

Advantages of invoking a Print method explicitly include:

• You can specify Print method parameters:

  D %XMLPIER:PRINT('/outer/inner')
  

• The output is not subject to the 500-line (default) limit of an “implied” Print.

Although object contents can be accessed from SirFact very much the same as they are accessed in User Language, the following restrictions apply:

• The special range, count, and wildcard syntaxes supported for some other display types are not supported for objects. For example, to request the display of the first three items in StringList %SL, you cannot use D %SL(1-3). You can get the result you want, however, by using StringList Print method parameters, as in:

  D %SL:PRINT(,,1,3)
  

• Not all system methods may be invoked in a DISPLAY command. In general, methods that update an object or that create a new object instance are not allowed. For example, if %SL is a StringList object, the following is not allowed:

  D %SL:ADD('A new item')
  

New SirFact $function: $FACT_OPTION

The $FACT_OPTION function is used to set or get the values of options that affect the retrieval and display of $FACT_DATA output.

$FACT_OPTION accepts two arguments and returns a numeric code or a string.

• The first parameter, which is required, is the name of the option that is being updated or retrieved. Current options are:

  CASE

  Controls whether $FACT_DATA internally uppercases all non-quoted characters in its arguments before processing. Such auto-uppercasing provides case-insensitivity and mimics the way mixed-case User Language is supported. Prior to Sirius Mods Version 6.7, $FACT_DATA respected the case of its arguments; that is, it performed no automatic uppercasing.

  Valid CASE values are LEAVE (do not uppercase) and TOUPPER; TOUPPER is the default. LEAVE is useful for accommodating dumps created from code compiled with case-sensitive User Language, if case-sensitivity is necessary. Case-sensitive User Language is enabled by starting a User Language program with an all-uppercase Begin statement or by specifying the Sirius compiler directive Sirius Case Leave.

  Note: Prior to Sirius Mods Version 6.7, the FACT subsystem uppercased all data passed to $FACT_DATA (which processes FACT system DISPLAY commands). However, this meant that mixed-case method arguments were also uppercased before $FACT_DATA processing (for example, d %myXmlDoc

  rint('/outer/inner'), became D %MYXMLDOC:PRINT('/OUTER/INNER')). In Version 6.7, this FACT subsystem uppercasing is replaced by the $FACT_DATA uppercasing (which correctly processes the example command as D %MYXMLDOC:PRINT('/outer/inner')).

  The option to change the default case handling is not available to FACT subsystem users.

  IMPLIM

  Sets the limit for the number of lines that $FACT_DATA can output for the implied-Print of an object variable's content. An implied Print is an automatic invocation of the Print method for the display of the content of an object variable for those object classes for which such printing is enabled.

  Valid IMPLIM values are numbers between 1 and 99999999. The default is 500.

• The second $FACT_OPTION parameter is an optional new value for the option you specify as the first argument. If you specify a value for this parameter that changes the current setting of the first parameter, the $FACT_OPTION return depends on whether you are changing CASE or IMPLIM:
  • If CASE is changed successfully, the return code is 0.
  • If IMPLIM is changed, the return is the previous value of IMPLIM.

Assert Statement Enhancements

The Assert statement has been enhanced in two ways.

1. A %variable in the Info clause is now interpreted to mean the contents of the indicated variable. Before this release, an unquoted %variable name was interpreted as a literal, that is something like the following:

   assert %x = 22, info %x
   

   would simply display

   MSIR.0494: Assert info: %X
   

   Under this release, the Assert info: above would be followed by the value of %x.

   Note: If %x is not a valid %variable name, the above would produce a compilation error, so this new feature is a backward incompatibility.

2. A Continue keyword on an Assert statement indicates that an assertion failure should produce a message and possibly, a SirFact dump, but it should not cause the request to be cancelled. That is, the request should continue after the Assert statement did whatever it had to do.

   The following statement illustrates the use of the Continue keyword:

   assert %income gt 10000, continue
   

Sirius Functions

User buffer functions

Model 204 V6R1.0 introduces support for Large Object data, which can be passed via the Universal Buffer and/or the MQ/204 Interface. Sirius Mods 6.7 provides support for Sirius longstring $functions you can use to work with Large Object (LOB) data.

For Versions of Model 204 prior to 6.1, the new $functions apply only to the MQ user buffer, and they require the MQ/204 feature. For Model 204 Version 6.1 and after, the user buffer may also be a Universal Buffer for LOB data. The Universal Buffer is a one-per-user, temporary storage area that, like the MQ buffer, automatically expands to accommodate its data contents. Unlike prior Versions, the MQ buffer in Model 204 6.1 also becomes a one-per-user buffer.

The following function returns to a longstring the contents of the current user buffer (Universal Buffer or MQ/204 user buffer):

%lstr = $lstr_get_userBuffer

Any errors during the transfer of the buffer contents result in request cancellation.

The following function sets the current user buffer to the value of the longstring argument:

%len = $lstr_set_userBuffer(longstring)

%len is the resulting length of the buffer data in bytes, or it is -1 to indicate an error.

If the buffer has to be expanded to accommodate the longstring, its length is increased in increments of 4096 bytes (one page). Any errors during the transfer of the longstring result in request cancellation.

The following function adds the value of its longstring argument to the contents of the current user buffer. Data insertions into or deletions from the buffer are not allowed in Model 204 6.1.

%len = $lstr_add_userBuffer(longstring)

The return value, resizing, and error handling are the same as $lstr_get_userBuffer.

$SIRJGET modification

Previously, $SIRJGET retrievals stripped all blanks at the start of an audited line. They are no longer stripped. Also, XX lines are combined, so in particular, long user audit entries that had been split into a US line and one or more XX lines are now displayed just as a US line (with SirScan style continuations: no timestamp/etc./audit type prefix).

Note: This change will be reflected in the display of audit trail entries by SirScan.

$GZIP and $GUNZIP functions

The $GZIP and $GUNZIP functions allow compression and decompression of longstrings:

• $GZIP returns a compressed longstring in the format defined by RFC1952.
• $GUNZIP decompresses a string compressed by $GZIP or any other RFC1952 compatible compressor.

$GZIP and $GUNZIP can be used with the SMTP helper to attach compressed files to e-mail documents.

SirLib

New $function: $PROC_TOUCH

$PROC_TOUCH lets you change the date/time stamp of a procedure as well as the account ID of the last updator.

SirMon

A number of statistics were added or modified for Version 6.7. Most of the new statistics are for monitoring the Large Objects and Table E added in Model 204 Version 6.1. The following functions were affected:

• $FISTAT and $FISTATL
• $USSTAT and $USSTATL
• $SYSTAT

SirScan

New StringList class method: AppendJournalData

The StringList class now has an AppendJournalData method, which is the object-oriented equivalent of $SirJGet. The AppendJournalData method has four NameAllowed parameters that exactly correspond to the second through fifth $SirJGet parameters. Their names, respectively, are StartTime, EndTime, Threads, and Options.

SirSafe

Changes in Version 6.7 include:

• The information displayed by AUTHCTL VIEW has been enhanced to better support the monitoring and management of shared DASD enqueueing within Model 204.
• A system manager may now start and stop any application subsystem without requiring “subsystem manager” authority for the subsystem. This enables users to eliminate SCLASSes for many subsystems, which typically improves performance.
• The SirSafe Reference Manual has been thoroughly rejuvenated.

Backwards Incompatibilities

In general, backward incompatibility means that an operation which was previously performed without any indication of error, now operates, given the same inputs and conditions, in a different manner. We may not list as backwards incompatibilities those cases in which the previous behaviour, although not indicating an error, was “clearly and obviously” incorrect, and which are introduced as normal bug fixes (whether or not they had been fixed with previous maintenance). For more information on these backwards incompatibilities, please refer to the Sirius Mods Release Notes V6.7.

Janus SOAP XML processing

The following backwards compatibility issues have been introduced in the Janus SOAP Xml* methods.

Prohibit childNumber arg when inserting Text node

In version 6.7 of Janus SOAP, the $Xml_InsText function does not allow a “child number” argument. Also, the $Xml_Cop function does not allow a child number argument other than -1, if the source is a Text node.

Maximum NCName length 100 characters

The maximum length of a prefix or localName of an XML document is now 100 characters. Previously, it was 650 characters.

WspNewline option for deserialization

In version 6.7 of Janus SOAP, the default option for the deserialization methods has changed: it is now WspNewline. Also, the option that strips all leading and trailing whitespace in a Text node, and which converts every sequence of whitespace in a Text node to a single space, is now called WspToken. It formerly was called WspNorm (which can no longer be specified), and it was the default.

Character references for serializing whitespace

In version 6.7 of Janus SOAP, whitespace serialization has changed. Formerly, the one-byte value of the whitespace character itself was used (for example, hexadecimal “0D” was used to serialize a carriage return). The new whitespace serialization approach is in accordance with the XML standard.

LoadFromStringlist newlines

In version 6.7 of Janus SOAP, a newline character is added after Stringlist items in the LoadFromStringlist method.

Invalid EBCDIC characters, X'B1' square bracket

In version 6.6 of Janus SOAP, various invalid EBCDIC characters were accepted in an XML document, either in the deserialization methods or in the various Add/Insert methods. These are no longer accepted. The hexadecimal value of these EBCDIC characters are:

06 08-0A 14-15 1A-1B 20-24 28-2C 30-31 33 36 38-3B 3E
43-49 51-59 62-69 70-78 80
8A 8C-90 9A 9C-A0 AA-AC AE-B0 B2-B9 BC BE-BF
CA-CF DA-DF E1 EA-EF FA-FF

Also, EBCDIC X'B1', one of the representations of square bracket, was correctly treated as a square bracket (for example, in a CDATA section), but when translated to ASCII for serialization, it was translated to the ASCII colon (:) character. X'B1' now translates to the ASCII left square bracket.

Serialized Attribute's extraneous leading blank

In version 6.6 of Janus SOAP, if the result of the Serial method is just an Attribute node, it started with a blank character. This bug is fixed in version 6.7, but not by a maintenance zap to version 6.6.

Janus SOAP ULI

Equal sign in method arguments

In version 6.6, an equal sign (=) as the second token in a method invocation would be treated as a comparison operator, so that the following:

%list  is object stringList
  ...
%list:add('a' = 'b')

would add a “0” to the StringList, since 'a' is not equal to 'b'. Under Version 6.7, the argument above would produce a compilation error, since the Janus SOAP ULI expects a parameter name before the equal sign in this context. This would be true whether what precedes the equal sign is a string literal, a variable name, or a field name.

Should the above construct be used in any method invocations, it can be corrected by using the character comparison operator (eq) in place of the symbolic one:

%list  is object stringList
  ...
%list:add('a' eq 'b')

Janus Sockets

HTTP Helper connection errors are non-counting

Prior to this change, the HTTP Helper treated certain run time connection-attempt errors as non-request-cancelling, Model 204 counting (ER) errors, and it displayed them on the terminal. The errors in question were from Get and Post method connection failures that produced the MSIR.0084, MSIR.0085, and MSIR.0667 messages, Then, even when the method's no-cancel option was used, a site's APSY error processing routines might be triggered unnecessarily, and the Model 204 session error count might become unnecessarily excessive and cause a user restart.

In Version 6.7, these errors are informational (AD), though they can still be detected and handled by the application (by checking for a Null result object, checking $status and $statusd, or both). This change was also made by maintenance zap to Janus Sockets Version 6.6.

Janus Web Server

$web_get_cookie_lstr

The original implementation of $web_get_cookie_lstr accidentally left on the third and fourth parameters from $web_get_cookie. These were offset and length parameters which the longstring function ignored, and in fact, they were not documented. However, if they were accidentally entered, they would compile successfully.

Under Version 6.7, specifying a third or fourth parameter on $web_get_cookie_lstr will produce a compilation error.

$web_put_text and $web_put_bin

$web_put_text and $web_put_bin are now longstring capable: they accept and send strings longer than 255 bytes. This is unlikely to be a backward compatibility problem, because previous attempts to pass a longstring longer than 255 bytes to these functions resulted in request cancellation.

There might be a backward compatibility issue if a request previously did a $web_put_text or $web_put_bin of the result of a With operation on two non-longstring strings. For example:

%foo    is string len 255
%bar    is string len 255
  ...
$web_put_text(%foo with %bar)

Prior to Sirius Mods Version 6.7, if the result of the expression %foo with %bar was longer than 255 bytes, the result would be truncated to 255 bytes before being passed to $web_put_text. As of Sirius Mods Version 6.7, the result will not be truncated.

SirFact

Displaying XML objects in SirFact

In version 6.7 of Sirius Mods, the FACT syntax for displaying an item in an XmlNodelist system object has changed. Formerly, to display the fifth element of a nodelist, for example, you entered:

D %nl:5

Now you have to enter:

D %nl:item(5)

Similarly, $FACT_DATA calls specifying syntax like %NL:5 no longer work.

$FACT_DATA calls with mixed-case input

Prior to Sirius Mods Version 6.7, $FACT_DATA respected the case of its arguments. That is, passed the data item %myXmlDoc

rint, $FACT_DATA would search the dump for exactly the mixed-case variable %myXmlDoc. (To succeed, the dump would have to have been created from code compiled with case-sensitive User Language.)

In Version 6.7, $FACT_DATA first uppercases the non-quoted data items it is passed, then does its processing, so it would search the dump for the variable %MYXMLDOC. Thus, in general, $FACT_DATA calls with non-quoted, mixed-case values no longer work &emdash. unless, for an appropriate case-sensitive dump, you set the CASE option to LEAVE in the new $FACT_OPTION function.

Assert Info %variable Incompatibility

Before this release, an unquoted %variable name in the Info clause of the Assert statement was interpreted as a literal, that is, something like the following:

assert %x = 22, info %x

would simply display

MSIR.0494: Assert info: %X

Under this release the Assert info: would be followed by the value of %x. Note that if %x is not a valid %variable name, the above would produce a compilation error.

Return to top of page

Sirius Mods Version 6.6

Version 6.6 of the Sirius Mods was released in August, 2004. The major enhancements are summarized below. Please refer to the Notes for Sirius Mods Version 6.6 for more detailed information.

Janus SOAP

The following sections describe changes to Janus SOAP. Please refer to the Janus SOAP Reference Manual for updated documentation.

AddNamespace restrictions somewhat relaxed

The AddNamespace subroutine now adds a namespace declaration to an element even if the element already contains attributes. Also, AddNamespace allows the addition of a namespace to an element that has children, as long as it has no Element children. The concept of so-called "implicit" declarations, described in the version 6.5 documentation, has been removed; the documentation has been changed to reflect the operation of AddSubtree (etc.) in version 6.5: all declarations are copied.

DeleteSubtree allows prefixed nodes

The DeleteSubtree method no longer prevents the deletion of nodes with prefixes or URIs in the subtree being deleted. Note that in two cases (only), DeleteSubtree should not be considered a complete “undo” operation of Add/Insert methods. The first case is when the URI argument of AddAttribute creates a namespace declaration: DeleteSubtree of the added attribute node does not delete the declaration. The second case is when the argument of AddSubtree (or InsertSubtreeBefore) references an attribute node that has a prefix not in scope at the target of the copy operation: DeleteSubtree of the added attribute node does not delete the declaration.

Exists

The new method, Exists, returns True if the XPath result is non-empty, and it returns False otherwise.

%bool = nr:Exists(XPath)

For example, the following request:

Begin
%d Object XmlDoc
%d = New
Print 'Root exist?' And %d:Exists('.'):ToString
Print 'Elem of empty doc exist?' And %d:Exists('*'):ToString
End

Prints the following:

Root exist? True
Elem of empty doc exist? False

The Exists method is the most efficient way to check for the existence of one or more nodes in a document. SelectCount has the relative disadvantage that it may continue to examine the XmlDoc tree after the first matching node is found. SelectSingleNode can also force processing of the entire document, since SelectSingleNode guarantees it will return the first node in XmlDoc order.

LoadFromStringList

The LoadFromStringList method behaves like LoadXML, but it accepts its input from a StringList object:

%pos = doc:LoadFromStringList(strLst, [options])

Where strLst is a StringList object, and options are the same as for LoadXml. The input consists of the concatenation of the StringList items; that is, there is no insertion of line end characters at the end of each item.

LoadSystemMethodInfo

The LoadSystemMethodInfo method loads an XmlDoc with information about methods in classes selected by the “pattern” argument:

Call doc:LoadSystemMethodInfo(pattern)

Where pattern is a string whose case is ignored and which can have any of the following forms:

methodPattern

This selects, from any system class, all methods that match the specified pattern.

classPattern':'methodPattern.

This selects, from any system class matching “classPattern”, all methods that match “methodPattern”.

'System:'classPattern':'methodPattern.

This is the same as classPattern':'methodPattern.

Note that the “New” method will only be displayed if either is true:

• The “methodPattern” is the string “New”.
• The “New” method has any arguments.

Print compaction options

The following mutually exclusive Print method options are provided for more compact formats:

Compact

An element's entire start tag is printed on a single line, which includes attributes and namespace declarations. If it has no children or has a single Text child, and does not have attributes nor namespace declarations, then the Text child is serialized on the same line as the start and end tags. Compact is the new default for the Print method, which is documented as a compatibility issue.

Expanded

A new line is started for each attribute, namespace declaration, and child. Expanded is the format previously used.

AttributeCompact

Attributes and namespace declarations are printed on the same line as the start tag.

ElementCompact

An entire element is printed on one line, if it has no attributes nor namespace declarations and has no children other than possibly a Text child.

BothCompact

Combines the effect of AttributeCompact and ElementCompact, producing the most compact formatting. It displays on one line an element that has no children or that has a single Text child.

Note that these options make the Print method a little more like the format of the non-Print serialization methods, because the latter do not introduce any line breaks (by default). The non-Print methods also have options to make them a little more like the Print method with the BothCompact option (see Serialization (non-Print) newline options).

Serialization (non-Print) newline options

A set of options is available for the following methods (in these classes):

• Serial (XmlDoc and XmlNode)
• Xml (XmlDoc)
• WebSend (XmlDoc)
• AddXml (HttpRequest)

The options are to provide a serialized stream that is easier to read (for example, with WebSend, using a browser's View/Source to look at XHTML produced with Janus SOAP). These options will insert a “newline” sequence after serializing the following:

• an element start-tag, if it has any non-text node children
• an empty element tag or element end-tag
• a PI
• a comment
• a text node, if it has any siblings

This is analogous to the new BothCompact option of the Print method. In addition, you can specify an indentation value for each level of the sub-tree.

The options available to any of these methods are:

CR

Insert a carriage-return character as the newline sequence in the above cases.

LF

Insert a newline character as the newline sequence in the above cases.

CRLF

Insert a carriage-return character followed by a newline character as the newline sequence in the above cases.

In addition, a Janus Web Server connection or an HTTPRequest object has the ability to define the newline sequence for the connection or object, respectively. So, the WebSend and AddXml methods also allow the following option:

Newline

Insert the newline sequence defined for the connection or object as the newline sequence in the above cases.

All the above options are mutually exclusive. The other option available for these methods is:

Indent <n>

Where n is the indentation for each lower level in the serialized subtree. This option can be specified in conjunction with CR, LF, CRLF, or Newline. It can also be specified without any of these for WebSend and AddXml, and in that case, it implies the Newline option.

Value is settable property

The Value property in classes XmlDoc and XmlNode is now settable. It's not allowed if the head of the argument XPath result is either the Root or is an Element with more than one text child. For example:

%worker:Value('billingRate') = %worker:Value('billingRate') - 10

User class definition changes

New and Discard may be disallowed outside the class

The Public block of a class definition may now contain a Disallow qualifier for the New and Discard system methods. This option prevents users of a class from invoking either the New function or the Discard subroutine outside of the class definition. Disallow is ignored for methods inside the class: If Disallow is specified in the class definition for New or Discard, you may still issue a New or Discard within the class wherever you want.

Private constructors are allowed

You can now define constructor methods in the Private block of a class definition. Such constructors may only be invoked from inside the class. If you want to define a private constructor named New, you must make sure to specify Disallow New in the Public block of the class definition. No other private constructors require an additional Disallow New in the Public block.

Optional parameters allowed on methods

Optional parameters are now allowed on method definitions. A definition may specify a default value to be passed when no value is provided for an invocation. Similarly, a method can test to see if a particular parameter was specified by its invoker.

For more information about these changes see the Janus SOAP Reference Manual.

HTML/Text statement To clause

The HTML and Text statement now accept a To clause that can be followed by a stringList that is to receive the output from the HTML or text statement. In the following, the first few lines of Hamlet's most famous soliloquy are added to stringList %quoteList:

%quoteList   is object stringList
%quoteList = new
text to %quoteList
    To be, or not to be: that is the question:
    Whether 'tis nobler in the mind to suffer
    The slings and arrows of outrageous fortune,
    Or to take arms against a sea of troubles,
    And by opposing end them?
end text

For more information about the HTML/text statement To clause, see the Janus SOAP Reference Manual.

SIRCOMP user parameter

This new system parameter is a bitmask-type parameter whose X'01' bit means that string literals in HTML/Text statements are to be stored in CCATEMP rather than STBL. This is a compilation time parameter, and it can save large amounts of STBL space used to hold string literals (at a potential CPU cost in accessing the literals in CCATEMP).

System and subsystem classes

Shared methods in the System and Subsystem classes are provided to allow manipulation of system-wide and subsystem-wide entities. The following is a very brief synopsis of the new methods:

• %(system):SetGlobal(name, value).
• %(subsystem):SetGlobal(name, value).

• %(system):DeleteGlobal(name).
• %(subsystem):DeleteGlobal(name).

• %success = %(system):SetString(name, value, testvalue).
• %success = %(subsystem):SetString(name, value, testValue).

• %(system):DeleteString(name).
• %(subsystem):DeleteString(name).

• %(system):String(name).
• %(subsystem):String(name).

• %stringList = %(system):ListOfGlobals(gname).
• %stringList = %(subsystem):ListOfGlobals(subsysName, gname).

• %stringList = %(system):ListOfStrings(sname).
• %stringList = %(subsystem):ListOfStrings(subsysName, sname).

For more information about these methods, see the Janus SOAP Reference Manual.

Session objects

In addition to global objects, session objects are now available. Session objects are very much like global objects, except instead of being associated with a login, they are associated with a logical session that can span multiple logins or be passed between logged-in threads. These sessions are the same sessions managed with the $session functions documented in the Sirius Functions Reference Manual.

Session objects, like global objects, can be statically bound to %variables:

%ruby   is  object jewel session

or set and retrieved dynamically using Object class methods:

%(object):getSession(%bauble, 'DIAMOND')
%(object):setSession(%bauble, 'EMERALD')

For more information on these methods see the Janus SOAP Reference Manual.

Garbage collection

The Janus SOAP ULI now supports “garbage collection” — the cleaning up of orphaned object cycles. Garbage collection can be initiated with the Object class GarbageCollect method:

%(object):garbageCollect

Garbage collection is too complex a topic to cover here, so before using this method, see the Janus SOAP Reference Manual for more details about garbage collection.

Auto keyword on object declarations

System objects can now be declared with the Auto keyword followed by the word New, or if the object is an enumeration, followed by an enumeration value. This indicates that the first reference to the object variable, if it's not an assignment to the variable, will cause an instance of the object to be created, as if it had been explicitly instantiated. For example:

%colors    is collection arrayList of string len 32 auto new

%colors:add('Magenta')

is equivalent to

%colors    is collection arrayList of string len 32

%colors = new
%colors:add('Magenta')

The Auto New clause can be used in in object declaration, even if the declaration is in a Public, Private, Public Shared, or Private Shared block in a Class declaration. This facility is especially useful in helping to avoid having to write a constructor for an object just to instantiate collections or arrayLists inside the object. It also avoids having to worry about null values for an enumeration variable that typically has a default value:

%expertUser    is enumeration boolean auto true

RecordSet object manipulation methods

Several new methods are introduced in version 6.6 of Janus SOAP:

Creating an empty record set

To create a RecordSet object that references an empty record set, you can use the New contructor of the RecordSet object. The RecordSet object constructor has one optional parameter: a LockStrength enumeration. If no LockStrength value is specified, a default value of Share is used (as is consistent with the Record object). For example:

%rs is object recordSet in foo
%rs = new
%rs = new( none )
%rs = new( exclusive )
%rs = new( share )

Adding records to a record set

The AddRecordSet and AddRecord RecordSet object methods are now available. AddRecordSet adds a RecordSet object's records to the records in an existing RecordSet object:

%target:AddRecordSet( recordSetObject )

AddRecord adds the record in a Record object to the records in an existing RecordSet object:

%target:AddRecord( recordObject )

For these methods, the lock strength of the records being added to the set must be greater than or equal to the lock strength of the set being added to. Consequently, adding records to a record set will not cause the RecordSet object to try to acquire a record lock that it does not have. Therefore, these methods never cause a record locking conflict. Within a recordset, all records are always locked at the same strength (the lock strength with which the object was created).

In summary, these locking rules are in effect:

• To a set locked at exclusive level, you may add only records that are locked at exclusive level.
• To a set locked at share level, you may add records locked at exclusive level or share level.
• To an unlocked set, you may add records locked at any strength (exclusive, share, none).

Any violation of these rules results in request cancellation. If the recordSetObject parameter of AddRecordSet, or the record object parameter of AddRecord, is null, the request is cancelled. These parameters must have the same file context as the object for which the method is being called, or a compilation failure will result.

These two methods effectively perform an “OR” operations, just like PLACE RECORD/RECORDS.

Removing records from a RecordSet

The following RecordSet object methods mey be used to remove records from a RecordSet:

*  remove a set of records
%target:RemoveRecordSet( recordSetObject )

*  remove a single record
%target:RemoveRecord( recordObject )

If the recordSetObject parameter of RemoveRecordSet is null, or if the record object parameter of RemoveRecord is null, the request is cancelled. These parameters must have the same file context as the object for which the method is being called, or a compilation failure results. Since the methods simply remove records from a set, the records being removed can be of any lock strength.

ANDing RecordSets

The AndRecordSet method may be used to AND two recordSet objects:

%target:AndRecordSet( recordSetObject )

If the recordSetObject parameter is null, the request is cancelled. The parameter must have the same file context as the object for which the method is being called, or a compilation failure results. Since ANDing can only remove records from a set, there are no restrictions on lock strength.

Making a copy of a record set

The Copy function of the RecordSet object makes a copy of a RecordSet:

%clone = %original:Copy

This method takes an optional parameter: a LockStrength enumeration. As with the New constructor, the default lock strength is Share if the LockStrength parameter is unspecified. You can only create a copy of lock strength less than or equal to the original, so Copy cannot produce a record locking conflict.

SirFact

Compact Xml display

When displaying the contents of an XmlDoc, the Compact form of the XmlDoc Print method is used.

Janus Sockets

The following sections describe changes to Janus Sockets. Please refer to the Janus Sockets Reference Manual for updated documentation.

Handling server redirection (HTTP Helper)

An HTTP server may return an indication that a page has moved and that the client process should fetch it from a new location. A server indicates this case by returning a response code in the 300s accompanied by a response header named “location” that indicates the new location of the page or resource. The version 6.5 HTTP Helper does nothing special with redirects: the 300+ response code is returned to the application as if it were any other response.

In Version 6.6 of the Sirius Mods, your HTTP Helper application may use the new MaxRedirects property of the HTTP Request object to request automatic handling of redirects that a Get or Post method call receives from the server:

%HTTPRequest:MaxRedirects

Since redirects may be chained (that is, the location to which a redirect leads can also return a redirect), MaxRedirects specifies the maximum number of times a redirect is followed when it is returned from a web server. Its default is zero (do not automatically handle redirects). If non-zero, it indicates the maximum number of times a redirect is followed on one Get or Post call. If the maximum number of redirections have been followed, and the last response is still a redirection response code, the last redirection response code is returned to the HTTP Helper application.

MaxRedirects may be set to an integer from 0 through 100. An attempt to set it to anything else results in request cancellation. When MaxRedirects is set to a value greater than zero, the following HTTP redirection response codes are automatically handled:

301	Moved Permanently
302	Found
303	See Other
307	Temporary Redirect

In order to facilitate working with redirects, the new URL method of the HTTPResponse object returns the actual URL from which a response was obtained. In the case of redirects, this will not be the URL requested on the HTTPRequest object.

File-based form uploads (HTTP Helper)

The HTTP Helper now supports Multipart Form encoding to provide browser-like handling of file uploads. A version 6.6 HTTPRequest object can send file data to a web site from either a longstring or a Stringlist. The Post of file data using this feature emulates an HTML form that uses enctype="multipart/form-data" and a type="file" input field. To enable this feature:

1. Set to True the new boolean property, MultiPartFormEncoding, of the HTTPRequest object.
2. Add form data with AddField.
3. Use the Post function to send the request.

MultiPartFormEncoding must be set to True before any AddField statements are issued, or the request is cancelled.

AddField method changes (HTTP Helper)

In version 6.6, the HTTPRequest method AddField is enhanced to support file uploads. The method has two new optional parameters, and an existing parameter has an additional type option, producing the following syntax for AddField:

%req:addField(fieldname, fieldvalue [,filename] [,xlatflag])

Where:

• fieldname, a string that identifies the form field name, is unchanged from version 6.5.
• fieldvalue can now be either a StringList or a LongString (previously, only longstrings were allowed). If it is a StringList, a line-end sequence is appended to each StringList item as it is added to the Post data. The new LineEnd property sets which of three line-end sequence options is appended.
• filename, a string, is a new optional parameter that identifies the file to be uploaded. The default is no file specification, that is, a non-file data Post.
• xlatflag is a new optional parameter that controls whether the fieldvalue content gets EBCDIC-to-ASCII translation. If xlatflag is not specified, the default is True (use EBCDIC-to-ASCII translation). If set to False, no translation occurs.

ContentToStringList method (HTTP Helper)

This HTTPResponse object method places into a StringList object the content returned from an HTTPRequest Get or Post method. ContentToStringList does the following:

1. Instantiates a StringList object.
2. Breaks the HTTPRequest returned content into lines by scanning for line-ends.
3. Translates each line from ASCII to EBCDIC, and places it in its own StringList element in the StringList it created.
4. Returns the StringList.

No single content line may exceed 6124 bytes in length (excluding the line end), or the request is cancelled. The scanned-for line-ends are the three typical characters (CRLF, CR, LF). The ContentToStringList syntax is:

%lines = %httpresp:ContentToStringList

where %lines is a StringList object.

This method is useful when the content returned from the HTTP server is a series of ASCII text lines separated by line-end characters (for example, an HTML document). Accessing such content with the HTTPResponse Content method would leave all the lines in one longstring, which the application would have to separate into lines using string-handling User Language code.

ContentToStringList is also useful for getting readable output for debugging purposes. For example:

%myGradeBookResponse:contentToStringList:print

The statement above produces much more readable output than this:

print %myGradeBookResponse:content

LineEnd property (HTTP Helper)

The new LineEnd property of the HTTPRequest object lets you select which of three line-end sequences to use when adding a file to form Post data by passing a StringList object to the AddField method of the HTTP request object.

By default, each item in the StringList copied into the Post data has a line-end sequence appended to it. The line-end sequence CRLF (carriage-return/line-feed) is the default (hex value X'0D0A'). However, a client application may instead use carriage-return only (X'0D'), or line-feed (X'0A').

To specify an alternative line-end sequence for AddField, you set the LineEnd property of the HTTPRequest object. The LineEnd property sets and returns an Enumeration (the LineEnd enumeration), which has one of the following values:

CRLF	Use carriage-return/line-feed (the default)
CR	Use only carriage-return
LF	Use only line-feed

For example:

%HTTPRequest:LineEnd = CR
%HTTPRequest:AddField( ...
%HTTPRequest:LineEnd = CRLF

The LineEnd property must be set before the AddField call. The LineEnd setting remains in effect until the property is reset with another assignment.

AutoSendXMLContent property (HTTP Helper)

This property of the HTTPRequest object allows or suppresses the automatic generation of an HTTP content-type header for a Post produced by the HTTPRequest AddXml method. As of Sirius Mods version 6.6, if you do not explicitly set a content-type HTTP request header via AddHeader, AddXml generates a content type header of “text/xml” upon a Post. To suppress this automatic generation, you can set the AutoSendXMLContentType property (HTTPRequest class) to False. This property sets and returns a Boolean enumeration that indicates whether AddXml automatic header generation is on or off.

Automatic request header for Post calls (HTTP Helper)

As of version 6.6, the HTTP Helper automatically sends the following request header on Post calls if no explicit content-type header is set, if form fields are set, and if multi-part form encoding is not enabled:

content-type: application/x-www-form-urlencoded

In version 6.5, to set this header you must do so explicitly using the AddHeader method of the HTTPRequest object.

Additional error checking (HTTP Helper)

These Post-oriented actions are incompatible with an HTTP Get, and they result in request cancellation if detected by Get function error checking:

• An AddXML call added Post data to the request.
• An AddLongString call added Post data to the request.
• The MultiPartFormEncoding property set to True enabled multipart form encoding.

Close is the only option for "connection" headers (HTTP Helper)

In version 6.5, the HTTPRequest object of the HTTP Helper automatically generates the HTTP Request header "Connection: close" under HTTP 1.1. In version 6.6, if you try to set a “connection” header using the AddHeader method of the HTTPRequest object, any value except close will result in request cancellation. Note: If you explictly set “connection” to close, the automatic generation of "Connection: close" is suppressed to ensure that an extra connection header is not sent.

Socket port name defaults to MASTER port

The socket port name parameter on $SOCK_CONN, on the Socket object New constructor, and on the HTTP Helper Get and Post methods now defaults to the MASTER port, if your CLSOCK port is defined with the MASTER keyword. In these circumstances, you may omit the explicit specification of a socket name on these calls.

CLSOCK port enhancements

• MASTER parameter allowed

  The MASTER parameter of the JANUS DEFINE command is now allowed for CLSOCK ports. A port defined as MASTER can be accessed on a Janus Sockets connection request without specifying its port name. The socket port name parameter on $SOCK_CONN, on the Socket object New constructor, and on the HTTP Helper Get and Post methods now defaults to the MASTER port, if any.

• Default for REMOTE parameter of JANUS DEFINE

  REMOTE * * is now the default for CLSOCK ports. It is expected that this will be more convenient and desirable than the former requirement to explicitly designate a specific host or IP address. Explicit specification remains an option. Note: If the REMOTE default setting is in effect for a CLSOCK port, REMOTE * * is not included in JANUS DISPLAY output.

Janus Web Server

The following sections describe changes to Janus Web Server. Please refer to the Janus Web Server Reference Manual for updated documentation.

HTTPVERSION parameter for JANUS DEFINE

The new JANUS DEFINE parameter HTTPVERSION allows changing of the HTTP version returned to the browser by Janus Web Server. This parameter should be changed with caution.

WEBOPT system parameter

WEBOPT is a new bitmask-type parameter. The X'01' bit indicates that RACF authentication functions performed on behalf of Janus Web threads should be done in a special RACF subtask. This can significantly improve performance when RACF is being used to validate logins for Janus Web Server in high-load environments.

All or Multiple Products

The following sections describe enhancements available to all customers that have any Sirius “API” product, such as Janus Web Server, Janus SOAP, Janus Sockets, or the Fast/Unload User Language Interface. Note that in addition to changes to the features and functionality of the Sirius Mods, the documentation is constantly being improved.

ASSERT statement availability

The ASSERT statement is now available to all customers that have any Sirius “API” product. For more information please refer to the Janus SOAP Reference Manual.

$list item length restriction

For most purposes, $list and stringList items can now be up to 2**31-1 bytes long.

Mixed-case User Language availability

Mixed-case User Language is now available to all customers that have any Sirius “API” product. For more information please refer to the Janus SOAP Reference Manual.

SIRMETH rules

The SIRMETH command allows system managers to delegate authority to control system and subsystem globals, eliminating the requirement to construct “wrapper” subsystems. The following authority can be controlled:

• Set system globals and strings.
• Set subsystem globals and strings.
• Set a subsystem context.

The format of the SIRMETH command is

SIRMETH {ALLOW | DISALLOW}                 -
        {SYSTEMSET | SUBSYSTEMSET |        -
         SUBSYSTEMCONTEXT csubsys | ALL}   -
        [SUBSYSTEM subsys [NONPRE] ]

For more information please refer to the Janus SOAP Reference Manual.

Backwards incompatibilities

Janus SOAP

• In version 6.6 of Janus SOAP, the default option for the XmlDoc and XmlNode Print method has changed. The new default is Compact.
• As of version 6.6, all labels within a method must be unique; a duplicate label will cause a compiler error. In version 6.5 duplicate labels within a method were allowed.

Janus Sockets

• In version 6.5 of the HTTPHelper object, if no content-type header was set with the AddHeader method, an AddXml method Post sent no content-type header. In version 6.6, if you do not explicitly set a content-type HTTP request header via AddHeader, a content-type header of “text/xml” is automatically generated when you do a Post.
• You can suppress this version 6.6 automatic header generation by setting the AutoSendXMLContentType property of the HTTPRequest object (new in version 6.6) to False.
• The GetMySocketNumber has been renamed GetSocketNumber. Also, the GetSocketNumber, GetSocketObject, and ServerSocket methods in the Socket class have been changed so that a socket is either accessible by a number or an object, but not both. That is, after a GetSocketNumber call, the method object socket is no longer accessible as an object, and after a GetSocketObject or ServerSocket call, the socket can no longer be accessed by its number.
• The number of bytes used for each possible user socket (SOCKMAX) has been changed from 5 to 6.

Fixes in Sirius Mods 6.6 but not in 6.5

This section lists fixes to functionality existing in the Sirius Mods version 6.5 but which, due to the absence of customer problems, have not, as of the date of the release, been fixed in that version.

Janus SOAP

• Previously, if an XmlDoc subtree that contained an explicit namespace declaration was deleted, an internal error was introduced into the XmlDoc, and subsequent usage could cause incorrect results. Such a declaration was necessarily unreferenced, since if it was referenced, deletion of a node with a URI would have been attempted, and the deletion operation would not have been allowed.

SirFact

• Previously, when a SIRFACT NODUMP rule was matched, a message was issued that a file was not found; the name of the file consisted of 8 hexadecimal zeroes.

Return to top of page

Sirius Mods Version 6.5

Return to top of page

Version 6.5 of the Sirius Mods was released in May, 2004 The major enhancements are summarized below. Please refer to the Sirius Mods Release Notes Version 6.5 for more detailed information.

Janus SOAP

There have been significant changes in the Janus SOAP API in this release. Most of these are caused by the support for object-oriented syntax. In addition the XML API now supports namespaces as well as additional XPath axes, and as usual there have been various performance enhancements.

Object-oriented syntax

The new XML API for Janus SOAP is based on objects, which are acted upon or described by members such as functions and properties. For example, here is a fragment using version 6.4:

%D = $XML_DOC
%X = $XML_STR2DOC(%D, 'Hello, world!')
%N = $XML_NL
%X = $XML_NODE_SING(%N, %D, '/*')
PRINT $XML_VAL(%N)

This could be written using version 6.5 as:

%d Is Object XmlDoc
%d = %d:New
Call %d:LoadXml('Hello, world!')
%n Is Object XmlNode
%n = %d:SelectSingleNode('/*')
Print %n:Value

Note: in practice, this would be simplified, because the Value property supports an XPath argument (as did $XML_VAL). So, you'd likely combine the last three lines as:

Print %d:Value('/*')

The old form of the API has been deprecated, although it is still documented in the Janus SOAP Reference Manual (6.4). From now on all examples and documentation will focus exclusively on the new syntax. The conceptual foundation for the Janus SOAP object-oriented approach is described in the Janus SOAP Reference Manual.

Additional XPath axes

This version now supports all axes in XPath expressions except the namespace and preceding axes. The following are axes which were not previously supported:

• following-sibling
• preceding-sibling
• descendant-or-self
• descendant
• ancestor-or-self
• ancestor
• following

Namespace support

Janus SOAP now fully supports namespaces. The documentation for version 6.4 included some explanations of how namespace support was expected to work, in some cases the actual support is different. For example, the AddAttribute function is only used to insert Attribute nodes; the version 6.4 documentation assumed that it would also be used to insert Namespace nodes, which are instead inserted using AddNamespace. Other non-obvious differences include:

Inaccessability of namespace declarations

In accordance with the XPath 2 specification, namespace declarations are not directly accessible with Janus SOAP. The namespace axis is not supported and there is no need to identify a node type (formerly called Namespace) for namespace declarations. You can obtain the information provided by namespace declarations by various Xml* class members, for example, the URI property of an XmlNode.

Implicit namespace declarations

When an Element node or Attribute node is inserted in an XmlDoc, specifying the URI argument indicates the namespace URI of the node (including “no namespace“, when the null string is given as the URI argument, which is different from omitting the argument). If necessary, a namespace declaration is implicitly inserted in the newly inserted Element node (or, when inserting an Attribute, in its Element parent). This is one of the two styles of namespace control which you can use when inserting nodes (the other is to omit the URI argument). Whichever style you use, or if you create an XmlDoc with one of the deserialization functions, the URI which is set for an Element or Attribute node remains the URI of that node. For example, if you copy or move the node, that URI remains as the URI, and if an implicit namespace declaration is needed as part of the copy or move operation, one is inserted.

Node order and XPath performance

Performance of certain XPath queries can suffer from issues of document order. In general, use of only “simple” axes, e.g. child, attribute, self, and following-sibling (or parent only as the first axis) presents no issues for XPath processing performance. Other axes, in certain combinations can increase processing time and forgo the usual efficiency offered by single node selection (e.g., the SelectSingleNode member, or Value or various other members which accept an XPath argument). This is because some cases require searching the entire document, even after some node is selected, in case that node is not the “first” node in the document matching the XPath expression.

As discussed in the Janus SOAP Reference Manual, the items in an XmlNodelist are in document order, which is simply the order in which the node (or its start-tag, in the case of an Element node) occurs in the serialization of the XmlDoc. Many Janus SOAP members operate on a single node, which may be the first node satisfying an XPath expression. For example, the SelectSingleNode member explicitly returns one node matching its XPath expression argument, and there are a number of members (e.g., Value, DeleteSubtree, QName, etc.) which operate on a single node.

The “single node“ XPath selection by Janus SOAP will return the first node in document order, but in some cases this is not the same as the order of its internal selection algorithm. In those cases, Janus SOAP will examine the entire document to find the first, in document order, node selected by the XPath expression.

More non-syntactic changes

Control characters disallowed

The deserialization and node insert functions now check for invalid characters in an XML document, e.g., “&#x19;” This may cause a backward incompatibility.

Default Namespace On

The default value of an XmlDoc's Namespace property is 'On'. This may cause a backward incompatibility. You may find that some applications which used Namespace Ignore are now handled better (because of the increased error checking, and the improved use of prefixes with XPath) using the default Namespace property (On).

Mixed case node type

All node type names (value of the Type property) are now returned as mixed case, for example: Attribute, Comment, Element, PI, Root (note: this was formerly the DOCUMENT node), and Text.

Note: The $Xml_Type functions still returns all uppercase values, and the old name for the root node: ATTRIBUTE, COMMENT, ELEMENT, PI, DOCUMENT, and TEXT.

Mixed case property values

Various property values which are of a fixed set of strings are now mixed case. When setting these values, any case variation can be used, but if you compare the value of the property to a string whose source is hand-coded, you must compare to the string exactly as follows to achieve the expected results:

• Namespace property: On, None, Ignore.
  Note: The $Xml_Set and $Xml_Info functions still return all uppercase values (ON, NONE, IGNOR), but $Xml_Set can be passed a value in any case.
• XPathOrder property: EBCDIC, Unicode.

Any case for option arguments

Various option arguments, such as “ErrRet” for the LoadXml member and “NoXmlDecl” for the Serial member, can now be specified using any mixture of upper and lower case. In addition, the options to the deserialization members, such as “DTDIgnore” and “WspPreserve” for LoadXml, can now be specified without the underscore previously used (although the underscore is still accepted).

Boolean predicates

The and and or Boolean operators can be used in XPath predicates, for example:

Print %n:SelectSingleNode( -
   'pay[@per="day" and @due="late"]')-
   :Value

Full position() support

The XPath position() function is supported (not simply the “abbreviation” of a number in square brackets, e.g., [3]), and it may be followed in a predicate with a comparison operator (e.g., >=) and a numeric value. The numeric value used for position (both with explicit position() and the “abbreviated” form) may now be any integer, including zero and negative integers.

AddSubtree disallowed with different Namespace

It is illegal to copy a subtree from one XmlDoc to another which has a different value of the Namespace property. This may cause a backward incompatibility.

No “]]>” in serialized result

In accord with the XML Recommendation, an Element's content representation (in the serialized form, of course) cannot contain the character string “]]>”. Previously, this could occur. This bug fix may cause a backward incompatibility. .

Print of “incomplete” XmlDoc

The Print subroutine allows printing from the root node of an XmlDoc which does not contain an Element. This is useful since Print is used for debugging, and so it should not fail in such cases.

Deserialization returns error position

The deserialization functions return the position of an input character which is at or after the cause of a parsing error (when the ErrRet option is used). In version 6.4, the $function forms returned the value “1” to indicate a parse error. This may cause a backward incompatibility.

Deserialization errors provide element/attribute name

During deserialization, several types of errors refer to an element start-tag or attribute which preceded the discovery of the error, for example, a mis-matched element end-tag. The messages for these errors now include the name of the element or attribute involved in the error, thus making the error easier to find.

Performance

There have been several changes to Janus SOAP to enhance its performance. Besides overall changes, the following two deserve mention:

Hashing

All strings (names or values) are stored in an XmlDoc as part of a hash table. The hashing algorithm and its implementation have been improved to reduce path length and to reduce hash collisions. This will improve serialization, node insertion, and XPath operation.

Depth-first XPath

The approach to evaluating XPath expressions has been changed so that now it is in depth-first order of the XmlDoc tree, which usually will coincide with the stored order of XmlDoc nodes, and will also reduce the number of needless nodes searched when a “single node” member is invoked.

In addition to the above improvements, you may be able to improve the performance of your Janus SOAP applications by ensuring that the Model 204 MAXOBUF parameter is large enough; it should probably be a minimum of 6 if your XmlDocs are heavily used or contain a number of nodes and values in the thousands or more. MAXOBUF can be extremely beneficial for a large number of Model 204 applications, not just those involving Janus SOAP.

SirFact

The following are new or changed features in SirFact:

INFO.VERSIONS

You can display INFO.VERSIONS to get the Model 204 version, the Sirius Mods version, and the SirFact internal dump format version in effect when the SirFact dump was produced.

Display XmlDoc and XmlNode objects

You can use the VALUE and ATTRIBUTE classes to display an XmlDoc or XmlNode object. The VALUE class of display, which can also be used to display one or more elements of an array of XmlDoc or XmlNode objects, consists of the same output lines as the result of the Print method.

Display XmlNodelist objects

You can use the VALUE and ATTRIBUTE classes to display an XmlNodelist object. The VALUE class of display consists of the same output lines as the result of the Print method applied to the Item method; in order to specify which item of the XmlNodelist to display, use a colon followed by the item number as the suffix for the specification. The following example displays the XmlDoc subtree starting at the node which is the third item in the %nodlis XmlNodelist:

D %NODLIS:3

To request the count of items in an XmlNodelist, use a colon and “number sign” (“#”) as a suffix. The following example displays the number of items in the %nodlis XmlNodelist:

D %NODLIS:#

The VALUE class of display can also be used to display one or more elements of an array of XmlNodelist objects; for that, the colon and item number or “#” is specified after the parenthesized array subscripts.

Colon syntax for $list items

The same “:” and “:#” suffix notation can be used with. the LIST display class, as an alternative to a single item in parentheses. So, to display a single $list item:

D L.%LIS:3

To display the number of items in a $list:

D L.%LIS:#

Sirius $functions

The following are new or changed features in the Sirius Functions:

New $Lstr_Translate function

This function takes a string or longstring input and replaces characters indicated by an “input table” with corresponding characters in an “output table.”

Janus Web Server

The following features are new or changed in Janus Web Server:

SESFASTLOGIN and HIGHPRIORITY

These JANUS DEFINE parameters are valid only for Janus Web ports. They are designed, respectively, to reduce the login security overhead for Janus Web threads, and to have web threads start at the upper end of their priority range rather than the default start.

SESFASTLOGIN

Indicates that a login performed for a continued session will be a “fast” login. A fast login does no CCASTAT lookup or external authorizer (RACF, ACF2, Top Secret) lookup for the userid. Setting this parameter avoids the overhead of heavy external-authorizer login traffic for web threads, which do a login for every protected page requested. Note: this parameter has no effect unless login sessions are being maintained by SESCOOKIE or SSLSES. The WEBLOGHOLD parameter accomplishes many of the same things as SESFASTLOGIN, but it has the drawback that an sdaemon thread is tied up for each held login.

HIGHPRIORITY

Indicates that upon login, a web user's priority is set to the top of its priority range. This allows web threads to better compete with 3270 threads for CPU resources in busy onlines, since Model 204 tends to promote long-running 3270 threads to the top of their priority range.

Janus Sockets

The following features are new or changed in Janus Sockets:

FTP support

Version 6.5 combines the rules-based processing language of Janus Web Server with the APIs of Janus Sockets to make it easier to set up one or more FTP servers within a Model 204 online. These FTP servers can be accessed with the FTP client of your choice to copy procedures into and out of Model 204 procedure files. The provided application supports:

• Adding, replacing, deleting, and renaming Model 204 procedures with any FTP client.
• Viewable procedure lists (the FTP ls and dir commands).
• EBCDIC/ASCII translation in both directions.
• Binary file transfers (FTP TYPE I).
• Mapping of the standard UNIX folder structure to Model 204 procedures and procedure files, enabling navigation with the standard FTP CWD command.
• FTP User authentication based on Model 204 user ids and passwords using your security package.
• Anonymous FTP.
• Active and passive FTP.
• Support for MVS, VM, and VSE.
• Multiple FTP servers running on different port numbers in an online, not necessarily using the default port (21).
• Letting the procedure name suffix (say, .HTML) control the transfer mode of a file (text vs. binary).

Socket object support

Janus Sockets Socket object support offers a coding alternative to the $SOCK_xxxx functions for both client and server applications that spares you from having to manage or refer to socket numbers.

Essentially an object style reference to a Socket number, the Sirius Socket object is designed for Janus SOAP applications only. Socket objects and $functions may be used in the same code, and transition methods are available for converting $function applications to object-oriented applications.

HTTP Helper object support

The Janus Sockets HTTP Helper is a simple object-based API that lets you write a User Language HTTP client without knowledge of socket level programming or the format of HTTP requests and responses. You can construct HTTP requests for any HTTP server (including Janus Web server).

For SOAP applications, the HTTP Helper supports the posting of XML data and parsing an XML document in an HTTP response. HTTP Get and Post requests are supported as are proxy servers and full HTTP header access.

Fast/Unload User Language Interface

The following feature is new in the Fast/Unload User Language Interface:

$FUNLOAD and multiple output streams

The multiple output feature was introduced in Fast/Unload 4.1, but not supported for the Fast/Unload User Language Interface until Fast/Unload version 4.2 (and Sirius Mods 6.5). To use $FUNLOAD to invoke a multiple output version 4.2 Fast/Unload you specify a fourth argument that is any eight-character or less string that is not a %variable or a single asterisk (“*”).

This string is not used, but it indicates that the output data is to be sent to the data sets specified in the FUEL program. Prior to Fast/Unload 4.2 and Sirius Mods 6.5, such a character string in a $FUNLOAD fourth argument was assumed to name an output data set specified in the FUEL program.

Fast/Reload

The following feature is new in Fast/Reload:

LAI support for procedures

As of Fast/Unload version 4.2 and Sirius Mods 6.5, the UAI and LAI statements support the reorganization of procedures and procedure aliases. Procedures and aliases present in the TAPEI input data set for a Fast/Reload run are loaded as is by LAI. The UAI unload and LAI reload preserve all alias associations and date/time stamps from the procedure dictionary. The procedure file reorg offers an automatic tuning of the target file's procedure dictionary, which can significantly reduce the CPU required for compilations with very large procedure files.

If procedure or alias names clash with names in the target file, the reload stops. If you want the unloaded procedures and aliases not to be reloaded, you specify the NOPROCS option of the LAI statement.

Some environmental tuning may be required to achieve the best results when loading procedures via LAI. At the very least a larger Model 204 buffer pool will probably be required. Please refer to the Fast/Reload Reference Manual for more detailed information.

All or Multiple Products

Callable $functions

This release introduces the ability to call (using a User Language CALL statement) many of the existing Sirius $functions, relaxing the requirement that they may only be invoked as assignments to %variables. For example:

%L = $LISTNEW
$LISTADD(%L, 'Once upon a midnight dreary')
$LISTADD(%L, 'As I pondered weak and weary')
CALL $LIST_PRINT(%L)

You can CALL such $functions and still test for their return code, if necessary.

The callable $functions are indicated as such in their individual function descriptions in Sirius documentation. They are typically those that return no value other than an indicator of whether the function completed successfully or not.

Case-insensitive User Language

This release introduces the ability to compose a User Language request in case-insensitive mode. When in this mode, all elements of a User Language program excepting “literal strings” are processed after converting lowercase letters to uppercase. The non-literal string elements treated in this case-insensitive manner are: User Language keywords; variable elements such as %variables, screen/image names and items; class/structure members; labels and subroutine names; field names; $functions; and procedure names (on the Include statement). The following literal strings are not affected by case-insensitive processing: quoted strings literal contents of the Text/Html block, except those enclosed in the “evaluation” brackets.

It should be noted that case-insensitive processing only applies to program elements encountered during compilation. This applies to a multititude of string values in use in the program. For example, when setting a value for a fieldname variable or for Screen or Image indirection, the value must exactly match the name. That is, if you have a field named EMPNAME and you reference it with a fieldname variable, the value used must be all uppercase:

Begin
%x String Len 20
%x = 'EMPNAME'
FR
   Print %%x
End For
End

The case-insensitive mode of User Language processing is entered at the start of a request if the BEGIN command has any lowercase letters. In addition, the Sirius Case compiler directive can be used turn case-insensitive processing on or off. The following statement in a User Language request will turn on case-insensitive processing:

Sirius Case toUpper

The following statement in a User Language request will turn off case-insensitive processing:

Sirius Case Leave

Note that other than the Begin command, case-insensitive processing of User Language does not apply to Model 204 command processing.

Backwards incompatibilities

Janus SOAP

Version 6.5 introduces a new API that uses object-oriented methods instead of $functions. Many of the methods perform the same or nearly the same operation as, and have names that closely resemble, their $function counterparts.

Control characters disallowed

The deserialization and $XML_INSxxx functions now check for invalid characters in an XML document, e.g., “&#x19;”. This is in accordance with the XML Recommendation, but since previous versions of Janus SOAP did not check for valid characters, you may now obtain a request-cancelling error message due to an invalid character, in an application which formerly inserted the illegal character without any error message.

No subtree copying with different Namespace

It is illegal to copy a subtree from one XmlDoc to another with different values of the Namespace property. Previous versions of Janus SOAP did not enforce this restriction.

Default Namespace On

The default value of an XmlDoc's Namespace property is 'On'. In previous versions of Janus SOAP OFF was the default. Applications which were handled using Namespace Ignore may now be better handled using the default Namespace property (On).

No “]]>” in serialized result

In accord with the XML Recommendation, an Element's content representation (in the serialized form, of course) cannot contain the character string “]]>”. If an XML document contains this string, it was previously incorrectly serialized as “]]>” but now is serialized as “]]&gt;”.

Deserialization returns error position

The deserialization functions return the position of an input character which is at or before the cause of a parsing error (when the ErrRet option is used). In version 6.4, the $function forms returned the value “1” to indicate a parse error.

$XML_PRINT of ill-formed XmlDoc (conversion note)

In version 6.4, the $XML_PRINT function was not allowed if the top of the subtree to be printed was the Root node, and the XmlDoc did not contain an Element (an XmlDoc in this form is called “not well-formed” - every well-formed XmlDoc must contain an Element node). Since the $XML_PRINT function was designed to support debugging, not serialization of an XmlDoc, this is now allowed in the version 6.5 Print method.

Exclusive/redundant serialization options

In version 6.4, the serialization $functions (e.g., $XML_PRINT) allowed an option to be specified multiple times. Mutually exclusive options were also allowed, with the last one having effect. Both of these cases are now treated as errors.

Unicode XPath comparisons

In accord with the XPath Recommendation, an ordered comparison in an XPath expression is performed using the Unicode collating sequence. In some cases, this differs from the EBCDIC collating sequence, which was used in version 6.4. If you want all XPath expressions on an XmlDoc to use EBCDIC collation, set the XPathOrder property to EBCDIC.

Mixed case property values

When converting from $Xml_Type to the Type property, or from $Xml_Info('Namespace') or $Xml_Set('Namespace', value) to the Namespace property, please note that these properties return values with the initial letter capitalized and the rest of the value lowercase. Also please note that for the Type method, the name of the root of an XmlDoc tree is 'Root', rather than the former value of 'DOCUMENT'.

Empty XPath result causes request cancellation

An empty XPath result causes request cancellation with the following methods: Length, LocalName, Prefix, QName, URI, Print, Serial, Type, and Value. The like-named $Xml_xxx functions did not cancel the request in these circumstances, but rather had a special result defined for the empty XPath result.

Janus TCP/IP Base

The following backwards incompatibilities are introduced in Janus TCP/IP Base:

JANUS DEBUG not allowed

Formerly, you could use JANUS DEBUG as an alias of the JANUS TRACE command. Use of this alias is no longer available.

Fixes in Sirius Mods 6.5 but not in 6.4

Janus SOAP

Retain Namespace property after parse failure

Previously, an error during deserialization of an XML document would completely re-initialize the XmlDoc, causing the Namespace setting to be lost. Deserialization errors now will retain the value of the Namespace property.

Detect “?>” in all $XML_INSPI cases

Previously, if the value (argument 3) of $XML_INSPI contained the characters “?>” (which are invalid in that context), for a very small number of such cases, the error was not detected.

Duplicate $XML_NODES/PLC/COUNT with “..”

Previously, use of the parent axis in an XPath expression could produce duplicate nodes as the result of $XML_NODES or $XML_PLC, or in an incorrectly large value as the result of $XML_COUNT.

Control characters disallowed

Previously mentioned as a compatibility issue.

No “]]>” in serialized result

Previously mentioned as a compatibility issue.

Unicode XPath comparisons

Previously mentioned as a compatibility issue.

Return to top of page

Fast/Unload Version 4.2

Return to top of page

Version 4.2 of Fast/Unload was released in March, 2004. The major enhancements are summarized below. Please refer to the Fast/Unload Release Notes Version 4.2 for a more detailed discussion of the release or to the Fast/Unload Reference Manual for information on how to use Fast/Unload.

Support for procedures

As of Fast/Unload version 4.2 and Sirius Mods 6.5 the UAI and LAI statements support the reorganization of procedures and procedure aliases.

The UAI unloading of procedures and procedure aliases is invoked for UAI unloads by default or by the new UAI statement option PROCS. If you specify PROCS, any procedures or procedure aliases in the file are unloaded; if you specify the new option NOPROCS, they are not unloaded. PROCS is the default.

Statistics about the file's procedures are produced when you invoke FSTATS processing or invoke procedure unloads (explicitly or implicitly), and generating these statistics enables an optimization of the procedure dictionary reloading.

Procedures and aliases present in the input data set for a Fast/Reload are loaded &oq;as is&cq; by LAI. The UAI unload and LAI reload preserve their associations. The LAI procedure loading entails some environmental adjustments (especially more disk buffers), and it also includes an automatic PDSIZE-setting feature.

New or changed program parameters

The following parameter is enhanced in version 4.2:

FSTATS

All settings of FSTATS now generate procedure dictionary statistics. If UAI PROCS is also specified for any output stream, or UAI NOPROCS is not specified for any output stream, procedure text page statistics are included in addition.

New or changed FUEL statements

The following directive is enhanced in version 4.2:

FSTATS

All settings of FSTATS now generate procedure dictionary statistics. If UAI PROCS is also specified, for any output stream, or UAI NOPROCS is not specified for any output stream, procedure text page statistics are included in addition.

Miscellaneous enhancements

• Multiple output streams with Fast/Unload User Language Interface

  The multiple output feature was introduced in Fast/Unload 4.1, but not supported for the Fast/Unload User Language Interface until Fast/Unload version 4.2 (and Sirius Mods 6.5).

  To use $FUNLOAD to invoke a multiple output version 4.2 Fast/Unload you specify any character string (eight-character maximum and not a %variable or asterisk) as the $FUNLOAD fourth argument. This string is not used, but it indicates that the output data is to be sent to the data sets specified in the FUEL program.

  Prior to Fast/Unload 4.2 and Sirius Mods 6.5 such a character string in a $FUNLOAD fourth argument was assumed to name an output data set specified in the FUEL program.

  Specifying multiple outputs in a Fast/Unload 4.1 FUEL program that is invoked by $FUNLOAD is an error, regardless of the Sirius Mods version.

Backwards compatibility with Fast/Unload 4.1

This section lists any differences in processing that result from execution with Fast/Unload version 4.2, as compared with the same inputs to Fast/Unload version 4.1 at current maintenance levels.

UAI unloads

In Fast/Unload 4.2, UAI unloads, by default or if UAI PROCS is specified, will unload any input file procedures and procedure aliases. Specifying UAI NOPROCS prevents the unloading of procedures and aliases.

Prior to version 4.2, the UAI PROCS and NOPROCS options did not exist, and the UAI default was not to unload procedures.

Version co-requisites

This section lists any restrictions on usage of various products (including Fast/Unload itself) which will be imposed by use of version 4.2 of Fast/Unload.

• Using the Fast/Unload 4.2 multiple output feature with the Fast/Unload User Language Interface requires at least version 6.5 of the Sirius Mods.

Return to top of page

Fast/Unload Version 4.1

Return to top of page

Version 4.1 of Fast/Unload released in September, 2003. The major enhancements are summarized below. Please refer to the Fast/Unload Release Notes Version 4.1 for a more detailed discussion of the release or to the Fast/Unload Reference Manual for information on how to use Fast/Unload.

Maintenance and Support

These enhancements to Fast/Unload do not affect its intrinsic functionality, but they do improve its maintainability.

New #function - #ABDUMP

ABEND the Fast/Unload job, with a specified completion code.

Change to display of program listing

The statement offset of the generated code is displayed on each line of the listing of the FUEL program.

New Features

The primary addition in Fast/Unload 4.1 is the ability to produce multiple output data streams from a single pass over an input file. Related changes relieve limits on the size and complexity of FUEL programs and support for “preprocessor” directives to support FUEL programs that support many versions of a file design.

Larger FUEL programs

In Fast/Unload version 4.0, the size of a FUEL program was limited, based on a maximum size of the generated code of about 4 million bytes. This limit has been removed. This feature was also implemented as part of the maintenance zaps to Fast/Unload version 4.0, but it was not previously mentioned in any Release Notes.

The limit to the size of a FUEL statement has also increase — the default has been more than tripled, and you can increase the limit even further with the new LIBUFF program parameter. An increase to the limit was also implemented as part of the maintenance zaps to Fast/Unload version 4.0, but it was not previously mentioned in any Release Notes.

New or changed program parameters

The following new parameters may be passed to Fast/Unload:

FNVMASK X"yz"

FNVMASK specifies which of the 8 characters of the name of the file being unloaded may differ from the file name stored on the disk pages of the Model 204 file.

If Fast/Unload is invoked via the Fast/Unload User Language Interface, the value of the FNVMASK parameter in Model 204 is automatically communicated, and this is the default value of FNVMASK for the unload. Invoking the Fast/Unload User Language Interface with a non-zero value of FNVMASK in Model 204 requires the use of version 6.1 or later of the Sirius Mods.

LIBUFF n

LIBUFF may be used to increase the limit on the length of a FUEL statement.

SORTOUTD

SORTOUTD has been added as a third option (along with FUNOUT and SORTOUT) to control output from sort(s) invoked by Fast/Unload. These three parameters are mutually exclusive, and SORTOUTD is the default.

• If FUNOUT is specified:
  Fast/Unload will handle all output from invoked sorts, sending each stream to the destination (DDNAME, FILEDEF) specified in the declaration of the stream (OUT TO dest or UAI TO dest). For legacy FUEL programs (that is, one output stream, not explicitly declared), output will go to FUNOUT. .If SORTOUT is specified:
  For legacy UAI programs, the sort itself will send output to FUNOUT. For legacy non-UAI programs, the sort will send output to SORTOUT.

  For non-legacy programs, the sort will do the output for each sorted output stream; the name of each particular output stream will be sent to the particular sort by an internally generated

  OPTION SORTOUT= <i>dest</i> sort control statement.
• If SORTOUTD is specified:
  This option works like SORTOUT except for legacy non-UAI programs, for which the sort will send output to FUNOUT, not SORTOUT, consistent with the handling for UAI sorted output.

#IF, #ELSEIF, #ELSE, and #END IF "preprocessor" statements

#IF through #END IF statement blocks allow the FUEL programmer to write programs that work across a variety of different files, even if all the files do not contain exactly the same fields.

#IF { DEFINED | UNDEFINED } tests the currently open file; subsequent FUEL statements are compiled if the #IF statement is true, that is, if the specified is defined (or not defined) in the currently open file.

#ELSEIF { DEFINED | UNDEFINED } statements optionally follow the #IF. An optional #ELSE statement is always true.

A #IF block must end with a #END IF statement. #IF blocks may not be nested.

The first #IF / #ELSEIF / #ELSE block that is true causes all FUEL statements to be compiled up to the next #ELSEIF / #ELSE / #END IF block. All other statements following such a true #ELSEIF / #ELSE / #END IF block are skipped until the #END IF is reached.

Multiple output stream support

OUT TO <i>destination</i> [DEF[AULT]] UAI [TO <i>destination</i> [DEF[AULT]]] ... SORT [TO <i>destination</i>] ... [TO <i>destination</i>] PUT ... [TO <i>destination</i>] OUTPUT [TO <i>destination</i>] PAI [TO <i>destination</i>] UNLOAD[C] [...] ... #RECOUT[(<i>destination</i>)] ... ... #OUTLEN[(<i>destination</i>)] ... ... #OUTPOS[(<i>destination</i>)] ...

In the statements shown above, the OUT TO destination and UAI TO destination serve as declarations specifying the name of an output stream. This name is used in the TO destination clause on subsequent statements that actually generate the output.

The stream name is also used as the parenthesized qualifier on the special variables #RECOUT, #OUTLEN, and #OUTPOS. And similarly, the SORT [TO destination] qualifier associates the sort control statement to a particular stream.

In addition, a SORTOUTD parameter is now available as a third option (along with FUNOUT and SORTOUT) to control output from sort(s) invoked by Fast/Unload.

Please refer to the Fast/Unload Reference Manual for the details of Fast/Unload multiple output stream support.

Miscellaneous enhancements - nesting level

Whenever the nesting level changes within a FUEL program, the new level is displayed on the program listing, along with an indication whether it is increasing or decreasing (or, in some cases, creating a block of code with neither an increase nor decrease).

Backwards compatibility with Fast/Unload 4.0

This section lists any differences in processing that result from execution with Fast/Unload version 4.1, as compared with the same inputs to Fast/Unload version 4.0 at current maintenance levels.

SORTOUT, SORTOUTD parameters

In version 4.0, SORTOUT was the default. In version 4.1, SORTOUTD is the default.

Return to top of page

Sirius Mods Version 6.4

Return to top of page

Version 6.4 of the Sirius Mods was released in May, 2003. The major enhancements are summarized below. Please refer to the Sirius Mods Release Notes Version 6.4 for more detailed information.

Maintenance and Support

The Sirius Mods Version 6.4 adds support for Model 204 version 5.3 and drops support for Model 204 version 4.1.1.

All or Multiple Products

Since versions of Sirius Mods older than 5.4 are not supported, references to versions older than that have been removed from some manuals.

SIRIUS MAINT command

The SIRIUS MAINT command will display information about the current maintenance level of the Model 204 load module.

LOBUFF truncation

Prior to version 6.4 of Sirius Mods, "print" output lines retrieved by $LIST_CAPTURE or $SOCK_CAPTURE, or redirected to a client browser by $WEB_ON, are truncated if their length exceeds the value of the Model 204 LOBUFF parameter setting. In version 6.4, this LOBUFF truncation remains only for $LIST_CAPTURE.

$LIST_CAPTURE is described in the Sirius Functions Reference Manual; $SOCK_CAPTURE is described in the Janus Sockets Reference Manual; $WEB_ON is described in the Janus Web Server Reference Manual

New compression $functions

$DEFLATE and $INFLATE are new functions which allow compression and decompression of longstrings using the "deflate" algorithm described by RFC 1951. They are described in the Sirius Functions Reference Manual.

NCMPBUF parameter

The NCMPBUF User 0 parameter sets the number of compression buffers available for the duration of the online run. The NCMPBUF parameter must be set by User 0 before the $DEFLATE or $INFLATE functions can be used or before Janus Web Server compression takes effect. For example, if $DEFLATE or $INFLATE is called with NCMPBUF = 0, the request is cancelled.

NCMPBUF should be set to the maximum number of users expected to concurrently use the compression feature. Compression buffers may also be used by Janus Web threads. About 309K bytes are required for each NCMPBUF. These are allocated in 31-bit storage.

Janus SOAP

The following sections describe new or changed features in Janus SOAP.

Note that we are planning for some pervasive changes for the Janus SOAP $functions API in version 6.5; one of these will be to remove the use of a contx_n argument in $functions that have an XPath expression argument. As a start in this direction, we have implemented $XML_PLC and $XML_DEL with an XPath expression argument, but no contx_n argument.

$XML_xxx functions

This section describes $XML_xxx functions which are introduced in version 6.4 or which had been documented in version 6.3, but are only now fully supported.

• $XML_CHECK This new $function allows you to check whether an XMLDoc or nodelist ID is valid.
• $XML_COP This new $function allows you to copy an XMLDoc sub-tree as the child of another node, either in the same XMLDoc or in another one.
• $XML_DEL This new $function allows you to delete an XMLDoc sub-tree; note that if any deleted nodes had been referenced in a nodelist, they may not subsequently be referenced using a relative XPath expression.
• $XML_NODE_SING This new $function is the same as $XML_NODES, except that it only gets the first node matching the XPath expression argument; therefore it can be more efficient for a large document, if you only need one node in the target nodelist.
• $XML_PLC This $function is now supported.
• $XML_RMV_NL This $function is now supported; it can be useful to remove items from a nodelist for nodes deleted by $XML_DEL, so that the whole nodelist is still usable.
• $XML_SER This new $function serializes a sub-tree of a document, and provides an EBCDIC option.

XPath changes: predicates

This section describes forms of XPath predicates which are now supported in version 6.4. Within a single step, only one predicate may occur, and location paths within predicates cannot themselves contain predicates.

• [<n>] predicate This XPath predicate is now supported; for example: /book/chapter[2]/section[9]/paragraph[3]
• Location path within predicate You can now use a location path in a predicate of an XPath expression. This can take either of two forms, an "existence" test, or a "value comparison" test; simple examples of these are shown below. Note that the location path in a predicate can be any supported location path, including multi-step and absolute expressions.
• Existence test You can now use a location path as a predicate of an XPath expression; the predicate evaluates as true if the resulting nodeset is non-empty. The usual (but not only) purpose of this predicate is to select a node if it has at least one attribute or element of a given name; for instance: /active/cust[invoice]/contact[fax] The above example selects all contact children of cust elements, if the cust element has an invoice child element and the contact has a fax child element.
• Comparison test You can now use a location path followed by a comparison operator and literal as a predicate of an XPath expression; the predicate evaluates as true if the comparison is true of at least one node in the resulting nodeset. The usual (but not only) purpose of this predicate is to select a node if it has at least one attribute or element whose value bears the requested relationship to the literal; for instance (if the following two lines are combined as one XPath expression): /bills/cust[@bill_dt<"20030101"]/ contact[state="MA"] The above example selects all contact children of cust elements billed before 2003, if the contact has a state child element with the value "MA".

Other changes

• New NOEMPTYELT option This option of the serialization $functions specifies that an empty element be serialized with a start tag and end tag (e.g., "<foo></foo>") rather than an empty-element tag ("<foo/>").
• Remove limit on nodelists The initial version of Janus SOAP had a limit on the number of nodes in a nodelist; this has been removed.
• contx_n checking The "contx_n" argument is now always checked, if you provide one explicitly: it must either be 1, if it corresponds to an XMLDoc ID argument, or less than or equal to the size of its correspoding nodelist argument, and greater than zero. A common error which this will now detect is an "options" argument in the wrong position with an absolute XPath expression; for example: * It should be: * .. $XML_PRINT(%D, '/', , 'INDENT 1') %X = $XML_PRINT(%D, '/', 'INDENT 1') Note that this introduces a minor backward incompatibility because such errors were not detected in version 6.3.

Janus Network Security

The following features are new or changed in Janus Network Security:

New security protocol option: TLS

Prior to this release, Janus Network Security offered support only for the SSL (Secure Sockets Layer) protocol, versions 2 and 3, created by Netscape. This release adds support for the TLS (Transport Layer Security) protocol, developed by the IETF Internet standards group. TLS is a more secure extension to SSL V3, and it is supported for both client and server Janus ports.

Since TLS is an extension and not a fundamental change to SSL, general references to SSL in the Janus Network Security Reference Manual now imply TLS as well, or they are stated as "SSL/TLS" or as "SSL-like." Explicit references to TLS are included where appropriate.

TLS support introduces only the following visible changes to Janus security implementation:

• The SSLPROT parameter of the JANUS DEFINE command has two new bit settings:
  • X'04', if a port will support only TLS.
  • X'07', if a port will support TLS, SSL v3, and SSL v2, and offers them in that order of preference. This is the new SSLPROT default.
• The $WEB_PROTOCOL web server function may now return "4" (which corresponds to the new SSLPROT value), if TLS is being used for the connection.

Janus Sockets

The following features are new or changed in Janus Sockets:

FINCLOSE parameter for $SOCK_CONN

This new option on $SOCK_CONN indicates to Janus Sockets that if the other side of a connection closes the connection, even if it does so "cleanly" (that is with FIN rather than RESET), the connection is to be closed immediately. This is useful in situations where FIN is as good as RESET for rendering a connection unusable, and where it's important to know that a FIN has been sent to avoid wasted processing or even a hung connection.

One specific application for this capability is a Janus Sockets application communicating with a web server that is using a keep-alive facility (multiple requests over the same TCPIP connection). In such a situation, the web server could close the connection between any pair of requests, and it appears most web servers do this with a FIN. Without FINCLOSE, the Janus thread that made the connection to the web server would remain in-use until the Janus Sockets application tried to receive data on the connection and so noticed the closed connection.

FINCLOSE and its inverse NOFINCLOSE can be specificied on a $SOCK_CONN call or, to set a port-wide default, on the JANUS DEFINE command for a port.

LOBUFF truncation

"Print" output lines retrieved by $SOCK_CAPTURE are no longer truncated if their length exceeds the value of the Model 204 LOBUFF parameter setting. In addition, long print lines no longer wrap at the Model 204 OUTCCC limit, nor are they truncated at the Model 204 OUTMRL limit.

A long print line is captured as a single "logical" line (with a single trailing LINEND string, as specified on the JANUS DEFINE command or $SOCK_SET for the socket).

New PUSH keyword for $SOCK_SEND and $SOCK_SENDLN

Specifiable as the third argument for these functions, PUSH ensures that the data being sent on the socket is immediately sent to the receiver. Normally, data to be sent is buffered and may not be sent immediately. Using PUSH is not necessary if:

• You are specifying FIN, since a push operation is implied by FIN.
• You are alternating sends and receives on a socket, since receive-processing functions ($SOCK_RECV and $SOCK_RECVPRS) always do a push before receiving.

Janus Web Server

The following features are new or changed in Janus Web Server:

URL Matching for Persistent Sessions

Janus Web Server now only requires the initial part of the URL to match the original URL for a persistent session, that is one that uses $WEB_FORM_DONE. The first $WEB_FORM_DONE establishes the base URL and any request with a URL whose start matches this base URL (assuming userid and other basic criteria also match) will be considered a response to the $WEB_FORM_DONE. This allows URL parameters to be added to a base URL in a persistent session or even to have hypertext links that can continue a persistent session on one of its pages. For example, if a persistent session was created by URL /cust/update?crn=54321, a page generated for this session could have a link like <a href="/cust/update?crn=54321&view=history">History</a> and when the user clicks on this link it would cause the $WEB_FORM_DONE for the session to return. At that point the request could examine the URL parm using $WEB_ISINDEX_PARM or $WEB_PARM, determine that the URL parameter view is set to "history" and take appropriate action.

SirFact

The following features are new or changed in SirFact:

APSY Maintenance Enhancements

Several new features facilitate the maintenance of large-scale APSY subsystems. The various features are controlled by bits of the SIRFACT user 0 parameter:

X'40'	Causes all procedures to be copied to CCATEMP before being processed by INCLUDE. After the copy the share enqueue on the procedure is released. Note that this feature can be useful whether a procedure is INCLUDE'd as part of an APSY subsystem or directly from Model 204 command mode.
X'80'	Enables a variety of APSY subsystem maintenance enhancements that are described below.

Once the maintenance enhancements are activated, their individual behavior can be controlled on a system-wide or subsystem basis. System-wide control is achieved by setting the following bits of the SIRAPSYF user0 parameter:

X'01'	Allows compilations to be saved even if the outer procedure (or a procedure it includes) was found in an unlocked procedure file of the APSY procedure group. If a pre-compilable outer procedure is changed in or added to an unlocked file in the procedure group, the procedure will be re-compiled and that compilation saved.
X'02'	Keep track of the names and locations of all included ("inner") procedures that are used in compiling a procedure whose compilation is saved, provided that a subsystem is using a procedure group with one or more unlocked files. Then if an inner procedure is changed or added to an unlocked file, automatically recompile all affected "outer" procedures and re-save their compilations.
X'04'	Keep track of all the pages used by saved compilations in each subsystem, using a bitmap for each subsystem. When the subsystem is STOPped, this bitmap is used to free the pages, providing a significant reduction in the amount of CCATEMP I/O and elapsed time.

Note that for the purposes of both the X'01' and X'02' bit, an inner or outer procedure is considered changed if the actual procedure is modified or if a new version of the procedure is added to an earlier file in the procedure group. When using temporary procedure groups, a request compilation will not be saved if any of the outer (or inner) procedures came from a file not in the subsystem's permanent group.

The feature control bits in SIRAPSYF may be overridden by values set for each subsystem. For more information on subsystem-specific controls and some arcania about changed enqueueing behavior, please refer to the Sirius Mods Release Notes Version 6.4.

These facilities extend Model 204's unique "compile on first use" behavior to an even more powerful "compile on first change". The ability to update APSY subsystems on-the-fly while still saving compilations can significantly increase programmer productivity. However, two problems can arise when attempting post-hoc error correction or real-time subsystem maintenance on a busy system:

• When more than one procedure needs to be updated in a coordinated fashion, it is possible that a user could start re-compiling a procedure before all required procedure updates are complete. The resulting mix of old and new versions could result in compilation errors or, perhaps even worse, incorrect application behavior.
• The Model 204 compiler obtains share locks on the procedures it reads during compilation. While the SIRFACT X'40' bit significantly shortens the time during which such an enqueue is held, it is still possible that in a busy system a procedure update could be stymied by enqueue conflicts.

To help deal with these problems, SirFact has introduced the concept of quiescing a subsystem — that is getting all users into a state where they are not likely to compile inconsistent sets of inner and outer procedures or block procedure update operations. A subsystem is "quiesced" if all users are either evaluating a pre-compiled request (as determined by the request's prefix not its true pre-compilability) or between procedures in the subsystem driver loop. Another way to think of this is that a subsystem is quiesced if no users are inside a non-pre-compiled procedure or compiling pre-compiled procedures.

A subsystem can be quiesced with the SIRFACT QUIESCE command and then "unquiesced" or resumed with the SIRFACT RESUME command:

SIRFACT QUIESE subsys [WAIT sec] [BUMP] SIRFACT RESUME subsys where

	subsys	The name of the subsystem to be quiesced or resumed.
	sec	The number of seconds to wait for the subsystem to be quiesced. If the subsystem is quiesced before this time the command simply returns. If the subsystem is still not quiesced after this time it will either return with an error message, or if BUMP is specified it will attempt to bump all non-quesced users.
	BUMP	Indicates that any users preventing the subsystem from being quiesced (after waiting as directed by the WAIT arhument) should be bumped.

When a SIRFACT QUIESCE is issued for a subsystem the subsystem enters a quiescing state. While quiescing, any user that is going to switch to the next procedure in the subsystem driver will be stopped until the subsystem is resumed. In addition, any user that exits a pre-compiled procedure will be stopped at end of request. Other users will continue to run until they hit one of these two points.

Compatibility/Bug fixes

There are some backward incompatibilities introduced by Sirius Mods version 6.4.

Janus SOAP

Checking of contx_n arguments

The contx_n argument is now always checked. If you provide one explicitly: it must either be 1, if it corresponds to an XMLDoc ID argument, or less than or equal to the size of its correspoding nodelist argument, and greater than zero. As a result of this change, some programs that were in error may have run successfully under version 6.3 of the Sirius Mods, but will now cause request cancellation.

Return to top of page

Sirius Mods Version 6.3

Return to top of page

Version 6.3 of the Sirius Mods was released in October, 2002. The major enhancements are summarized below. Please refer to the Sirius Mods Release Notes Version 6.3 for more detailed information.

Maintenance and Support

As of version 6.3, the Sirius Mods no longer supports Model 204 version V4R1.0.

Janus SOAP

The following features are new or changed in Janus SOAP:

<!DOCTYPE ...>

This phrase is now allowed for the deserialization $functions, using the DTD_IGNORE option.

Control of <?xml version...?>

The serialization $functions, and $XML_PRINT, now have options to either allow or suppress the "xml declaration".

Other $XML_PRINT options

$XML_PRINT provides an INDENT option to control indentation width.

CDATA

The <![CDATA[...]]> clause is now supported.

XMLDoc generating/updating

The $XML_INSATT, $XML_INSCOM, and $XML_INSPI functions are now supported. In addition, there are no restrictions to the order in which a document is created. The $XML_INSTEXT function is supported, but it is restricted to not allow insertion of adjacent TEXT nodes.

Global XMLDocs

The $XML_DOC_GLOBAL and $XML_DOC_GLOBAL_DEL functions allow you to create, retrieve, and delete global XMLDocs, so that their content can be preserved across User Language requests.

Session XMLDocs

The $XML_DOC_SESSION and $XML_DOC_SESSION_DEL functions allow you to create, retrieve, and delete session XMLDocs, so that their content can be preserved over a logical session that can span mutiple logins and logouts.

UTF-8/16

Initial Unicode support is provided in this version:

• UTF-8 and UTF-16 encoding may occur in "inbound" streams ($XML_STR2DOC and $WEB_XML_RECV).
• UTF-8 is always generated for "outbound" XML ($XML_DOC2STR and $WEB_XML_SEND).

PI targets

A processing instruction target (conceptually, the "name" of a PI) can now contain any character as described by the XML standard.

Text node length

A text node's length is now limited only by the maximum size of a $list and the other data in a document, all of which are stored in a single internal $list (about 3.5 gigabytes is the limit of a single $list).

Whitespace handling

For TEXT nodes in most business-to-business applications, leading and trailing whitespace should be removed, and multiple whitespace characters should be combined as one. This is the default behavior of the deserialization $functions ($XML_STR2DOC and $WEB_RECV_XML); it can be over-ridden (to preserve all whitespace in TEXT nodes) with the WSP_PRESERVE option.

XML parse errors

The information presented by an error deserializing an XML document ($XML_STR2DOC and $WEB_XML_RECV) shows where the error occurred in the serialized document character stream, including the fragment of the stream near the error with a "pointer" showing the current parsing location.

XPath parse errors

The information presented by an error parsing an XPath expression now is specific to what the parser expected, replacing the generic "Invalid XPath expression" message.

Further improvements to performance and scalability

Various internal changes have been made to facilitate more intensive XML and XPath processing.

Janus Sockets

The following features are new or changed in Janus Sockets:

LONGSTRING support

All Janus Sockets $functions are now LONGSTRING capable. Most important in this regard is that $SOCK_SEND can send a LONGSTRING containing more than 255 bytes in a single call, $SOCK_RECV and $SOCK_RECVPRS can receive more than 255 bytes in a single call and $SOCK_TRAN_IN and $SOCK_TRAN_OUT can translate more than 255 bytes in a single call.

$SOCK_SSL_ON

This function makes it possible to make an initial connection from a Janus Sockets client application to a proxy server, use the CONNECT method to connect to a server through the proxy and then communicate via SSL with the back end server, simply having the proxy server act as a "tunnel" for the SSL data. Basically, the $SOCK_SSL_ON should be used after a positive response has been received for a CONNECT method request on a Janus Sockets client socket. For more information on HTTP tunneling and the CONNECT method see http://www.ietf.org/rfc/rfc2817.txt.

Janus Web Server

The following features are new or changed in Janus Web Server:

Compression

Janus Web Server can now use deflate compression upon request. Compression can be indicated on the JANUS DEFINE command, JANUS WEB ON rules and $WEB_SET. The compression value can be 0 meaning to use no compression, 1 meaning to use deflate duplicate compression and 2 meaning to use duplicate compression and Huffman character encoding. Data compression requires a not insignificant amount of CPU (COMPRESS 2 requiring more than COMPRESS 1) and an extra 64K of virtual storage for each thread on any web port with compression enabled. For example, a port with compression enabled and 20 threads would require an extra 20*64K or about 1.3M of extra virtual storage for the compression buffers. The advantage of compression, of course, is that compressed data will use less network bandwidth, anywhere from 30% less to 80% less, depending on the datatstream. Images tend to be in a compressed format already so generally do not compress any more and are not compressed by Janus Web Server.

To enable deflate compression on a port, the COMPRESS parameter must be specified on the JANUS DEFINE command for the port. If this is not done, compression could be requested in JANUS WEB ON rules or with $WEB_SET but is ignored. If some compression is required but the port default should be no compression, simply specify COMPRESS 0 on the port definition and set compression on a URL basis in JANUS WEB ON rules or on an application basis with $WEB_SET.

Enhanced wildcard processing in JANUS WEB ON rules

Janus web ON rules now allow wildcard substitution in FILE and GROUP names in the OPEN clause. This substitution always occurs before substitution in the CMD or SEND clause. For example, with the rule JANUS WEB WEBPORT ON /TEST?/* OPEN FILE QA* - CMD 'I *' the URL /test5/queequeg would result in the file QA5 being opened and procedure QUEEQUEG inside QA5 being INCLUDEd.

In addition, variable data from a URL can now be substituted out of order by indicating the wildcard match position after a double-quote character. For example, with the rule

JANUS WEB WEBPORT ON /*/TEST?/* OPEN FILE TEST CMD 'I MOBY"2,*' the URL /xyz/test5/tashtego would result in the file TEST being opened and the command "I MOBY5,TASHTEGO" being issued. As this example illustrates, an asterisk after a positional replacement string uses the replacent string after the positional string. It is possible with positional replacement strings to re-use replacement strings. For example, with the rule JANUS WEB WEBPORT ON /TEST* OPEN FILE TEST CMD 'I A"1' AND 'I B"1' and 'I C"1' the URL /test3 would result in the file TEST being opened and the commands "I A3", "I B3" and "I C3" being issued.

Error handling

In cases, such as a User Language programming error that cancels the request, Janus Web Server automatically generates a web page describing the error. This has been improved so that:

• In addition to the last error message, up to two other messages may be displayed, these messages correspond to the messages that can be obtained by $FSTERR and SETGRC.
• The response header parameters on this page are set so that it should always be displayed by the browser.

Also, a new section has been added to the Janus Web Server Reference Manual which briefly mentions the various error handling considerations when using Janus Web Server.

HEADJS and ONLOAD parameters on SCREEN rules

HEADJS and ONLOAD can now be specified on JANUS WEB SCREEN rules. HEADJS indicates a URL that will be pointed to by a <script> tag inside the tag in Janus Web Legacy Support screens. This allows embedding of JavaScript outside the HTML body which can be useful on occasion. It is often especially useful to have one or more JavaScript methods inside the header that are invoked when the page body is loaded as indicated the the onload attribute in the <body> tag and so is most useful in conjunction with the ONLOAD JANUS WEB SCREEN rule parameter.

ONLOAD indicates JavaScript statements to be placed inside the onload attribute in a <body> tag. This allows JavaScript to be invoked before the page is actually rendered but after it's been fully received from the network. The JavaScript statements indicated in the ONLOAD parameter are placed after any Janus Web Legacy support onload JavaScript statements (currently only used for cursor positioning) so that Janus Web Legacy support actions (such as cursor position) can be overridden by locally specified actions.

SCREENURL/NOSCREENURL parameters

SCREENURL and NOSCREENURL can now be specified on the JANUS DEFINE command for web ports and on JANUS WEB SCREEN rules. SCREENURL indicates that Janus Web Server should generate a new URL for Janus Web Legacy Support screens. Prior to Sirius Mods 6.3 a special legacy URL would be generated if NOSCREENREDIR was in effect for a request. As of Sirius Mods 6.3 NOSCREENREDIR does not generate a legacy URL unless SCREENURL is specified and, in fact, SCREENURL could be specified with SCREENREDIR.

$WEB_NOCACHE function

Sets various response header parameters so that the browser will display a new version of the page, ignoring any cached version.

$WEB_SAVE_xxx and $WEB_REST_xxx enhancements

$WEB_SAVE_RECSET, $WEB_SAVE_LIST, $WEB_REST_RECSET and $WEB_REST_LIST have been extensively enhanced. First they all accept a new optional control string. The control string consists of a list of blank delimited keywords that provide fine-grained control over error handling and the semantics of whether lists are "copied" or "moved" when saving and restoring. If no control string is provided, the functions assume their default behaviour.

The default behavior of all of these functions can, however, be changed on a thread basis by setting the SRSPARM parameter (which can be reset with $RESETN). If SRSPARM is set to 0 (the default), then the default behavior of these functions matches their behavior prior to 6.3. SRSPARM is a bitmask-style user parameter.

In addition to the new parameters and $function options, a host of new statistics have been added to track the performance of the saved record set facility and assist with setting its control parameters.

Sirius Functions

Several existing $functions and facilities have been enhanced with version 6.3 and many new $functions have been added.

$FIELD_LISTI and $FIELD_IMAGE enhancements

$FIELD_IMAGE and $FIELD_LISTI now accept an optional prefix to be prepended to each image item name when generating field names. This allows part of a field name prefix to be factored out of the item names in an image, producing more readable code when certain popular field naming conventions are followed.

Frequently a site will store a special value to act as a place holder for a "missing" value of field when the field is used in a repeating group. $FIELD_LISTI and $FIELD_IMAGE now accept a new optional argument (argument 4 for $FIELD_IMAGE and argument 6 for $FIELD_LISTI) which indicates a value to be replaced by a null when populating the target $list or image.

$lists as parameters to ECF programs

A $list identifier can now be passed to an ECF program as in EXTERNAL CALL COBPROG WITH $LIST inlist outlist where

	inlist	is the $list identifier to be passed to the ECF program as input.
	outlist	is the $list identifier to receive the data as modified by the ECF program. The contents of this $list are replaced with the ECF program output.

The input $list is copied into the ECF parameter area before the ECF program is called. The $list items are simply concatenated to each other and there is no way to determine where one ends and the next begins so presumably the $list items would all have the same length or some $list items have the length or number of occurrences of a following set of $list items which can be used in the ECF program to determine the structure of the data. However, the most common structure for passing data from a $list to an ECF program is likely to be a $list where all $list items have the same length. To facilitate use of such a structure, the $list ECF interface automatically places a one word (four byte) binary number of occurrences before the copied $list items in the ECF parameter area. This makes it possible, if the ECF program is written in COBOL, to refer to the $list as a DEPENDING array where the number of occurrences can vary at run-time. To refer to the $list, the COBOL program would look something like

LINKAGE SECTION. 01 STUBB. 03 NUM-HARPOONS PIC 9(9) BINARY 03 HARPOON-INFO OCCURS 0 TO 25000 TIMES DEPENDING ON NUM-HARPOONS. ... PROCEDURE DIVISION USING STUBB. If for some reason, this count is deemed undesirable in the linkage structure it can be suppressed via the NOCOUNT keyword in the EXTERNAL CALL statement as in EXTERNAL CALL COBPROG WITH $LIST %LIST NOCOUNT Multiple $lists and images can be passed in a single ECF call as in EXTERNAL CALL COBPROG WITH $LIST %LIST, - INIMAGE, - $LIST %LIST2

$LIST_ADD_ORDERED, $LIST_ADD_UNIQUE and $LIST_ADD_UNIQUE_ORDERED

These functions have the format %RC = $LIST_ADD_ORDERED(list, string) %RC = $LIST_ADD_UNIQUE(list, string) %RC = $LIST_ADD_UNIQUE_ORDERED(list, string) where

	list	is a $list identifier to which the string might be added.
	string	is the string to add to the $list.

$LIST_ADD_ORDERED always adds the indicated string even if that string already exists on the $list but the new item is inserted so that the $list is in EBCDIC order. $LIST_ADD_ORDERED assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate the correct insertion point.

$LIST_ADD_UNIQUE always adds the indicated string to the end of the $list but does not add it if there's already an identical $list item on the $list. $LIST_ADD_UNIQUE does not assume any order for the $list so sequentially scans the entire $list for matches to the string being added.

$LIST_ADD_UNIQUE_ORDERED only adds the indicated string to the $list if there isn't already an identical $list item on the $list. If the there are no matching items, the new item is inserted so that the $list is in EBCDIC order. $LIST_ADD_UNIQUE_ORDERED assumes that the $list is in EBCDIC order so it does a pseudo binary search to locate a match or the correct insertion point.

These functions all return either the item number added (if an item was added), or the negative item number of the matching item number if an existing item prevented an addition. Obviously, $LIST_ADD_ORDERED always returns a positive item number since it does not look for matches to ensure uniqueness.

$LSTR_GET_IMAGE and $LSTR_SET_IMAGE

$LSTR__GET_IMAGE converts the contents of an image into a LONGSTRING as in %LSTR = $LSTR_GET_IMAGE(image) where

image

is the name of the image to be retrieved.

$LSTR__SET_IMAGE sets the contents of an image from a LONGSTRING as in

%RC = $LSTR_SET_IMAGE(image, value) where

	image	is the name of the image to be set.
	value	is a longstring value to which to set the image.

$LSTR_SET_IMAGE returns the number of bytes set in the image.

$LSTR_GET_IMAGE and $LSTR_SET_IMAGE can be useful for maintaining multiple copies of or versions of an image in a single request, for maintaining one or more global copies of an image (using global LONGSTRINGs) without using the GTBL space required by the standard GLOBAL IMAGE feature and for maintaining copies of an image associated with a session that survives a logout (using session LONGSTRINGs).

Session $functions

Several new $functions are available to support sessions. A session is a workstream that might extend beyond a Model 204 login session and might even be transferred among multiple Model 204 threads or users. Sessions are especially useful for web applications that require some context to be maintained over multiple web requests, each of which requires a login and logout. Sessions are either owned by a specific user or are public in which case they are considered to be owned by "*", that is all users. Non-privileged users can only create, access and delete public sessions and those owned by themselves, that is by their own userids. Privileged, that is system manager or system administrator users can create, access and delete public sessions and those owned by any user.

Several new system parameters that control the availability and behavior of the session feature: Please refer to the Sirius Mods Release Notes Version 6.3 for a more detailed explanation. The following $functions have been added for session support:

• $SESSION_CREATE Creates a new session.
• $SESSION_DELETE Deletes a session.
• $SESSION_OPEN Opens a previously created session.
• $SESSION_CLOSE Closes the current session.
• $SESSION Returns a 1 if the user has a session currently open.
• $SESSION_ID Returns the id of the currently open session.
• $SESSION_OWNER Returns the owner of the currently open session.
• $SESSION_TIMEOUT Returns the timeout value of the currently open session.
• $SESSION_LIST Returns a $list of active sessions.

Session $lists

Several new $functions are available to support session $lists. Session $lists are just like global $lists except they survive a logoff and can be reestablished with the $SESSION_OPEN function. Any attempt to reference a session $list results in request cancellation if there is no current session established via a $SESSION_CREATE or $SESSION_OPEN call.

The new functions available to support session $lists are $LIST_SESSION, $LIST_SESSION_DEL and $LIST_SESSION_LIST which work exactly like $LIST_GLOBAL, $LIST_GLOBAL_DEL and $LIST_GLOBAL_LIST respectively except that they refer to $lists for the current session rather than those global to the current login.

Global and session LONGSTRINGs

Several new $functions are available to support global and session LONGSTRINGs. Global LONGSTRINGs are LONGSTRINGs whose values surivive end of request. Session LONGSTRINGs not only survive end of request but survive a logoff and can be reestablished with the $SESSION_OPEN function. Any attempt to reference a session LONGSTRING results in request cancellation if there is no current session established via a $SESSION_CREATE or $SESSION_OPEN call. Please refer to the Sirius Mods Release Notes Version 6.3 for a more detailed explanation. The following $functions have been added:

• $LSTR_SESSION Binds a LONGSTRING to a session LONGSTRING.
• $LSTR_GLOBAL Binds a LONGSTRING to a global LONGSTRING.
• $LSTR_SESSION_SET Sets the value of a session LONGSTRING.
• $LSTR_GLOBAL_SET Sets the value of a global LONGSTRING.
• $LSTR_SESSION_GET Retrieves the value of a session LONGSTRING.
• $LSTR_GLOBAL_GET Retrieves the value of a global LONGSTRING.
• $LSTR_SESSION_DEL Deletes a session LONGSTRING.
• $LSTR_GLOBAL_DEL Deletes a global LONGSTRING.

$SIR_WILD

Indicates whether the one string matches a Sirius-style pattern where a "*" matches any set of characters, a "?" matches any single character and a """ indicates that the following character is to be treated as a literal even if it is one of the three special wildcard characters. The format of the $SIR_WILD call is %RC = $SIR_WILD(string, wildcard) where

	string	is the string to be tested for a match.
	wildcard	is the string possibly containing wildcards againstwhich it is to be tested.

%RC is set either to 1 if the first string matches the second or 0 otherwise.

SirSafe

Shared DASD support for Sysplex and LPARs

SirSafe simplifies the operation of Model 204 in Sysplex and multiple LPAR environments. The SIRENQ stand-alone utility allows members of a Sysplex or GRS ring to "see" each other, providing automatic recovery from a variety of shared DASD enqueueing conflicts that arise when Model 204 jobs are scheduled across multiple systems. Extended monitoring and administration facilities within the Model 204 environment simplify administration of Sysplex environments.

The AUTHCTL command has been enhanced to better support the monitoring and management of shared DASD enqueueing within Model 204. The AUTHCTL VIEW command now indicates whether enhanced shared DASD enqueueing is active, and if so lists the systems which are visible and those which have become invisible:

	*** MSIR.0688: SirSafe enhanced shared DASD active on V210 (SIRIJES2)
	*** MSIR.0689: SirSafe Shared DASD visible system: V210 (SIRIJES2)
	*** MSIR.0689: SirSafe Shared DASD visible system: + Z140 (SIRIZOS4)
	*** MSIR.0689: SirSafe Shared DASD visible system: - TEST (SIRITEST)

The above example shows that enhanced shared DASD enqueueing is active for the current system, that the system Z140 has become visible since the last AUTHCTL VIEW or AUTHCTL REFRESH, and the the system TEST was visible but is currently not visible. Note that the eight-character "system name" is shown as well as the older four-character SMF ID for each system.

Suppose that a Model 204 online being tested under system TEST had several files open when the testing LPAR was reset. Rather than track down all the obsolete shared DASD enqueue list entries and delete them with an ENQCTL command, a second copy of SIRENQ can be run on the V210 system, with a parameter of "SMFID=TEST". This will cause any Model 204 instance on V210 to automatically clear the obsolete entries from TEST. While this second copy of SIRENQ is active, an AUTHCTL VIEW command would yield:

	*** MSIR.0688: SirSafe enhanced shared DASD active on V210 (SIRIJES2)
	*** MSIR.0689: SirSafe Shared DASD visible system: Z140 (SIRIZOS4)
	*** MSIR.0689: SirSafe Shared DASD visible system: TEST (SIRIJES2)

The presence of the system name makes it easy to spot duplicate copies of SIRENQ used to facilitate recovery. Note that if the system SIRITEST was restarted and rejoined the Sysplex or GRS ring, then when it's copy of SIRENQ was started, the operator of SIRITEST would receive an error notification indicating that SIRIJES2 was running a spoofing copy of SIRENQ.

Each Model 204 instance maintains its view of visible systems in an efficient manner. A new AUTHCTL command is available for causing Model 204 to manually rebuild its view of visible systems:

AUTHCTL REFRESH [CLEAR] The CLEAR option directs Model 204 to remove from its list any systems that were once visible, but are now invisible (i.e., those entries preceded by a minus sign). If a Model 204 instance is started without a copy of SIRENQ running, then an AUTHCTL REFRESH command is required to enable enhanced shared DASD enqueueing.

$SIR_CHECK_ACCESS function

The $SIR_CHECK_ACCESS function allows installations to code sophisticated interfaces between Model 204 applications and a System Authorization Facility such as RACF or ACF2. $SIR_CHECK_ACCESS lets a system security administrator maintain controls over "dataset names" that identify intended application actions. By calling the function at strategic points a User Language program can provide security with arbitrary granularity. The format of the $SIR_CHECK_ACCESS call is %RC = $SIR_CHECK_ACCESS( dsn, prefix, access, log) where

	dsn	an upper case "dataset name", following the usual rules. Note: if a prefix is provided, the prefix will be concatenated to the front of dsn with a separating dot ('.') and the resulting string must be less than 44 characters.
	prefix	a string indicating whether the provided dataset name is to be prefixed. Valid values are:
		NONE no prefix is to be provided (the default). AUTH the same HLQ used by SirSafe determined by the external authorizer in use:   RACF the RACF control group name in effect for the run, default M204RACF. ACF2 The character "R" with the ACF2 resource type appended, default R204. JOB the current job name. JOB.STEP the current job name and step name separated by a dot. AUTH.JOB the SirSafe HLQ and job name separated by a dot. CCASYS the dataset name for CCASYS
	access	flag indicated desired access, either "R" for read or "W" for write. The default is R.
	log	flag indicating whether failed access checks should be logged, either "Y" or "N". Default is "N", which suppresses logging.

$SIR_CHECK_ACCESS returns an integer value as follows:

	2	no authorizer running, call ignored
	1	access not allowed
	0	access allowed
	-1	resulting dsname (prefix.dsname) invalid
	-2	prefix argument invalid
	-3	read/write flag invalid
	-4	log/nolog flag invalid

Compatibility

This chapter lists any compatibility issues with prior versions of the Sirius Mods, that is, any differences in processing that result from successful execution with Sirius Mods version 6.2, as compared with the same inputs to Sirius Mods version 6.3.

Janus Sockets

$SOCK_SENDx argument values longer than 255

Since the Janus Sockets $functions are now LONGSTRING capable, any argument values longer than 255 bytes are passed in their entirety to the $function. In previous versions, such values would be truncated at 255 bytes. $SOCK_SEND and $SOCK_SENDLN present different behavior for this; for example, if %A and %B are STRINGs and their combined length exceeds 255 %RC = $SOCK_SEND(%SOK, %A WITH %B) would send the first 255 bytes of the concatenated results prior to Sirius Mods 6.3 but as of this version it will send the entire concatenated result.

$SOCK_RECV result

$SOCK_RECV now returns the number of bytes received when the RECVLIM is hit or a FIN is received. Before Sirius Mods 6.3 $SOCK_RECV used to return a 0 in such a case.

Sirius Functions

$COMMAND and $COMMNDL output width parameter

$COMMAND and $COMMNDL allow an output line width to be specified that is greater than 256. The maximum line width allowable in a $COMMAND and $COMMNDL is now the smallest LOBUFF value for any sdaemon in the Online. In addition, where these functions would silently set the line length to 80 and 256 respectively if an invalid line width was specified, as of Sirius Mods 6.3 these functions now cancel the request on an invalid line width value.

Return to top of page

Sirius Mods Version 6.2

Return to top of page

Version 6.2 of the Sirius Mods was released in May, 2002. The major enhancements are summarized below. Please refer to the Sirius Mods Release Notes Version 6.2 for a more detailed explanation.

All, or multiple products

Support for Model 204 Version 5.1

All products packaged in the Sirius Mods now support Model 204 Version 5.1.

Commands now available as operator commands The SIRIUS, JANUS, SIRFACT and BUMPSNAP commands are now available as operator commands, that is as responses to the Model 204 HALT command from either a real or virtual console under OS/390 or as a virtual console command under CMS.

Comments before user 0 parameter line

In addition to the various commands which are supported before the user zero parameter line (such as MSGCTL), you may now place Model 204 comments (that is, lines which begin with an asterisk and a space) before the user zero parameter line.

CASE Mixed/Upper command in Full Screen Editor

You may issue either of the following commands in the Model 204 Full Screen Editor:

CASE Mixed

This command indicates that terminal input is accepted "as is", without translation to upper case. This is similar to invoking the *LOWER command prior to entering the Full Screen Editor. The second word of this command "Mixed", may be abbreviated to any prefix.

CASE Upper

This command indicates that terminal input is translated to upper case. This is similar to invoking the *UPPER command prior to entering the Full Screen Editor. The second word of this command "Upper", may be abbreviated to any prefix.

Janus TCP/IP Base

The following features are new or changed in Janus TCP/IP Base:

JANUS command

The JANUS command can now be issued as an operator command, that is on the Online virtual console under VM or as a response to the HALT message under OS/390.

Janus Sockets

The following features are new or changed in Janus Sockets:

$SOCK_URL_ENCODE

Does URL encoding for an EBCDIC string so that special characters that can't be part of a URL or other parts of an HTTP request such as form fields are represented as their URL encoded equivalents which is simply a percent character followed by the hexadecimal representation of the ASCII character to which the EBCDIC character maps except for spaces which are encoded as pluses.

Janus Web Server

The following features are new or changed in Janus Web Server:

$WEB_BROWSER function

Returns the release of specified browser or 0 if not that browser. Valid browsers are IE for Microsoft Internet Explorer™, NS for Netscape Navigator™ and OPERA for, you guessed it, Opera™.

Janus Web Legacy Support Enhancements

Janus Web Server legacy support has been enhanced to use Cascading Style Sheets (CSS). This greatly improves the appearance and alignment of fields on a 3270 screen mapped to HTML. In additon it is now possible to set the color of a field that's BRIGHT but without an explicit color and it's possible to specify PF key positions on a legacy screen as either TOP, LEFT, RIGHT or BOTTOM. Janus Web Server legacy support also uses the accesskey attribute for PF keys to allow Alt-1 through Alt-= to be used as mouseless function keys with many browsers.

The Janus Web Server CSS for legacy support allows users to optionally specify their own style sheets for further customization of the appearance of legacy screens. Finally, a facility is provided to have Janus Web Server embed some JavaScript before and after a legacy screen which makes it possible to have legacy screens contained in pages with site specific graphics and text and also to specify images for the function keys.

Janus Web Server legacy support has also been enhanced to generate well-formed XHTML, that is all <input> tags are now terminated with a "/>" and all attributes on all tags are enclosed in double quotes. This makes it possible to treat a Janus Web Server legacy screen as XML for the purposes say of doing web-based 3270 screen-scraping.

WRAPJS parameter for ON rules

HTML does not allow a page to embed HTML from another URL but it does allow a page to embed JavaScript from another URL. This JavaScript can simply issue document.write calls to add HTML to the page at the point it was embedded and so can be used as the logical equivalent of an embedded HTML document. To eliminate the need for such embedded documents to contain all the document.write calls and their parentheses and quotes and to avoid the need to worry about "escaping" double quotes, the WRAPJS parameter is provided in JANUS WEB ON rules to indicate that Janus Web Server should automatically wrap each line of text in document.write calls and to precede every double quote with a slash character to prevent it from being treated as a close quote.

EXPIRE parameter for ON rules

The EXPIRE parameter in JANUS WEB ON rules now allows rules based setting of either absolute or relative expire times on pages as in JANUS WEB WEBPORT ON /MUMBLE/* OPEN FILE MUMBLE - SEND * EXPIRE 021131 JANUS WEB WEBPORT ON /FOO/* OPEN FILE FOO - SEND * EXPIRE +3600

Janus SOAP

Sirius Mods Version 6.2 introduces general availability of Janus SOAP. The XML API provided by Janus SOAP has been adapted to use the latest version of the XPath navigation language. In addition the storage model used by Janus SOAP has been simplified, in order to simplify debugging and make XMLDoc and nodelist instantiation more obvious. For more information, refer to the Janus SOAP Reference Manual.

SirFact

The following features are new or changed in SirFact:

SIRFACT command

The SIRFACT command can now be issued as an operator command, that is on the Online virtual console under VM or as a response to the HALT message under OS/390.

SIRFACT DUMP procedure substitution

Additional template characters for JANUS DUMPs allow for more flexibility in identifying SirFact dumps. This can be particularly useful for reducing the number of dumps saved to effect a sort of "first failure" policy.

TRACE statement

A new User Language statement, TRACE, has been added that acts very much like a PRINT or AUDIT statement with the exception that the target for the TRACE statement can be dynamically changed by RESET'ing the ULTRACE parameter. The ULTRACE parameter is a standard bit-oriented user parameter where the bits mean:

X'01'	Send TRACE output to terminal.
X'02'	Send TRACE output to audit trail.
X'04'	Send TRACE output to a CCATEMP wrap-around trace table.

The default setting for ULTRACE is X'01' which means that the TRACE statement will act pretty much like a PRINT statement. The bits can be combined so that output could be sent to both the terminal and the audit trail or to the CCATEMP wrap-around trace table and to the terminal and to the audit trail. If a TRACE statement is executed when ULTRACE is set to 0, the request is cancelled.

The CCATEMP wrap-around trace table is a user-specific trace table that consists of a set of CCATEMP pages up to a maximum specified by the ULTRACEP user parameter. If ULTRACEP pages are already in use when a TRACE statement is issued and output is being routed to the trace table (ULTRACE X'04' set), the trace data on the oldest page is discarded and the oldest page is re-used for the new trace data. The default value for ULTRACEP is 2.

The wrap-around trace table is dumped in SirFact dumps and can be viewed when examining the dump with the command:

D[DISPLAY] T[RACE][.{* | N}] where N specifies that the last N entries are to be displayed. A simple "D T" will display all trace entries and a "D T.20" will display the last 20.

LONG REQUEST dumps

SirFact now produces dumps when a request is cancelled as the result of a "M204.1332" message when the user is not prompted with a "DO YOU REALLY WANT TO CONTINUE" message.

Sirius Functions

The $functions presented in this chapter are new or have changed in version 6.2.

Character entity substitution enhancements

There is a new $function called $ENT which does character entity substitution, that is replaces characters that have special meaning to an HTML or XML processor with their character entity representation. For example, the "<" is represented as the "&lt;" character entity. A default character entity substitution table is provided which does the basic required character entity mappings for HTML and XML of "&" to "&amp;", "<" to "&lt;" and the double quote character to "&quot;". Another new $function, $ENT_TAB makes it possible to modify or examine the default or current character entity substitution table.

$ENT_PRINT is provided to control automatic character entity substitution of PRINT'ed data including data PRINT'ed via an HTML statement. $ENT_PRINT can set character entity substitution to "OFF" (the default), "ON" which causes all PRINT'ed data to undergo character entity substitution or "VAR" which causes only non-constant, that is non-literal and non-static variable data to undergo character entity substitution.

The HTML statement has also been enhanced to allow an ENT_PRINT ON, OFF or VAR parameter to control the effect of character entity substitution just over the scope of the HTML statement. Finally, three special characters have been defined that when they immediately follow the expression start character(s) in an HTML block they cause special processing for the printing of the expression results:

&	Perform character entity translation regardless of the current $ENT_PRINT setting and the ENT_PRINT setting on the HTML statement.
!	Don't perform character entity translation regardless of the current $ENT_PRINT setting and the ENT_PRINT setting on the HTML statement.
*	Don't print the results of expression.

So for example in

HTML <input type="text" name="foo" value="{&%FOO}"> END HTML %FOO would undergo character entity translation before being printed.

$FIELD_IMAGE and $FIELD_LISTI

Allow retrieval of multiple fields from a record in a single call using an image as a template for the fields to be retrieved. $FIELD_LISTI allows multiple occurrences of a repeating group to be retrieved to a $list, again using an image as a template for the fields to be retrieved.

$list size restrictions eased

The maximum size of a $list item has been increased from 4096 bytes to 6124. This maximum $list item size can now be retrieved with the $LIST_MAXIL function.

In addition, $lists have been enhanced to allow $lists to grow to a three-level tree structure rather than their former two-level limit. This means that the quantity of data that can be held in a $list has been increased from the former limit of about 4.6 megabytes of data to about 3.5 gigabytes (billions of bytes) of data.

$LISTNEWI and $LISTNEWAI

Combine the functionality of $LISTNEW and $LISTIMG or $LISTNEWA and $LISTIMG into a single call. These functions make it possible to create a new $list or array of $lists and associate these $lists with an image in a single call.

$LIST_PRINT

Displays the contents of a $list to the current output target, probably the terminal. This function is useful in displaying $list contents when debugging code but might prove useful in contexts where data is stashed on a $list and then needs to be sent to a USE dataset or a web browser.

LONGSTRING datatype

It is now possible to declare a %variable as a type LONGSTRING. LONGSTRING's largely act as regular STRING's with a few exceptions;

• They can be longer than 255 bytes, in fact can be as long as 2**31-1 bytes long. The first 255 bytes of a LONGSTRING always resides in the server and any more resides in CCATEMP.
• A WITH operation involving a LONGSTRING either as an operand or the target will not truncate at 255 bytes but will produce a LONGSTRING result up to 2**31-1 bytes long.
• They will not be automatically truncated on assignment to a regular STRING variable the way Model 204 normally silently truncates values on assignment. An assignment from a LONGSTRING to STRING variable that requires truncation will cause a request cancellation. Similarly, the use of a LONGSTRING that is longer than 255 bytes as input to a $function or subroutine that takes regular STRING's as input will also result in request cancellation.
• They can't be passed as parameters to subroutines that have the parameter defined as STRING OUTPUT and STRING's cannot be passed as parameters to subroutines that have the parameter defined as LONGSTRING OUTPUT.

There are several new $functions that are specifically geared toward manipulating LONGSTRING's including

$LSTR_LEN	Returns length of a LONGSTRING.
$LSTR_SUBSTR	Returns a sub-string of a LONGSTRING.
$LSTR_LEFT	Returns the left-most N characters of a LONGSTRING padding on the right if the requested length is greater than the length of the input LONGSTRING.
$LSTR_RIGHT	Returns the right-most N characters of a LONGSTRING padding on the left if the requested length is greater than the length of the input LONGSTRING.
$LSTR_INDEX	Returns the position of a STRING inside a LONGSTRING or 0 if the STRING can't be found in the LONGSTRING.
$LSTR_UNBLANK	Removes leading, trailing and extra intermediate blanks from a LONGSTRING.

LONGSTRING's can be defined as arrays, common variables and as parameters in subroutine definitions. A few other $functions have been added to facilitate movement of data to/from LONGSTRING's:

$LISTINF_LSTR	Returns a $list item to a LONGSTRING.
$LISTADD_LSTR	Adds a LONGSTRING to a $list.
$LISTINS_LSTR	Inserts a LONGSTRING into a $list.
WEB_GET_COOKIE_LSTR	Returns the value of an HTTP cookie to a LONGSTRING.
WEB_SET_COOKIE_LSTR	Sets an HTTP cookie from a LONGSTRING.

LONGSTRING's are dumped in SirFact dumps and can be displayed at dump examination time exactly as one displays the value of any other %variable, namely with the "D %variable" command.

SEQ parameter for $SIRJGET

An option that requests that sequence numbers be placed in front of the journal entries formatted by $SIRJGET. This is useful for maintaining context and position when subsetting the formatted journal lines. SirScan has been enhanced to take advantage of this facility to improve subsetting and positioning associated with the ALL command.

$STRAND, $STROR and $STRXOR

String oriented logical bit manipulation functions. Allow AND'ing, OR'ing and exclusive OR'ing the bits in two strings. $STRXOR, in particular, can be useful as a low-grade two-way encryption technology since two-way encryption often simply involves the exclusive OR'ing of a string with an encryption mask.

Single line HTML/TEXT statement

The HTML/TEXT statement now has a DATA option that must be the last option on the HTML/TEXT statement and indicates that all text that follows the word DATA is to be treated as if it were inside an HTML block and that the HTML block is considered to end at the end of the logical line. This provides a single line HTML or TEXT statement capability that can be very useful as a PRINT statement alternative as in FOR %I FROM 1 TO 10 FOR %J FROM 1 TO 10 TEXT DATA {%I} + {%J} = {%I + %J} END FOR TEXT DATA Isn't this prettier than PRINT? END FOR

Return to top of page

SirAud Version 1.04

Return to top of page

Version 1.04 of SirAud, released in May 2002, provides support for the additional statistics and changed journal formats of Model 204 Version 5.1.

There are no major functional enhancements in this release.

Return to top of page

Sirius Mods Version 6.1

Return to top of page

Version 6.1 of the Sirius Mods was first released in July 2001, as a limited distribution interim release to provide stable support for the "PERF3" enhancements to Model 204. It became generally available in September of 2001. The major enhancements are summarized below. Please refer to the Sirius Mods Release Notes Version 6.1 for a more detailed explanation.

Janus SOAP (new product)

Version 6.1 of the Sirius Mods introduces Janus SOAP, the newest member of the Janus family of products. Janus SOAP provides User Language programmers with facilities for processing eXtensible Markup Language (XML) documents. Janus SOAP adds support for tree-structured data objects to User Language, introducing rudimentary Object Oriented (OO) programming concepts to Model 204.

A set of $functions provides an Application Programming Interface (API) for navigating the tree-structured objects. Functions are provided for transferring data between the tree-structured objects and simple User Language objects such as percent variables and images. For more information, please refer to the Janus Soap Reference Manual.

Sirius Performance Enhancements, Version 3 (new product)

Sirius Performance Enhancements, Version 3 is a collection of performance enhancements for Model 204 Version 4.2 that are the result of a joint development effort between Sirius and CCA. Although packaged as a Sirius product for use with Model 204 Version 4.2, the entire set of enhancements have been integrated with Model 204 Version 5.1. Each enhancement is separately activated by a parameter setting, as described below.

Reduced cost of searching GTBL (GTBLHASH>1)

The Model 204 global variable table consists of a single table that is scanned sequentially to locate a given variable. As the number of global variables increases, the scanning costs increase. It is not uncommon for up to 5% of the CPU consumed by an ONLINE to be spent scanning GTBL.

The GTBLHASH parameter causes that portion of GTBL used for storing global variables to be divided into GTBLHASH sections of equal size. A second system parameter, GTBLPCT indicates the initial percentage of GTBL to be allocated to the portion of GTBL used for global variables and subject to control by GTBLHASH. The default for GTBLHASH is 1, which deactivates the optimization. The default for GTBLPCT is 50 (for 50%).

In order to look up a name when GTBLHASH>1, a hash function is used to determine the correct section, then that section is sequentially scanned. This approach reduces the average number of GTBL entries that must be scanned by a factor of GTBLHASH. Also, the overhead of updating a value is reduced because only the entries in a bucket need to be moved to fill in holes made by deleted or updated values. Under TPNS testing a large customer saw an overall CPU saving of 4.3% with GTBLHASH set to 23.

Subscripted field references (PERFOPT X'01000000' bit)

Complex repeating group structures are quite common in Model 204 databases. Conventional wisdom has evolved the following code fragment as the best way to iterate over all occurrences of a repeating group, with this example having four fields in the group: O: FEO FOO %FOO = VALUE IN O %BAR = BAR(OCCURRENCE IN O) %SNA = SNA(OCCURRENCE IN O) %FU = FU(OCCURRENCE IN O) . . . . The FEO is optimized so that, except in certain special cases (unlocked record, updated record) FEO picks up where it left off in the record when searching for the next occurrence. Thus FEO does not have to repeatedly scan from the start of the record for each subsequent occurrence of FOO. However, extracting each occurrence of the other three fields (BAR, SNA, and FU) requires a scan from the beginning of the record, skipping over the occurrences already retrieved. This exponential behavior can cause field extraction to become a significant amount of the total CPU consumed by a Model 204 ONLINE, reaching 17% for one large customer.

The PERFOPT=X'01000000' optimization provides subscripted field references with with the same type of optimization as FEO. At compile time we detect a variable occurrence number reference to a field and allocate a special field position variable for that reference. At the time the field extraction is done for the first occurrence of a field we save the position in the record just as FEO saves its position. On subsequent extractions we use the previously saved position as a starting point if the occurrence number being requested is greater than the previous occurrence number retrieved and the position is still usable. One large customer saw a total CPU saving of 3.0% from this optimization.

String arguments to dollar functions (PERFOPT X'02000000' bit)

Model 204 uses a general purpose routine to resolve the values of arguments passed to dollar functions. As the types of variables supported by Model 204 have proliferated, the path length for this routine has grown. The PERFOPT=X'02000000' optimization improves the performance of passing arguments to dollar functions in two important cases - simple string percent variables and null strings or missing arguments. This optimizations saved about 2.5% of the overall CPU for one customer.

IDENTIFY IMAGE statement (PERFOPT X'04000000' bit)

This optimization eliminated a scan of NTBL that was performed whenever an IDENTIFY IMAGE statement was executed. For requests that use large amounts of NTBL, the savings can be significant. The CPU savings was about 0.7% for one large customer.

Dollar functions that return strings (PERFOPT X'08000000' bit)

This optimization reduces the instruction pathlength for dollar functions that return string values to string percent variables, by eliminating a generated assignment quad. One large site measured a 0.2% reduction in CPU usage and a 5% reduction in QTBL usage.

WITH clause, assignment and comparison statements (PERFOPT X'10000000' bit)

This enhancement builds upon the observations that drove the PERFOPT=X'02000000' enhancements. Optimized versions of the assignment, comparison and WITH quads were built to reduce their overhead in common simple cases (simple percent variable to percent variable movements, string to string comparisons, fixed to fixed assignment, etc.). In addition the pathlength for cases where comparisons resulted in a JUMP (for example an IF clause that evaluates to false) was reduced. These enhancements saved about 1.3% of the CPU for one large site.

Field extraction with unlocked records (PERFOPT X'20000000' bit)

This optimization allows Model 204 to save a position within a record even when the record is not locked. Without this optimization the Model 204 FEO statement and the PERFOPT=X'01000000' subscripted field extraction optimization must always scan from the beginning of a record for the N'th occurrence of a field if the record is not locked. This is required because a saved position could be rendered invalid as a result of updates to the record. The frequent use (and perhaps overuse) of FDWOL coupled with extraction of repeating groups causes performance degradation.

This optimization provides a highly efficient means for determining whether the contents of a specific record may have been changed while a position was held within the record. The concept is that when we would ordinarily de-optimize an FEO or subscripted field reference we do a quick check to see if anyone might have changed the record since we saved our position. If not, then even though we don't have the record locked we can use our saved position.

The algorithm used by this enhancement trades performance for accuracy, in that it might refuse to use a saved position that is safe, but the resulting simplicity keeps the cost to an acceptable level. Our experience has shown that the tradeoff of efficiency and accuracy works very well, one large customer saw a 5.0% reduction in Model 204 with this enhancement.

Overhead of idle non-XDM CRAM threads (PERFOPT X'40000000' bit)

This enhancement reduces the overhead associated with idle IODEV=11 and IODEV=29 (BATCH2) threads, eliminating the performance penalty for over-allocating. The enhancement has no effect for users of the XDM CRAM or Fast/CRAM, since these versions already utilize a different technique for accomplishing the same result. A large Model 204 ONLINE measured savings of about 0.6% using this enhancement.

Limited Janus Web Server - Free Use of Janus Web Server

A new capability, Limited Janus Web Server, is available starting with this release. This allows you to write limited-scale Janus Web Server applications without requiring you to purchase a copy of Janus Web Server. You can implement low-volume applications using the power of the Web, even if your only Sirius Mods product is, for example, Fast/Backup or Fast/Reload.

The Limited Janus Web Server capability is provided as a no-charge update to all customers licensed for any Sirius Mods product (except for Janus Web Server). If a Model 204 load module is authorized for any Sirius Mods product other than Janus Web Server, that load module will be automatically enabled for Limited Janus Web Server for as long as at least one Sirius Mods product remains authorized. See the Overview chapter in the Sirius Mods Installation Guide for a list of all products which are in the Sirius Mods.

Limited Janus Web Server consists of the following:

• Authorization to use the $WEBxxx functions.
• If Janus TCP/IP Base is not otherwise authorized, authorization to use it with 3 threads.
• Authorization to define and use WEBSERV ports with up to 3 connections.
• Authorization to use SirScan to view the audit trail entries of any WEBSERV thread.
• Authorization for the HTML/TEXT statement and the SIREDIT and WEBAUDIT parameters.
• Customer support and maintenance for Limited Janus Web Server.

The limitations imposed in Limited Janus Web Server are as follows, relative to a full Janus Web Server license:

• At most 3 concurrent JANUS WEBSERV threads may be active.
• Janus Web Server authorizes many $functions beyond the $WEBxxx functions; the only $functions authorized by Limited Janus Web Server are the $WEBxxx ones.

Sirius Software will encourage and assist users among its customer base to develop applications that can be shared amongst Limited Janus Web Server and Janus Web Server customers. Of course, Sirius Software hopes that the functionality provided by Limited Janus Web Server convinces you to purchase full Janus Web Server and SirScan licenses.

All products

HTML or TEXT block

The HTML and TEXT User Language statements are now available to users of the Fast/Unload User Language Interface, Janus Sockets, or of Limited Janus Web Server. This is in addition to the previous authorization, which made these statements available to customers who own Janus Web Server or the Sirius Functions.

Fast/Unload User Language Interface

The following features are new or changed in the Fast/Unload User Language Interface:

FNVMASK

The current value of the FNVMASK parameter is now automatically communicated to Fast/Unload when it is invoked by the Fast/Unload User Language Interface. If FNVMASK is non-zero, then either Fast/Unload version 4.1 or later, or version 4.0 with ZAP4022 applied, must be used for the unload.

Sirius Functions

The $functions presented in this chapter are new or have changed in version 6.1.

$BASE64_DECODE & $BASE64_ENCODE

The $BASE64_DECODE function converts a byte string from a base 64 encoding to the decoded byte string. The $BASE64_ENCODE function converts a byte string into its base 64 encoding.

These $functions were previously introduced by ZAP6042.

$COMMAND, $COMMBG & $COMMNDL available for Janus Sockets & Janus Web Server

The $COMMAND, $COMMBG, and $COMMNDL functions are now available to customers who own either Janus Sockets or Janus Web Server. This is in addition to the previous authorization, which made these $functions available to customers who own the Sirius Functions.

$UNBINDW

$UNBINDW allows semaphores bound by $BIND to be unboud. The difference between $UNBIND and $UNBINDW is that $UNBINDW allows wildcard characters in the semaphore name so that multiple semaphores can be unbound in a single call.

$UNSPACE

$UNSPACE normalizes a string by removing leading and trailing "space" characters and collapsing other sequences of "unquoted" spaces to single spaces. Normalization can also "undouble" quoted quote characters.

Janus TCP/IP Base

The features presented in this chapter are new or have changed in version 6.1.

VSE Support

Janus TCP/IP Base is now supported for users of VSE/ESA 2.3 and later via Connectivity Systems Inc. TCP/IP V1.4 and later. This provides VSE support for Janus Web Server, Janus Network Security, Janus Specialty Data Store, Janus Open Server, Janus Open Client and Janus Sockets.

Janus Web Server

The features presented in this chapter are new or have changed in version 6.1.

$WEB_END_SSLSES

Terminates an SSL session. This function is useful for Janus Network Security customers using client certificate based authentication. Terminating an SSL session with most browsers forces the end-user to provide a client certificate on subsequent connections to the server. This is important in allowing users with multiple certificates to switch certificates and in providing a true logout capability - without it, a timed out logical session would probably receive the client certificate from the timed out session and simply allow the login without any end-user interaction, making it appear as though there wasn't any session timeout at all.

Return to top of page

Sirius Mods Version 6.0

Return to top of page

Version 6.0 of the Sirius Mods, released in December 2000, adds many significant improvements to the Sirius product set. The major enhancements are summarized below. Please refer to the Sirius Mods Release Notes Version 6.0 for a more detailed explanation.

Janus Sockets (new product)

Janus Sockets, a new member of the Janus family of products, is available in version 6.0 of the Sirius Mods. This provides the basic connection over the Internet between Model 204 and a very wide range of other Internet applications.

The JANUS DEFINE command is enhanced to provide two new port types:

CLSOCK

This allows you to define a name that is used by User Language applications to create an "active" connection to a service running on some Internet host.

SRVSOCK

This allows you to associate a port number with a processing command (CMD parameter). When an application running on some Internet host requests a connection to that port number on the Model 204 Internet host, that command is invoked, with the connection established.

Either type of connection, CLSOCK or SRVSOCK, allows your User Language program to use the connection for sending and receiving data to the application running on the other Internet host. The interface is easy to use, with a flexible and convenient approach for establishing, managing, and ending the connection, and for dealing with errors which may occur.

A system manager provides the JANUS commands that describe the Janus Sockets connections that can be used; the connections are established and used in User Language programs with a set of $functions. Some noteworthy features are:

Translation

Translation between the EBCDIC character set and the character set expected by the other Internet host is handled without explicit manipulation by the User Language programmer. You can specify either translated (CHAR) and non-translated (BINARY) operations, and when CHAR is in effect, you can use the new Janus XTAB capabilities to specify the translation tables, if you need anything other than standard US ASCII.

Length- or separator-based receives

There are two receive $functions. One specifies the specific number of bytes to receive, and the other specifies a set of separator strings that end the next string to receive. This makes it easy to operate with various protocols that are well defined for Internet services, or to create your own protocols.

Sending strings or lines

You can optionally follow a transmitted string with a LINEND string (specified by its ASCII hex code), again making it easy to operate with various protocols.

Captured print

The flexibility and convenience of various print output in Model 204, including the new Sirius HTML statement, can be used to send lines over a connection.

Certificate support

You can use digital certificates to confirm the identity of the remote host on a Janus Sockets connection, and you can provide a digital certificate to a remote host, validating the identity of the Model 204 online. Certificate support uses the features of Janus Network Security.

Controlled access

With Janus Sockets, you can specify which local users and/or applications can access which remote Internet hosts and/or port numbers.

You can control which remote hosts (and/or users, which can be authenticated by a remote host providing a client certificate) use the local SRVSOCK services you provide to the Internet. You can also protect resources made available on a SRVSOCK port by the NEWSESCMD facility, which can perform a Model 204 LOGIN operation.

SSL encryption

You can use encrypted communication with Janus Sockets, using the features of Janus Network Security.

Error handling

You can establish a label in your User Language program to receive control when an error occurs, or you can test for error return codes from each $function invocation, or you can allow Janus Sockets to simply cancel the User Language request when a socket error condition occurs.

Socket manipulation

You can change a wide number of settings that apply to a connection, and you can obtain the current values of the settings.

Sirius-supplied applications

Since many of the Internet protocols are well-defined, Sirius Software will provide User Language source that you can use in your system. For example, a User Language subroutine is available which you can call to send an e-mail message directly to the Internet.

Janus TCP/IP Base

Many enhancements to the Janus TCP/IP Base product provide improved functionality to all of the other products in the Janus family.

Multiple commands on JANUS DEFINE

The CMD parameter on the JANUS DEFINE command now allows multiple commands to be specified.

Multiple files/groups on JANUS DEFINE

The OPEN parameter on the JANUS DEFINE command now allows multiple files or groups to be specified and each file or group can have the file open privileges specified.

Enhanced translation facilities

The JANUS LOADXT subcommand allows a pair of EBCDIC to ASCII and ASCII to EBCDIC tables to be loaded from Model 204 procedures or an operating system file and assigned a name. Tables loaded in this fashion can be referred to by the XTAB parameter on a JANUS DEFINE command. This facility supports an optional "entity" translation facility that can translate individual EBCDIC characters to special HTML "character entity references" upon output. For example, the character "<" could be translated to "&lt;" on output.

Enhanced Support for complex security schemes

A set of new parameters is supported for the JANUS DEFINE command when used to define a Janus Sockets server port or Janus Web port. These parameters allow a special set of file/group opens and command(s) to get processed before a new session is established. After a session is established, the standard CMD and OPEN parameters are invoked. It is intended that this special, "pre-login" environment would be used to create arbitrarily complex security mechanisms under the control of authorized User Language code. This could include the use of SSL client certificates, userid and password data entered on forms, header fields from a proxy server, or whatever else is deemed appropriate.

Enhanced monitoring of Janus threads

For certain types of Janus requests, there is quite a bit of activity on a thread before a user is actually logged on. With prior releases, these threads would not be visible to SirMon or the Model 204 MONITOR command. A new JANUS DEFINE parameter, PRELOGINUSER may be specified to indicate a user ID for threads associated with the Janus port that are in the "pre-login" state. In addition, all Janus threads will be visible to SirMon and MONITOR, even before they have been logged in. The TRACE keyword has replaced the DEBUG keyword and the data reported has been greatly enhanced. The JANUS LIMITS and JANUS TSTAT commands display information about thread usage, both at the system level and by individual Janus port. The benefits of the [NO]AUDTERM parameters of the JANUS DEFINE command have been extended to other types of Janus ports, in addition to Janus Web ports.

Janus Network Security

Support for SSL V3

Support has been added for Version 3 of the Secure Socket Layer. This includes support for client certificates and finer controls over the certifying authorities that are acceptable. The JANUS DEFINE command for an SSL port has been extended to allow the specification of maximum session age and output blocksize, providing significant performance improvement.

SSL client support

Client SSL connections are supported, both with Janus Open Client connections and Janus Sockets client applications. This includes the ability to manage and present client certificates to a remote server.

MP offload of RSA key exchange

The CPU-intensive RSA key exchange for SSL session establishment is now MP offloadable. If run under an MP version of Model 204, the MP subtasks will be used. Otherwise, separate subtasks will be attached and used for key exchange.

Janus Web Server

Extensive enhancements to Janus Web Server have made it even easier to write and support web applications with Model 204.

Janus Web Server Support for Legacy Rejuvenation

With Version 6.0 of the Sirius Mods, Janus Web Server delivers an unparalleled ability to adapt User Language 3270 applications to the web paradigm. A highly efficient mechanism operates at the Model 204 thread level to manage the persistence of application state data such as program variables, record lists, found sets, transaction backout logs, global variables and such. Differences between the application-directed navigation employed by 3270 applications and the user-directed navigation enabled by hypertext links are managed by a creative use of the hyper text transfer protocol only possible as a result of the integration of Janus Web Server and Model 204.

Any READ SCREEN statement executed by a User Language application is automatically converted into an HTML page, under the control of simple declarative rules. The resulting page includes a form with method="post" to a subtle variation on the URL that produced the form. The HTML for the page is buffered to CCATEMP and the current Model 204 thread is entered into a table conceptually organized by URL, user id and IP address. The end user's browser, which is still awaiting completion of its last URL (the one that executed the User Language program containing the READ SCREEN), is redirected to perform a get of the original URL. Janus Web Server intercepts the get (because it is for the URL/user id/IP address in the table) and returns the HTML previously saved in CCATEMP.

When the form is POSTed, Janus Web Server determines that the post is a result of a previous READ SCREEN (again using the table) and the indicated Model 204 thread is used to complete processing of the post. The value of each input form field is copied back into its corresponding Model 204 screen item and control is returned from the READ SCREEN.

This approach causes the browser to always see the HTML produced by READ SCREEN as the result of a "get" of the original URL. Thus, there is only one entry in the browser's history cache. The browser will only show the most recent interaction bewteen Model 204 and the user, just like a 3270. If the browser user loads another page and then uses the "back" button (Alt-"<-"), the browser will perform the get again and retrieve the last output HTML. This "vertical stacking" of browser interactions eliminates the confusion that results from other 3270 to HTML mapping schemes.

Unless directed otherwise, the HTML generated by Janus Web Server on behalf of a READ SCREEN statement will use JavaScript to set an initial cursor position when the page is displayed and to detect the current position of the cursor when the form is posted. This makes it possible to access essentially any existing Model 204-based 3270 application from a browser with no application changes, even if the application takes advantage of cursor position sensing.

The $WEB_FORM_DONE function provides User Language programs with access to the mechanisms for thread persistence and browser management that underly the Janus Web Server support for READ SCREEN. Additional supporting $functions enable the straightforward rejuvenation of complex User Language applications from 3270 applications to fully web-enabled browser applications. Complex multi-screen applications can be converted into HTML pages one screen at a time, with changes isolated to just those areas with READ SCREEN statements. Screens that are infrequently used can be left in 3270 form, reducing the cost of a web enablement effort. The following $functions are provided:

$WEB_FORM_DONE

The $WEB_FORM_DONE function combines management of the browser history cache with optional access to the Model 204 thread persistence feature. "Ordinary" Janus Web Server applications build up their HTML output into CCATEMP and then signal request comlpetion with a call to the $WEB_DONE function. This approach makes optimum use of network bandwidth and enables the browser to report download progress as a percentage of completion. The $WEB_FORM_DONE also indicates that all of the HTML for a request has been buffered into CCATEMP, but it does not directly send the output to the browser. The $WEB_FORM_DONE function is intended for use after an application has processed the data from a form that was sent with method="post". Instead of sending the buffered data stream to the browser as a response to the POST, $WEB_FORM_DONE sends a REDIRECT command instructing the browser to issue a GET request for the same URL that it just POSTed. That URL plus the current user ID and browser IP address are entered in a table maintained by Janus Web Server, along with a redirect wait timeout value. If the requested GET (i.e., for the indicated URL and from the specified IP address and user ID) does not arrive within the redirect timeout window, the buffered data stream is discarded and the table entry cleared. Otherwise, Janus Web Server responds to the GET with the data stream previously buffered in CCATEMP is transmitted to the browser.

By issuing the REDIRECT you prevent the browser from creating an extra history entry for the result of the POST. In addition to its obvious utility for emulating 3270-like behaviour, $WEB_FORM_DONE can be very useful for writing HTML form-based applications that need to redisplay a form, perhaps with an error message or acknowledgement. Without $WEB_FORM_DONE the browser would have the form as sent, followed by a page with the redisplayed form. The alternatives, such as pragma no-cache and setting an aggressive expiry date/time stamp can cause confusion to the end user.

In addition to responding to a POST request, $WEB_FORM_DONE can be used to cause a Model 204 thread to wait for another POST request of the same URL from the same browser session (user ID and IP address). This is accomplished by specifying a non-zero post wait time. This usage is intended to support the migration of User Language 3270 applications to HTML applications, while retaining persistent state information at the Model 204 thread level. Under this model, each interaction between the browser and Model 204 serves an HTML page containing another FORM, which POSTs back to the waiting thread. All of this browser interaction occurs under one URL, providing an intuitive and pleasing browser history cache appearance. Note that while this approach is easy to implement, it will require more Model 204 Janus threads than a state-less HTML implementation.

$WEB_FORM_ACTION and $WEB_FORM_ACTION_LEN

These functions can be used to determine the current URL. They are especially useful for filling in the URL on an action parameter of a <form> tag in HTML to be used in conjunction with $WEB_FORM_DONE. When the current URL is longer than 255 bytes, $WEB_FORM_ACTION_LEN provides a vehicle for dealing with the entire URL as a collection of less-than-255 byte components.

$SCREEN_CLEAR

The $SCREEN_CLEAR function clears the "tagged" and/or "modified" flags for all the items of a Model 204 SCREEN. This function is especially useful for providing HTML-based front ends for User Language programs that deal with Model 204 screens.

$SCREEN_MOD

The $SCREEN_MOD function sets the "modified" flag for a Model 204 SCREEN field. The only arguments allowed are screen items and screen item name variables that map to screen items. This function is especially useful for providing HTML-based front ends for User Language programs that deal with Model 204 screens.

The Janus Web Server legacy rejuvenation facility depends upon the ability to uniquely identify a browser session. The default mechanism is an internal "table" logically organized by URL, user id and client IP address. In order for a redirected browser session to successfully rendezvous with the output previously generated and to subsequently post the correct Model 204 thread, the identifying triplet must be stable and unique. There are some important cases where a client's IP address would be unsuitable for identifying a browser session. Use of a proxy server could cause all browsers to appear as the same IP address. A proxy farm might cause an individual browser to appear as several different IP addresses. An application server running several applications that use HTTP to access Model 204 might use a single IP address for several distinct end users.

The VARIPADDR port definition parameter instructs Janus Web Server to drop consideration of IP address from the rendezvous table. Thus, if the URL can be shared amongst users, then the combination of user id and IP address must be unique. For public URLs this presents the additional requirement that the URL must be unique, since all requests will be executed under the WEBUSER id. This can be accomplished by adding an ISINDEX query field that is unique for the session. Or the WEBCOOKID port definition parameter can be used to direct Janus Web Server to maintain a cookie for the purpose of identifying each browser session.

The FORMREDIRWAIT parameter may be specified on Janus Web port definitions, JANUS WEB ON rules, and in calls to the $WEB_FORM_DONE function. The parameter value is the number of seconds to wait for the appropriate browser get request after the Janus Web Server rejuvenation facility sends the redirect response.

The FORMPOSTWAIT parameter may be specified on Janus Web port definitions, JANUS WEB ON rules, and in calls to the $WEB_FORM_DONE function. The parameter value is the number of seconds to wait for the appropriate browser post of a form served in the response to a redirected get from the Janus Web Server rejuvenation facility.

HTML and TEXT statements

Web applications typically involve much structured formatting or scripting text interspersed with application data. Large blocks of mostly static text can now be placed inside an HTML/END HTML or TEXT/END TEXT block without quotes, providing a substantial improvement in readability and maintainability over the previous technique of User Language PRINT statements or $WEB_PROCSEND functions. Any Model 204 expression including simply %variable values or $function invocations can be placed inside an HTML block as long as it is enclosed inside the expression start and end characters which default to curly brackets ("{" and "}"). The following is an example of the use of the HTML statement:

HTML
<form method="POST" action="processform">
<br>
Last name: <input type="text"
            name="lname" value="{%LNAME}">
</form>
END HTML

Enhanced Janus debugging facilities

A powerful new debugging facility allows Janus Web requests to be selectively executed on specific non-SDAEMON threads, most likely 3270 threads where an interactive debugger could be used. A set of new JANUS WEB DEBUG rules is used to indicate which requests are to be scheduled on debugging threads, while a new JANUSDEBUG command causes a Model 204 thread to retrieve a browser request that is awaiting debug. Operating in conjunction they provide a facility for specific browser requests to execute in specific terminal-controlled threads.

JANUS WEB DEBUG rules

JANUS WEB DEBUG rules indicate which browser requests are to be executed on non-SDAEMON threads, presumably for interactive debugging. JANUS WEB DEBUG rules specify a URL, which can contain wildcards, as well as IPADDR or IPGROUP and USER or USGROUP keywords to further restrict debugging of the indicated URL(s) to requests from browsers with specific IP addresses or for specific users of protected URLs. In addition, a PUBLIC keyword indicates that a URL that does not require user login can also be executed on a debugging thread. There are also JANUS WEB NODEBUG rules to force normal SDAEMON scheduling for URLs that would otherwise be held for debugging.

A request that satisfies a JANUS WEB DEBUG rule (without satisfying a a JANUS WEB NODEBUG rule) will wait for a corresponding JANUSDEBUG command to be entered on an interactive thread. The request would then be executed on the same thread that issued the JANUSDEBUG command, allowing that user to run an interactive debugger.

JANUSDEBUG command

The JANUSDEBUG command retrieves a browser request previously suspended as a result of satisfying a JANUS WEB DEBUG rule and resumes execution of the request on the current user's thread. With proper setup, JANUSDEBUG can be used to run TEST SUBSYSTEM, TEST DEBUG, SSTEST, SoftSpy or any other testing subsystem. For example, if a SPYON command was issued before the JANUSDEBUG command, then SoftSpy could be used to debug the User Language processing the browser request. JANUSDEBUG will only allow debugging of protected (login required) requests running under the same userid as the debugging user or public (no login required) requests that are being debugged as a result of a JANUS WEB DEBUG rule that specified the PUBLIC keyword. The JANUSDEBUG command takes a few optional arguments:

IPADDR ipaddr

Indicates the IP address or addresses for which requests are to be debugged. The IP address can be a single IP address or can be an IP address followed by a subnet mask or a number of subnet bits.

PORT portname

Indicates the ports for which requests are to be debugged. Can contain wildcard characters.

URL url

Indicates the URL's to be debugged. Can contain wildcard characters.

Many customers are taking advantage of the integration of Janus Web Server with Model 204 to build bimodal applications that can be accessed from both browsers and 3270 terminals. Common techniques for determining the application mode include using $VIEW to examine IODEV and testing $WEB_PORT. In order to avoid confusion while debugging and to simplify coding, Version 6.0 of the Sirius Mods introduces the $WEB function. $WEB returns a 1 if running a Janus Web Server request and a 0 otherwise.

More flexible security

Janus Web Server now provides unequalled flexibility for managing the security of web-based transactions. This includes out of the box support for all the major industry standards as well as all the tools needed to accommodate the most complex requirements of business-to-business applications.

Support for Secure Sockets Layer (SSL) Version 3

Janus Network Security now supports SSL Version 3. The JANUS DEFINE command can include the SSLCLCERT parameter to indicate that a certificate will be requested from the client, or the SSLCLCERTR parameter to indicate that the client must provide a valid certificate. Any exception handler specified via a SSLNOCERTERR parameter on a relevant JANUS WEB ON, TYPE or REDIRECT rule is executed when a Janus Web port includes the SSLCLCERTR parameter, but the client does not provide a valid certificate. The $WEB_CERT_INFO and $WEB_CERT_LEVELS functions may be used to examine information from the client's certificate. The $WEB_PROTOCOL function may be used to determine the SSL protocol level for the current connection.

Support for application controlled security

Janus Web Server ports may now be configured so that a specified set of commands will be executed before a client creates a new session for accessing protected URLs. The additional JANUS DEFINE parameters are NEWSESOPEN, NEWSESCMD, NEWSESGUESTOK and NEWSESNOCLEARG. User Language programs executing on behalf of NEWSESCMD are authorized to use the $SIR_LOGIN function to login the client session. The NEWSESCMD will only be executed when the session is first established. The SESCOOKIE or SSLSES optimizations described later can then be used to avoid further login overhead.

One variant of NEWSESCMD could use a client certificate or header fields added by a proxy server to perform a "silent" login for the client. Alternatively the NEWSESCMD could serve HTML with a form that allows the client to enter a userid and password field, perhaps with the ability to change the password. Any header parm fields retrieved by a NEWSESCMD program are deleted from the Janus buffers to prevent accidental security exposures. Similarly, the NOTRACEFIELD port parameter can be used to prevent sensitive fields from being logged by a Janus trace. When the last NEWSESCMD defined for a port completes, if a user has not been logged in for the connection and the connection has not been terminated, Janus will issue a standard browser challenge for an id and password to be handled by the standard Model 204 security mechanisms.

Enhanced monitoring of "public" users

Most Model 204 shops have developed techniques for tracking individual users to assist help desks and for resource monitoring. Tools such as SirMon (or the MONITOR command) and SirScan are quite useful in 3270 environments where sessions are of relatively long duration and users login with distinct ids. Model 204 applications servicing "public" (non-protected) URLs are typically all executed under the user id specified by the WEBUSER parameter for the port definition. While SirScan can also display audit trail entries produced by clients with a given IP address, some end users might not know their IP address and proxy server farms can obscure that information.

The WEBLOGCOOKIE port definition parameter indicates the name of a cookie that contains a value to be used for the user id when public URLs are accessed. An application could set the cookie value to provide a meaningful name for the client. Then when the client accesses public URLs, the id from the cookie is used to perform a special type of login to Model 204. The indicated user is logged in with no privileges (UPRIV=X'00'), but the user id will appear on MONITOR commands, in the audit trail and in Janus Web log records. Any exception handler specified via a NOLOGCOOKIE parameter on a relevant JANUS WEB ON, TYPE or REDIRECT rule is executed when a Janus Web port includes the WEBLOGCOOKIE parameter, but the client does not provide a login cookie for a public URL.

Reduced authentication overhead

Version 6.0 of the Sirius Mods introduces features that can significantly reduce the cost of authenticating a user that repeatedly accesses PROTECTED URLs. An added benefit is better treatment of password changes, both those requested by the end user and those demanded by an external authorizer such as RACF. The basic concept is to authenticate the user just once per session and then remember the authentication in a secure fashion. Subsequent authentication requests can then retrieve the previously saved information and employ a highly efficient trusted login mechanism. This facility is controlled by four new port definition parameters and a $function:

SESCOOKIE parameter

Indicates the name of a cookie that will be used to save authentication information for the current session, once an identity has been established through either the standard HTTP challenge-response mechanism or by a $SIR_LOGIN issued during NEWSESCMD processing. Note that SESCOOKIE's are cryptographically designed to be virtually impossible to "fake".

SESCOOKIENSEC parameter

Indicates that the cookie specified by SESCOOKIE will not be sent to the browser as a "secure" cookie. This would make it possible with some browsers in certain situations to achieve single point login that is shared amongst multiple Janus Web Server ports, provided that they are all on the same machine.

SSLSES parameter

Indicates that SSL logical sessions will be used to remember authentication details for the browser session. Once a login has been performed for an SSL session, either through standard HTTP challenge-response mechanisms or through a $SIR_LOGIN issued during NEWSESCMD processing, Model 204 will remember the authenticated ID for the life of the SSL session.

SESTIMEOUT parameter

Indicates the maximum number of minutes of inactivity that may elapse before a logical login session being held either via SESCOOKIE or SSLSES will be terminated. After SESTIMEOUT minutes of inactivity, Janus Web Server will treat the session as a new session and perform the appropriate authentication for the port, which might or might not force the end-user to re-enter a password depending on the validation technique and possibly the browser.

$WEB_END_SES function

Terminates the logical session created using SSLSES or SESCOOKIE and can be useful in providing a user with a "logout" button or URL and can also be useful in allowing a user to switch to a different userid.

New exception handlers

Applications are provided with enhanced control over various error conditions through the creation of several new exception handling conditions can be specified in JANUS WEB ON, TYPE and REDIRECT rules:

NOLOGCOOKIE

Invoked when a port has the WEBLOGCOOKIE parameter set but a browser does not provide the login cookie for a public URL.

NOUSERID

Invoked when a user has requested a URL that requires a login but the user has not specified a userid yet.

OPENERR

Invoked when there is an error opening a file or group in the JANUS DEFINE command for the port or the JANUS WEB ON rule for the requested URL.

SSLNOCERTERR

Invoked when a user tries to connect to an SSL port defined with the SSLCERTR parameter but does not present a client certificate. This can be useful in presenting a user with the information that a client certificate is required and how such a certificate might be obtained.

SSLPROTOCOLERR

Invoked when a user tries to connect using an SSL protocol version that is not being allowed. Generally this would be used to respond to attempts to connect to Janus Web Server using SSL V2 when only SSL V3 is being allowed.

UNAUTHORIZED

Invoked when a user has logged in with a valid userid and password but is not authorized to access the requested URL.

Persistent Sirius $lists for stateless web transactions

The "saved record set" facility for Janus Web Server has been extended to allow the saving and passing of Sirius $lists. A request can use the $WEB_SAVE_LIST function to save a $list for later retrieval by a $WEB_REST_LIST function call. The list may only be retrieved by a request running under the same id as the user who saved it, within the appropriate timeout window. All of the controls for the saved record set feature (SRSDEFTO, SRSMAX, SRSMAXTO, and SRSMAXUS) also apply to saved $lists.

Enhanced character translation controls

Janus Web Server now uses the JANUS LOADXT command to load translate tables for accomplishing the translation from the EBCDIC and DBCS character representations on the mainframe to the ASCII and UNICODE character streams processed by browsers. In addition to the XTAB parameter on the JANUS DEFINE command, Janus Web Server supports an XTAB parameter on the JANUS WEB ON rule. This facility supports an optional "entity" translation facility that can translate individual EBCDIC characters to special HTML "character entity references" upon output. For example, the character "<" could be translated to "&lt;" on output. The functions $WEB_ENT_ON and $WEB_ENT_OFF are used to activate and deactivate entity translation. The SQUAREB parameter on the JANUS DEFINE command can be used to override the default EBCDIC characters used for square brackets.

SirFact

Comment-initialized globals

SirFact causes dummy string variables that begin with a backslash to have a default value of "*" rather than null. That is, a dummy string that begins with a "?&\" will be treated as an asterisk if the global is not set. This makes these types of dummy strings useful for commenting out debugging code. When the debugging code is to be activated, the global could simply be set to null.

Open records dumped in SirFact dumps

SirFact now dumps all "open" records at the time of a request cancellation. These are all records that are in currently active FOR EACH RECORD and FOR RECORD NUMBER loops. Field values can be displayed when scanning a SirFact dump by typing D F.fieldname where fieldname can be an explicit fieldname and occurrence number or can contain wildcard characters and occurrence number ranges. For example, D F.* would display all occurrences of all fields in all open records.

Found sets and LIST's dumped in SirFact dumps

SirFact now dumps the count of records in or on and a certain number of record numbers in or on a foundset or LIST. The number of record numbers dumped can be set with the SIRFACT RECNDUMP command and defaults to two which means that the first and last record number in a found set or LIST will be dumped. To display the count of records and RECNDUMP record numbers from a found set, type D RIN.label when scanning a SirFact dump. D RON.listname does the same thing for LISTs.

SIRFACT DUMP command enhancements

SirFact dumps can now be further controlled based on message number or the SNAP keyword on the SIRFACT DUMP command. For example: SIRFACT DUMP SUBSERR DUMP.+P.+T M204.0553 would send all dumps for subscript range errors to file SUBSERR and SIRFACT DUMP FACTSNAP DUMP.+P.+T SNAP would send all dumps resulting from SIRFACT SNAP commands to file FACTSNAP.

SIRFACT SNAP command

A system manager can now take a SirFact dump of another user by issuing the SIRFACT SNAP command with the user number or userid of the user for which the dump is to be taken. SIRFACT snaps can even be taken for non-evaluating threads though the snap will have precious little besides GTBL.

SirPro (Model 204 Editor Improvements)

Several enhancements to the Model 204 editor are available to customers authorized for the SirPro product. These changes are designed to improve the usefulness of the Model 204 editor, especially for mixed-case programming such as that found in procedures that generate or contain HTML. The improvements include:

• Support for wide-screen (RESET MODEL 5) editor sessions.
• Ability to automatically switch to "*LOWER" mode upon entry to the editor and restore prior setting upon exit.
• Optional case-insensitive locate.
• Support to automatically switch the LINEND character for procedures to carriage return (X'0D"), making it easier to edit text shared with stream-oriented systems.

SirSafe

Support for read-only files under MVS

SirSafe can now be configured to provide support for read-only files under OS/390 and MVS environments. By default this support is deactivated. In order to take advantage of read-only files, the system manager must explicitly activate MVSRO mode with the AUTHCTL command.

When SirSafe is active in MVSRO mode, additional checks are performed whenever a Model 204 database file is physically opened. For each dataset comprising the Model 204 database file, the external authorizer (RACF or ACF2) will be invoked to determine if the Model 204 job is running under a profile that allows write access. If so, the dataset will be opened for output, else the dataset will be opened for input.

If any of the datasets for a Model 204 database file are opened just for input, then the Model 204 database file will will be forced into read-only mode. Whatever privileges would have been granted to the opening user will be logically and'ed with X'8763' and the Model 204 message M204.0620 will be produced. If the first (or only) dataset for a Model 204 database file is opened just for input, then the Model 204 message M204.0590 will be produced and shared DASD enqueueing will be deactivated.

For most jobs the overhead of read-only support should be insignificant. That is because most commonly used Model 204 database files tend to remain physically open for the life of a run. However, certain kinds of unusual jobs could experience degradation. An example could be an IFAM host language job that performs many IFOPEN and IFCLOSE calls.

Reduction in "noise" logging

A Model 204 run with SirSafe active for file/group password access validation can log a large number of RACF or ACF2 access violations. In many cases this is a normal result of exploiting a strength of SirSafe, namely the ability for a single file or group password to confer different privileges to different users.

This is accomplished by having more than one password entry for a file or group with the same password value. When an end-user provides a password, CCASTAT is searched in the collating sequence of the index character for the appropriate file/group entries. If the password value in the entry matches the value entered by the user, then the external authorizer (RACF or ACF2) is used to verify that the end user has access to the CCASTAT entry. If access is denied, then the next CCASTAT entry with a matching password is checked. :P. Starting with release 6.0 of the Sirius Mods, the checks for access to CCASTAT entries will be performed with a NOLOG option if Model 204 is run with APF authorization. Thus, no RACF or ACF2 violations will be logged as a result of an attempted Model 204 file or group open. However, if a user enters a password that is not present in CCASTAT or if the user does not have access to a CCASTAT entry with the password, a standard Model 204 error message will be issued. If the SirSafe test facility is activated by an AUTHCTL TEST ON command, the positive and negative results of access checks for CCASTAT entries will be logged to the journal and in the VIEW ERRORS table by MSIR.0552, MSIR.0553, MSIR.0554 and MSIR.0557 messages.

SirScan

Combined selection criteria

SirScan now allows selection criteria to be combined with the "&" separator. For example, a selection criterion of "IODEV15&SCRATCHY IODEV7&ITCHY" would return journal records for all IODEV15's logged on as user "SCRATCHY" and IODEV7's logged on as user "ITCHY".

Improved userid support

SirScan uses a more sophisticated technique to track the associations between userid and Model 204 thread numbers, even when a user is no longer logged in. This makes userid based selection criteria in SirScan much more usable, especially with Janus Web Server, where the same thread may be reused by many users in a brief interval of time. The new SCANTIME system parameter may be used to fine tune the algorithm used to remember historical userid to thread associations.

New selection criteria

SirScan now allows displayed journal records to be limited by the IP address and Janus port name for Janus threads. This is very useful for debugging Janus applications.

Miscellaneous

All users installing the Sirius Mods will receive access to three new parameters:

SIRPRMPT

The SIRPRMPT user zero parameter may be used to direct Model 204 to insert the job name in the command-level input prompt (before the ">" symbol).

ERCNT

The current number of counting errors for a thread has been made a viewable and resetable parameter, ERCNT.

SCANTIME

The SCANTIME system parameter indicates the maximum number of seconds between SirScan "heartbeat" messages to the audit trail. These messages indicate the userid and, where appropriate, IP address and Janus port name associated with the thread.

In addition minor enhancements have been made to a variety of individual products:

Sirius Performance Enhancements V2

A powerful compile-time macro language simplifies User Language program packaging and maintenance. It is especially useful for managing dependencies within included subroutines. The MAXINCL user zero parameter specifies the maximum include nesting level for a run, allowing the default value of 5 to be extended up to 40.

SirMon

Support has been added for new statistics added by the External Call Facility and the Model 204 MQ Interface.

Sirius Functions

Many useful new functions have been added to the Sirius Function Library. The support for image mapping of $-lists has been completely fleshed out.

SirAud Version 1.02

Return to top of page

Version 1.02 of SirAud, released in April 2000, contains a significant rewrite of internal code, building a solid foundation for future enhancements. The major enhancements are summarized below. Please refer to the SirAud Release Notes Version 1.02 for a more detailed explanation.

SirAud now packaged for Web download

SirAud can now be downloaded from our web product distribution facility and is included on all product cartridges.

Consolidation of report files

SirAud may now be run with all reports produced to the single SYSPRINT file, under control of new parameters.

Date/time filtering for reports

SirAud reports may now be restricted to an optional date and time range, allowing reporting over specific intervals of interest.

Fast/Unload Version 4.0

Return to top of page

Version 4.0 of Fast/Unload, released in January 2000, adds many significant improvements; here is a list of the most significant ones:

• Performance: Multi-track I/O can now be used on non-cylinder aligned datasets; Hashing of extension buffer pool pages reduces overhead of large NEBUFF
• EXEC parameters: ABENDERR, to ABEND based on return code; NOLIST, to suppress listing of FUEL program
• ADDC: If value is MISSING, just ignore the operation
• DELETEC: If occurrence is MISSING, just ignore the operation
• LEAVE: Jump out of FOR/FROM/TO, REPEAT, or SELECT
• REPEAT: Loop until condition satisfied
• UNLOAD : To re-order fields in UAI
• #CONCAT_TRUNC: Concatenate strings, allowing truncation
• #DEBLANK, #STRIP: Remove leading/trailing blanks/pad characters from string or substring
• #DELWORD, #FIND, #WORD, #WORDS: Operate on string of blank-delimited words
• #LEFT, #PAD, #PADR, #RIGHT: Initial/final substring, with pad characters
• #LOWCASE, #TRANSLATE, #UPCASE: Character translation
• #ONEOF: See if string is in delimited list of strings
• #NUM2STR: Convert number to string with decimal point and specified number of integer and fraction digits
• #REVERSE: Get reverse of string
• Special variables: #OUTLEN, for output length and position; #OUTPOS, for output position
• Numeric use of MISSING value is zero, simplifying FUEL coding
• If the FUEL listing is suppressed and it contains a coding error, the line number in error is printed
• Errors previously reported as simply "syntax error" now print a more likely cause of error, namely, "unknown field"
• If common ABEND error occurs (e.g., no more space in output dataset), an explanation of the abend is printed
• Job I/O statistics
• Table B statistics (record lengths, extension records, etc.)
• New field statistics: average and totals for occurrence counts and field lengths, counts of records missing field, complete field definition information
• Handling of numeric operations in some cases (non-zero fraction part, more than 15 digits) changed to be consistent with User Language

For details on these and other improvements, read the Fast/Unload Release Notes Version 4.0.