Recent product releases:
Fast/Unload Version 4.4
Fast/Unload Version 4.4 was released in September, 2007.
The major enhancements are summarized below.
Please refer to the
Fast/Unload Release Notes Version 4.4 for more detailed information.
New Features
The principal purpose of the release of version 4.4 of Fast/Unload is
to support the FILEORG X'80' feature present in an alpha release of Model 204.
In addition, the OPEN command in a “batch” Fast/Unload job (that is, not
using the Fast/Unload User Language Interface) now allows specification of multiple filenames,
allowing the unload of an ad-hoc group of files.
OPEN statement for ad-hoc groups
Your FUEL program now may specify a group in the OPEN statement.
There are two alternatives to the OPEN statement:
- OPEN FILE filename
- This form indicates that a single file is to be opened, with the given name.
- OPEN filename1 [, filename2] ...
- This form, if there is more than one filename in the comma-separated
list, indicates that a group of files is to be opened, with DD names
filename1, filename2, etc.
With this new capability, you are no longer required to use the Fast/Unload User Language Interface
to unload a group.
#FILENAME special variable
The #FILENAME special variable is now available.
It obtains the name of the file currently being unloaded.
Sirius Mods Version 7.1
Version 7.1 of the Sirius Mods was released in July, 2007.
It supplanted Interim Release 7.0 that was not made available for all customers.
Features initially present in version 7.0 are summarized below along with features
introduced in version 7.1.
Please refer to the
Notes for Sirius Mods Version 7.1 for more detailed information.
Supported Model 204 Versions
As of version 7.1, Sirius Mods supports only Model 204 version V6R1.
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
The X'02' bit in the SIRPRMPT parameter will cause the
name of the job step to be added to the Model 204 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 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
The Janus Debugger is a tool designed for software developers who create and maintain Janus Web Server
applications.
The Sirius Debugger is designed to debug classical screen-based 3270 applications as well as
BATCH2 applications.
Though the two debuggers use different thread types on the host, they can run
concurrently, and they both use the same Windows-based GUI client.
For more information about the debuggers, see the
Janus/Sirius Debugger User's Guide.
Many of the features described below were introduced with Sirius Mods interim release 7.0, while others
were introduced with release 7.1 of the Sirius Mods.
Assembler language replaces User Language
In order to hasten initial delivery, the Model 204 (server-side) support for
the debuggers was originally provided by User Language programs in conjunction with Janus
Sockets and a special set of dollar functions.
This User Language code has been converted to assembler and integrated within the
Sirius Mods as of Version 7.0, with the following implications:
- 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.
- The maximum number of breakpoints per request increased from 40 to 1000.
New mappable commands for Client GUI
The debugger Client GUI allows the end user to customize the assignment of commands for
common functions to buttons and hot keys.
The following new GUI commands are delivered with Version 7.1 of the Sirius Mods:
- 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 DEBUG OFF command.
Improved GUI display of variables
The client GUI has been enhanced on a more frequent release schedule than the Sirius Mods.
While some GUI enhancements are independent of the Sirius Mods version, the following
enhancements are delivered with Version 7.1 of the Sirius Mods:
- 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 Debugger Client.
Enhancements to SIRIUS DEBUG command
Invocation of the Sirius Debugger has been simplified.
Two new User 0 parameters may be used to set system-wide default values for two
operands required by the SIRIUS DEBUG ON command.
Additional commands allow debugging to be temporarily suspended and later resumed.
DebuggerTools DebugOff method
A new DebuggerTools method, DebugOff, provides a procedural way for a User Language
request to terminate debugging for a session.
Janus Sockets
HttpRequest class Get method can send content
Prior to version 7.1 of the Sirius Mods, certain “post-oriented” actions were
not allowed with an HTTP Get, resulting in request cancellation:
- 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
The following sections describe changes to the Janus SOAP ULI
since version 6.9 of the Sirius Mods.
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:
value
Each value declared by a Value declaration becomes one of the values
of the enumeration.
No values are allowed in the Private or Shared blocks.
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
Enumeration classes can also contain methods that operate on
or are related to the enumeration values.
Enumeration methods can be applied to enumeration values as well as
enumeration variables.
This is one case, however, where the enumeration value must
be qualified with the class name, because it appears in a context where
the class cannot be determined otherwise:
print %(shape):rhombus:sides
And, as with objects, an enumeration method could be applied to the output
of another method that returns an enumeration value.
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:
%myAim is boolean initial(true)
Such a clause can also be placed on variables in a class Public, Private, or
Shared block.
As with other variable types, an Initial clause in a Public or Private block
sets the initial value for the variable when the containing object is
instantiated.
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:
function getRecord(%key is string len 10, -
%ls is enumeration lockstrength default(share)) -
is object record in file foo
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:
class resource
public
function newFromUrl(%url is string len 255) -
is object resource
end public
function newFromUrl(%url is string len 255) -
is object resource
%return is object resource
print 'In the factory'
%return = new
end function
end class
%res is object resource
%res = %res:newFromUrl('http://nfl.com/score')
Such functions are often called factory methods or virtual constructors.
As the example illustrates, two things distinguish factory methods from constructors:
- 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:
%res is object resource
%res = newFromUrl('http://nfl.com/score')
Similarly, if a method called Send in class Coworker took a resource
object as an input parameter, the NewFromUrl virtual constructor could
also be used as follows:
%sufjan is object coworker
%sufjan:send(newFromUrl('http://asthmatickitty.com'))
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:
If GRPFLD1 Is Defined Then Add GRPFLD1 = %val
End If
If GRPFLD2 Is Visible Then Delete GRPFLD2
End If
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 [Not] Defined
fld Is [Not] Visible
Where:
- 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:
%rc = %sl:Print([NumWidth=] itemnumlen,
[LenWidth=] itemlenlen,
[Start=] firstitem,
[MaxItems=] maxitems)
where all the parameters are optional.
For example, to display the contents of a StringList with 6 bytes to be used for
the column containing the item width, and limiting the display to 20 items, one
can use positional parameters:
%list:print(,6,,20)
As of Sirius Mods version 7.0, one can do the same thing with named parameters:
%list:print(lenWidth=6, maxItems=20)
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 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
This method is designed to work with Unix-style diff formatted
text lines that are stored in StringLists.
A diff utility creates a report (a “patch file”) of the
lines that differ between two “files,” a base file
and an updated version of
the base file: that is, patch = diff(base, updated).
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
against the daemon object:
%pantalaimon is object daemon
%pantalaimon:runAsynchronously(%commands)
%pantalaimon:waitAsynchronous.
Even if a daemon thread running asynchronously has completed processing its
commands, a WaitAsynchronous method must be issued against the
daemon object before further commands can be sent to the daemon.
Most methods applied to a daemon object that is running asynchronously will
result in request cancellation.
Once the daemon that had been running asynchronously has be resynched with the
master thread via WaitAsynchronous, the master thread can treat it just as any
other daemon thread and issue further Open, Run, RunAsynchronous, RunIndependently
or other methods against the daemon.
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:
class fooRecords extends recordset in file foobar
It is not possible to generically extend any file classes.
For example, the following is not allowed:
class myRecordSet extends recordset
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”
A new value, NoRecord has been added to the CursorState enumeration.
This value corresponds to the state where the cursor had a valid position identifying a record
in a RecordSet, but a subsequent operation (RecordSet Clear or RemoveRecord method) removed the
record identified by the cursor from the underlying RecordSet.
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:
%doc:SelectionNamespace('xxpref') = ''
caused the string xxpref to no longer be usable as a prefix in
an XPath expression.
This was sensible, since the XPath recommendation specifies that a prefix
used in an XPath expression must be associated with the URI of a namespace,
and the null string is not a valid URI.
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:
* %uri has null string or desired node's namespace URI:
If %uri EQ '' Then
%node = %inpNode:SelectSingleNode('infoChild')
Else
%doc:SelectionNamespace('inf') = %uri.
%node = %inpNode:SelectSingleNode('inf:infoChild')
End If
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 that are not in a namespace.
Now the above code can simply be written as:
%doc:SelectionNamespace('inf') = %uri
%node = %inpNode:SelectSingleNode('inf:infoChild')
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.
strLis = nr:XPathNodeID([selection_XP])
This returns, as the first item of the result Stringlist, an absolute
XPath expression which identifies the node selected by the argument.
If this returned XPath expression contains no prefixes, the Stringlist
contains only that one item and no further explanation is required.
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:
LinefeedNoTrailingTabs
This option can be used with any of the 3 “Wsp*” options, including the
default (WspNewline).
The result is that if any Text node contains an initial linefeed followed by any number of tabs
and nothing else, “before” any of the “Wsp*” handling, then the value
of that Text node will be a single linefeed character.
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:
%nlis = %nod1:SelectNodes('order[@date > "2007-01-01"]')
The support of comparisons has been extended in version 7.0,
allowing comparisons to numeric literals (which are unquoted);
for example:
%nlis = %nod:SelectNodes('order[item@price > 99.99]')
For detailed information on the new numeric comparisons and examples, please
refer ro the Janus SOAP Reference Manual.
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 users might experience degraded response time.
This could be especially noticeable 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:
%pos = %(XmlDoc):InvalidCharacterPosition(string)
It checks the characters in the string argument and returns 0 if they are all
valid as characters to be used as the value of an Element or Attribute node;
a non-zero return indicates the position of the first invalid character.
The invalid characters of an Element or Attribute node are the
“control characters.”
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
The SIRFACT DISPLAY command output now includes a comment that reports the number of
SirFact dumps taken since the Model 204 online initialization.
The comment is on the line that follows the SIRFACT MAXDUMP line.
For example:
SIRFACT DISPLAY MAXDUMP
SIRFACT MAXDUMP TOTAL 20
* 11 Number of dumps taken
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.
Sirius Mods Version 7.0
Version 7.0 of the Sirius Mods was released in February, 2007.
Version 7.0 was an Interim Release that was not made available for all customers.
Its enhancements are included in Version 7.1 of the Mods, and they are
documented in the
Notes for Sirius Mods Version 7.1, as well as the
Notes for Sirius Mods Version 7.0.
The release is no longer available.
UL/SPF Version 6.9
UL/SPF Version 6.9 was released in January, 2007.
The major enhancements are summarized below.
Please refer to the
UL/SPF Release 6.9 Notes for more detailed information.
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.
Sirius Mods Version 6.9
Version 6.9 of the Sirius Mods was released in October, 2006.
The major enhancements are summarized below.
Please refer to the
Notes for Sirius Mods Version 6.9 for more detailed information.
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
Several new debugger features are available when the latest GUI build is used with
Version 6.9 and higher of the Sirius Mods:
- 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
The Object-Oriented User Language extensions provide by the Janus SOAP ULI have
been extended in several significant ways.
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:
%pos = xdocQual:InvalidCharacterPosition(string)
checks the characters in the string argument and returns 0 if they are all
valid as characters to be used as the value of an Element or Attribute node,
or returns the position of the first invalid character otherwise.
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
$Bind now has a second parameter that indicates the number of milliseconds
to wait for the resource name being bound, if it is not immediately available.
This allows $bind to be used to control access to resources that are held
for relatively short periods of time, so shouldn't require user intervention
to resolve the conflicts.
For example, the following program binds the resource called 'BURNS', waiting up
to 10 seconds (10,000 milliseconds) for the resource to become available.
b
%rc = $bind('BURNS', 10000)
end
$RegexMatch: Whether string matches regex
This function determines whether a given pattern (regular expression,
or “regex”) matches within a given string according to the “rules” of
regular expression matching.
$RegexReplace: Replace matching strings
This function searches a given string for matches of a regular expression, and it
replaces found matches with or according to a specified replacement string.
The function stops after the first match and replace, or
it can continue searching and replacing until no more matches are found.
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
Previously, some invalid forms of end tag were accepted during XML deserialization.
For example, the following was accepted:
%doc:LoadXml('<t></t foo="bar>')
Such invalid end tags are no longer accepted.
Accept UTF-16 input in Xml* deserialization methods
Previously, most UTF-16 inputs were not allowed during XML deserialization (for
example, the LoadXml method).
UTF-16 input is now accepted.
SirTune Version 1.6
SirTune Version 1.6 was released in October, 2006.
The major enhancements are summarized below.
Please refer to the SirTune Release Notes V1.6
for more detailed information on the changes in this release, and
SirTune Reference Manual for
installation and usage details.
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:
//ONLINE EXEC PGM=SIRTUNE,...
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:
//ONLINE EXEC PGM=ONLINE,...
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.
Fast/Unload Version 4.3
Fast/Unload Version 4.3 was released in May, 2006.
The major enhancements are summarized below.
Please refer to the
Fast/Unload Release Notes Version 4.3 for more detailed information.
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
Previously, in unusual circumstances, certain kinds of updates to a file being unloaded by
the Sirius Mods $Funload function can fail to be reflected in the unloaded file.
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.
UL/SPF Version 6.8
UL/SPF Version 6.8 was released in March, 2006.
The major enhancements are summarized below.
Please refer to the
UL/SPF Release 6.8 Notes for more detailed information.
Simplified Product Packaging
As of Version 6.8, all UL/SPF components are distributed
in a single file named SIRIUS.
This change simplifies distribution and maintenance of the UL/SPF product line,
and it allows all the Sirius products to share common routines.
Besides a simpler installation and
update process, UL/SPF gains a more consistent interface:
- 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 Version 6.8 has many changes from the previous release, including:
- 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.
Sirius Mods Version 6.8
Version 6.8 of the Sirius Mods was released in November, 2005.
The major enhancements are summarized below.
Please refer to the
Notes for Sirius Mods Version 6.8 for more detailed information.
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
The LDAP Helper can now accommodate as much returned data as an LDAP server
sends.
Formerly, an approximately 1300-byte limit was enforced on each LDAP request.
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
The following sections describe changes in the
Janus SOAP ULI in this release.
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
The This keyword can be used to indicate the current class for
shared member references inside the class.
For example, in the following, the word This inside parentheses
means the current class, that is, class Foo:
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
The New constructor for Daemon objects has a new, boolean, named parameter called
Transactional:
%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.
The meaning of the ErrRet option for Validate is similar to its
meaning for LoadXml: it indicates that Validate should
return (with return code -100 or +n) even if given an
invalid schema document.
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 JANUS NAMESERVER command can be issued at any time, so the name server
lookup behavior of Janus Sockets can be dynamically changed for extraordinary
situations such as name server crashes, name server reconfigurations,
wholesale IP address changes on the local network, and so on.
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
These two $functions provide longstring capable ASCII-to-EBCDIC and
EBCDIC-to-ASCII translation functions.
That is, they can take a longstring input and produce a longstring output.
Both of these functions take a single string argument and produce a string result.
$a2e and $e2a use the “standard” ASCII-to-EBCDIC and EBCDIC-to-ASCII
translation tables provided by Sirius, and they provide no mechanism for
overriding these tables.
$lstr_base64_encode and $lstr_base64_decode
These two $functions provide identical functionality to the $base64_encode and
$base64_decode functions, except that the new $functions are longstring capable.
That is, they can take a longstring input and produce a longstring output.
$lstr_c2x and $lstr_x2c
These two $functions provide identical functionality to the $c2x and
$x2c functions, except the new $functions are longstring capable.
That is, they can take a longstring input and produce a longstring output.
$daemonMasterNumber and $daemonParentNumber
Two new sdaemon thread $functions, $daemonMasterNumber and $daemonParentNumber,
are introduced:
- 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.
SirTune Version 1.5
SirTune Version 1.5 was released in October, 2005.
The major enhancements are summarized below.
Please refer to the
SirTune Release Notes Version 1.5 for more detailed information.
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 SI