m204wiki - User contributions [en]

Intrinsic classes

2011-01-07T14:15:42Z

Jeff: grammer

See also:
*[[List of intrinsic Float methods]]
*[[List of intrinsic String methods]]
*[[List of intrinsic Unicode methods]]
===Definition of Intrinsic classes===
In “pure” [http://en.wikipedia.org/wiki/Object-oriented_programming object-oriented languages], all datatypes are objects, that is, all datatypes are
extension classes of some base object class. This means that even things that one
might not immediately think of as objects, such as character strings or numbers, are, in
fact, considered to be objects.
There are two aspects to the assertion that strings or numbers are objects:
*They are internally managed in exactly the same was as any other objects. That is, a string or numeric variable is actually a reference to an object that contains the string or numeric value, rather than itself directly containing the string or numeric value.
*They are syntactically identical to other objects. That is, the syntax for manipulating strings or numbers is the same as the syntax for manipulating other objects. More specifically, methods are applied to strings or numbers using the exact same syntax as when methods are applied to other objects.
Since the first aspect is concerned with the internal management of strings or numbers,
it is largely irrelevant from the perspective of a programmer using a “pure” object-
oriented language. In fact, many languages that profess to be “pure” actually “cheat,”
internally, and they special-case string and numeric data. They do so because string
and numeric data is so important, and so heavily used in all programming languages,
that insisting on not treating it specially (internally) is pedantry that has a cost in
performance. To see why, consider a statement that adds two numbers together (the
language for the example is, of course, User Language):
%x is float
%y is float
...
%x = %y + 13
Insisting that numbers are no different from any other object means that this statement
must get the value referenced by %y, add it to the number referenced by the literal “13”,
create a new Float instance and set %x to reference that new instance. Clearly, this
would be less efficient than taking the number in %y, adding 13 to it and setting %x to
the result. Fortunately, the way this is actually done is purely an under-the-covers
implementation issue, so one can always pretend that “pure” object-oriented processing
is being used.
This is so because numbers and strings are an example of a special class of objects
called immutable objects. Immutable objects, as the name suggests, cannot be
changed once they are created. To illustrate the difference between immutable objects
and mutable objects, consider two variables:
%count is float
%account is object bankAccount
If %account were set to a new object instance, it would not be surprising if, after it's set,
the object changed. For example, it wouldn't be surprising if the account balance for
%account changed, even if the change was done via a different variable:
print %account:balance
%myAccount = %account
%myAccount:addToBalance(23)
print %account:balance
In this example, it is expected that the balance displayed in the second Print statement
will be 23 greater than that displayed by the first.
On the other hand, given the following:
print %count
%myCount = %count
%myCount:addToValue(23)
print %count
It would be surprising for some operation on %myCount to have changed the value in
%count. In general, for variables that contain numeric or string values, one would only
expect the value to change when a new value is assigned to it. In fact, one would not
expect to see methods like AddToValue that modify the method object for a numeric
datatype.
More typical for a numeric datatype would be a method that manipulates the value and
produces a new value (object):
%myCount = %myCount:addToValue(23)
Although even pure object-oriented languages have special syntax for the common
operation of addition:
%myCount = %myCount + 23
Absence of methods that modify a value is what make a class immutable, and in “pure”
object-oriented languages, basic string and numeric datatypes are always immutable.
==Intrinsic methods in User Language==
User Language is a legacy programming language for which object-oriented capabilities
are a relatively recent addition. So, one might expect that strings and numbers are not
maintained internally as objects, since their existence pre-dates objects. This is in fact
the case, though as was shown, this is largely irrelevant from a User Language
programmer's perspective, And even if object-oriented capabilities were present in User
Language from its inception, strings and numbers might have been special-cased for
efficiency anyway.

<div id="intrins_classes">The intrinsic classes are:</div>
<dl>
<dt>Float
<dd>See the [[:Category:Intrinsic Float methods|Float methods]]
<dt>String
<dd>See the [[:Category:Intrinsic String methods|String methods]]
<dt>Unicode
<dd>See the [[:Category:Intrinsic Unicode methods|Unicode methods]]
</dl>

==The benefits of object-oriented syntax in User Language==
Beyond the internal representation of strings and numbers, a distinction between User
Language and pure object-oriented languages was that the object:method syntax
was not used to manipulate strings and numbers; instead, strings and numbers were
manipulated via $functions. Sirius Mods 7.2 changed this to allow the object:method
syntax against string and numeric variables and constants.
The following code fragment illustrates how the same operation can be accomplished via
traditional $functions and via object-oriented syntax:
%name is string len 32
...
print $len(%name)
print %name:length
While this might not seem very significant, it provides considerable value:
*It allows User Language to be used as a “pure” object-oriented language. This might be especially appealing to programmers who were trained in a pure object-oriented language.
*It provides the benefit that expressions can generally be read in the natural left-to-right manner rather than the inside-to-outside manner required to understand an expression coded with $functions.
*It provides capabilities to methods that operate on strings or numbers that are not available with $functions. These include support for named parameters and the ability to take objects as input parameters and to produce objects as results. While it would have been possible to extend $functions to have this same functionality (much as Sirius Mods provided callable $function support), it makes more sense to provide it using true object-oriented syntax. Given that this has now been done, it is unlikely that these capabilities will ever be added to $functions.
==Two generic intrinsic classes: string and numeric==
User Language traditionally allowed declarations of many different datatypes. These
included Strings of a specified length with a possible DP value, Fixed numerics (also
with a possible DP), and Float numerics. In addition, Sirius Mods provided support for
Longstring datatypes. And images provide support for a variety of additional datatypes,
including packed and zoned formats. Essentially, however, there are two categories of
datatypes in User Language: string and numeric. In User Language one can easily
assign values from one datatype to another, even between numeric and string types.
This is intuitive and useful. Typically, in the “real world” one doesn't distinguish between
the string representation of a number and its numeric value used for calculation.
Similarly, except for performance purposes and, perhaps, value limits, one is typically
not concerned about how a value is stored internally.

This is not the case in some “pure” object-oriented languages where the paradigm of
strong-datatyping is extended to numeric and string datatypes. This means that if one
wants to display the value of a numeric variable, one must explicitly convert it to a string
(since what one displays is a string). Similarly, if one wishes to do a calculation using a
value in a string (perhaps read from an external data source), one must explicitly convert
the string to a number. It is asserted here that strong-datatyping for strings and numbers
is a mistake, allowing some vision of purity to prevent programmers from doing
something completely natural (treating numbers as strings, and strings as numbers) and
something that is done hundreds of times in any program of any size. This view is
reinforced by the fact that the general industry trend is away from strong-datatyping for
strings and numbers and toward implicit conversion between these types.

It is worth pointing out, however, that loose-datatyping between strings and numbers
does not imply loose-datatyping between strings and numbers and other classes. That
is, there are generally no implicit conversions of strings or numbers to or from non-string,
non-numeric objects.

Because loose-datatyping and the existing User Language datatypes work quite well in
facilitating rapid development of reasonably tight and efficient code, the Janus SOAP
ULI support for methods against string and numeric types does not add any new
datatypes to User Language. And, because of loose-datatyping, the numeric and string
methods can be applied to any of the standard User Language string and numeric
datatypes. Because they apply to these intrinsic User Language datatypes, these
methods are called intrinsic methods.

Intrinsic methods can be further classified into these subsets:
<dl>
<dt>Float<dd>Methods that perform numeric manipulation on values in Model 204's Float format.
<dt>Fixed<dd>Methods that perform numeric manipulation on values in Model 204's Fixed format (with an assumed DP of 0).
<dt>String<dd>Methods that perform string manipulation, with Longstring capability assumed.
<dt>Unicode<dd>Methods that perform Unicode string string manipulation, return Unicode results, or are based on the Unicode tables.
</dl>

The Float intrinsic class can really be thought of as a generic numeric class, as it is a
convenient way of representing both integer and decimal data. This is different from
most other programming languages where a Float datatype suffers from inconvenient
behavior, especially for decimal numbers.

The Float class is so convenient that all numeric parameters to system methods and
$functions are treated as Float parameters. Also, because of the convenience of the
Float class, there are currently no methods in the Fixed class.
As such, the intrinsic methods can be thought of broadly as belonging to two intrinsic
classes: the Numeric class and the String class. These classes behave largely as if their
inputs were User Language Float and Longstring datatypes, respectively. That is, for all
intents and purposes, the following are true:
*Any non-Float values, including Unicode, are converted to Float values before being processed by a Numeric method. This includes the conversion of any non-numeric strings into 0 that occurs in other User Language contexts that take a numeric input.
*For the purposes of truncation and the With operation, all String method string inputs or outputs behave as longstrings.
==Strings and numbers as method objects==
The term “method object” (or “intrinsic method object”) is used for
the value or variable to which an intrinsic method is applied,
even though the value or variable isn't really an object.
This is justified because, as noted above, strings and numbers can be considered
immutable objects, regardless of their history or internal representation.

For example, in the following case,
<tt>%str</tt> is the intrinsic method object for the <tt>Length</tt> method:
<pre>
%str is string len 32
...
print %str:Length
</pre>

Intrinsic methods can be applied to constants, in addition to variables.
For example, the following assigns the length of the string literal
“Whatever” to %x:
<pre>
%x = 'Whatever':length
</pre>
Intrinsic methods can take the output from another method,
intrinsic or not, as its input.
For example, the following uses the Right method (which gets the
rightmost characters of a string) against the output of a Stringlist
Item method:
<pre>
%list is object stringlist
...
%value = %list:item(%i):right(8)
</pre>
Since it is unnecessary to explicitly specify the Item method for
a Stringlist, the above can also be written as:
<pre>
%list is object stringlist
...
%value = %list(%i):right(8)
</pre>
Intrinsic methods can also be applied to User Language Image and Screen items:
<pre>
image michigan
romulus is string len 32
...
end image
...
%value = %michigan:romulus:right(8)
</pre>
And Intrinsic methods can be applied to the output from a $function:
<pre>
%seconds = $time:right(2)
</pre>
Intrinsic methods can even be applied to the results of expressions:
<pre>
...
%value = (%tweedledum with %tweedledee):right(8)
</pre>

==Automatic “implicit” conversion of intrinsic values==
As with other methods, the colon that separates the intrinsic method object from the method
name can be optionally preceded or followed by spaces. This could be done to enhance
readability, or even to split a long line. The following four statements are all equivalent:
%value = %list:item(%i):right(8)
%value = %list: item(%i): right(8)
%value = %list :item(%i) :right(8)
%value = %list : item(%i) : -
right(8)
As with most other uses of intrinsic variables or values, if the method object is of a
different type than the datatype on which the method operates, the input value is
automatically converted into the target datatype. For example, the expression 7/3
clearly produces a numeric value, but the Left method operates on strings. So, in the
statement:
%i = (7/3):left(4)
the result of the division is converted into a string and then passed to Left, which
produces 2.33 as its result.
Because of this automatic conversion, the specific class (String, Float, Unicode) of an
intrinsic method cannot be determined from the datatype of its method object. This
means that the class must be determined only from the name of the method, which
means that method names must be unique among all intrinsic classes (that is, among
String, Float, and Unicode). For example, there may not be a Length method in both the
String and Float intrinsic classes. In the case of Length, the method is an intrinsic String
method, there is no comparable Float method, and UnicodeLength is the comparable
Unicode method.

'''Note:''' Because some EBCDIC characters are not translatable to Unicode, and vice
versa, automatic conversions involving Unicode values may cause request cancellation.
The explicit intrinsic conversion methods (like EbcdicToUnicode and EbcdicToAscii and
their counterparts UnicodeToEbcdic and AsciiToEbcdic), however, have a parameter (as
of Sirius Mods version 7.6) that lets you decode or encode untranslatable characters.

==Intrinsic method syntax: special cases==
User Language is a legacy programming language that supports some unusual syntax.
Some of this syntax causes problems for the use of intrinsic methods,
as is described for the following three cases:

===Intrinsic methods against database field names===
Field names have very loose naming rules, and names can contain colons
and spaces.
Because of this, a field name must be contained inside of parentheses
to be used as a method object.
For example, the field <tt>big fat greek field</tt>
is used as the input to the intrinsic [[Substring (String function)|Substring]] method:
<pre>
for each record in %recordset
...
%value = (big fat greek field):substring(2, 3)
...
end for
</pre>

===Intrinsic methods against percent variables and images that have the same name===
User Language allows one to declare images and percent variables with the same name
in the same scope.
That is, inside a method, you can declare an image called <tt>holland</tt>
and a %variable called <tt>%holland</tt>.
References to items in the image and to the percent variable both start
with <tt>%holland</tt>:
<pre>
image holland
...
factory is float
...
end image
...
%holland is string len 10
...
%a = %holland:factory
...
%a = %holland
</pre>
Historically, this has not been a problem because a percent variable
would never be followed by a colon.
However, with intrinsic methods, this is no longer the case.
If the Holland image contained an item called Length, it would
be impossible to tell whether <tt>%holland:length</tt> referred
to the Length item in the Holland image or the intrinsic Length
method applied to %holland.

Because of this ambiguity, intrinsic methods cannot be used against percent variables
without a blank between the variable name and the colon if there is an image
with the same name as the percent variable.
This is true regardless of whether or not there is an actual conflict between
the method name and an image item name.

So, using the above example, to apply the length method to
<tt>%holland</tt>, you must do one of the following:
<pre>
%a = %holland :length
%a = %holland : length
</pre>
Specifying <tt>%holland: length</tt> would not work.
A space after the variable name indicates that the reference
is ''not'' to the image because image item references do not allow any
blanks between the image name, colon, and image item name.

You can also simply wrap the variable name in parentheses:
<pre>
%a = (%holland):length
</pre>
Of course, the best solution is to avoid using the same name for images
and percent variables, as this is generally somewhat confusing,
anyway.

<div id="printtext"></div>
===Intrinsic methods in a Print, Audit, or Trace statement===
The User Language Print, Audit, and Trace statements all use somewhat unusual
syntax.
While initially these statements appear to operate
on expressions, just like an assignment, this is not really the case.
For example, the following statement gets a compilation error:
<pre>
print 3*4
</pre>

Because of this, one has to be careful using intrinsic methods in
a Print, Audit, or Trace statement. The general recommendation is to use PrinText,
AuditText, or TraceText, as described below.

There are several specific syntax problems with Print, Audit, and Trace:
<ul>
<li>Because blanks are treated specially in these statements, you
may not put a blank before the colon in an intrinsic method invocation.
That is, the following is '''''incorrect''''':
<pre>
print %x :length
</pre>
But the following two statements are allowed:
<pre>
print %x:length
print %x: length
</pre>
<li>String and literal constants are treated specially by these
statements, so you cannot issue methods against constants in a Print, Audit,
or Trace statement.
That is, the following are '''''incorrect''''':
<pre>
print 'Foobar':length
print 22:squareRoot
</pre>

<li>Although you might be tempted to use parentheses to get around some of
these issues, leading parentheses are '''not''' allowed
in a Print, Audit, or Trace statement token.
That is, the following is '''''incorrect''''':
<pre>
print (fieldname):length
</pre>
Coupled with the fact that applying intrinsic methods to fields
generally requires use of parentheses, this means that you '''cannot''' display
the result of an intrinsic method applied to a field with the Print,
Audit, and Trace methods.
</ul>

Fortunately, ''Sirius Mods'' version 7.2, the same version that introduced intrinsic
methods, also introduced the '''PrintText''', '''AuditText''',
and '''TraceText''' statements ([[Targeted Text statements]]).
These are direct analogs of Print, Audit, and Trace, respectively, but they use
a more consistent syntax.
Specifically, the newer statements treat everything as literal text, except
for that which is enclosed by curly braces (<tt>{ }</tt>),
which is treated as a standard User Language expression.
This means that the syntax used for variable parts of PrintText, AuditText,
and Tracetext statements is identical to the syntax allowed on the right
side of a variable assignment.

So, the following is valid:
<pre>
printText {3*4}
</pre>

And this is valid:
<pre>
printText {%x:length}
</pre>

These are valid statements:
<pre>
printText {'Foobar':length}
printText {22:squareRoot}
</pre>

And this is valid:
<pre>
printText {(fieldname):length}
</pre>

The [[Text and Html statements|Text statement]])
also provides functionality comparable to the PrintText,
AuditText, and TraceText statements, and it is especially useful for displaying
multiple lines of data.

So it is recommended that you discontinue the use of the Print, Audit, and
Trace statements in favor of PrintText, AuditText, and TraceText, as of ''Sirius Mods''
7.2.

[[Category:System classes]]
[[Category:Overviews]]

Getting started with OOP for User Language programmers

2010-09-05T21:24:01Z

Jeff: changed "functions are subroutines" to "functions and subroutines" in 1st para of "Object-oriented syntax"

==Background==
So, you're a [[User Language]] programmer and you're thinking about learning object-oriented programming:
*Rumor has it you can be a more effective programmer if you use object-oriented techniques.
*You're tired of feeling inferior to object-oriented programmers because they speak a language that you don't understand but sure as heck sounds impressive.
*You use [[Sirius Software]] products and Sirius has announced that all new User Language functionality will used object-oriented syntax.
*“Object-oriented” looks better on your resume than “User Language”.
*You just want to learn something new.
Unfortunately, most User Language programmers' first experience with object-oriented programming is painful and bewildering. Often it comes in the form of a VB.Net or Java class where the terminology flows freely from day one. Even worse:
*Classes often emphasize how one architects an object-oriented application. While this might be a logical way to build an application, it's a daunting way to learn a language — like trying to learn ballroom dancing before you know how to walk.
*Teachers (and books about object-oriented programming) are often enamored with the more sophisticated aspects of object-oriented programming languages, leaving novices in the dust as they're still struggling to digest the simpler concepts.
*Many object-oriented concepts are inter-related so it often requires plowing ahead without fully understanding the concepts one has already learned.
*There seems no way to put the concepts learned in a Java or VB.Net class to use in User Language. So, one is either forced to try to work on object-oriented programming in one's free time, or the concepts are quickly forgotten.
Fortunately, there '''is''' a way you can learn object-oriented programming, and apply the principles on-the-job from day one!

One requirement for this is that one work at a site where [[Janus SOAP User Language Interface]] is available or, at least some of the other Sirius “API” products such as Janus Web Server or Janus Sockets.

First, a quick word about terminology. In English-speaking, as opposed to American-speaking countries, objected-oriented is usually called object-orientated. More commonly, everyone just calls object-oriented programming “O-O”. But then, you knew that.

==Mixed case code==
So, let's get started. First, if you're going to do O-O programming you've got to write your code in mixed case. No, there is no technical reason O-O code in User Language must be in mixed case but:
*It's easy enough to do and, even if you don't use O-O, it makes your code look more modern.
*The industry consensus is that descriptive, often compound words, are better for variable, function, and subroutine names than terse non-descriptive names. For example, %itemNumber is better than %ITMN. While the latter is easier to type, the former is much easier to read. USing %ITEMNUMBER, on the other hand, clearly blunts some of that readability benefit. %itemNumber is written in what's called [http://en.wikipedia.org/wiki/CamelCase CamelCase].
*Sirius Software depends on CamelCase to make their function and subroutine names readable.

Fortunately, it's easy to start using mixed case code. Simply start typing your code in mixed case. What can possibly go wrong? If you're system manager has set everything up nicely for you, nothing. But, if not, you might hot a few glitches that are easy enough to fix:
*If you use the 204 editor and type in mixed case code and it gets converted to upper case when you hit enter, you have two options:
*#Set *LOWER at command level. This is a bit of a hassle because now Model 204 commands require holding the shift key down, because mixed case Model 204 command don't work.
*#Set the SIREDIT user parameter to X'33' (only the X'01' bit is required, but you may as well set some others) before entering the editor. This causes Model 204 to essentially switch to *LOWER mode before entering the editor. Request that your system manager do this for everyone by setting SIREDIT X'33' in CCAIN.

*If you get compilation errors when you type in mixed case UL, it means that the compiler is not running in case-independent mode. To fix this, you have three options:
*#Have your system manager set the X'01' bit in the system COMPOPT parameter. This must be done in CCAIN and is probably the best/simplest option.
*#Change the BEGIN or B statement at the start of the request you're working on to use mixed case, as in ''Begin'', ''begin'', or ''b''.
*#If you can't change the start of the program, add the line ''Sirius Case ToUpper'' (the case of the words, doesn't matter) to the start of the procedure you're working on.
The following is an example of a mixed case User Language program that starts with a mixed case ''Begin'':
begin
print 'Hello World!'
end
The following is an example of an ''Includ''ed procedure that contains a ''Sirius Case ToUpper'' directive:
sirius case toUpper
subroutine hello
print 'Hello World!'
end subroutine
Note that mixed case UL support is case independent so you can write UL statements in an case, and you can refer to Model 204 variables in any case. The following illustrates a little island of mixed case code in the middle of some upper case code:
SUBROUTINE FOOBAR(%INPUT IS FLOAT)
%MSG IS STRING LEN 32
%TOTAL IS FLOAT
...
if %input gt %total then
%msg = 'Input value too big'
end if
...
PRINT %MSG
END SUBROUTINE
This illustrates that you don't have to convert an entire procedure (or request) to mixed case to take advantage of mixed case UL, though, obviously, in the long-term, it's a good goal to aim for relatively consistent casing in all your code. In the short term, however, a bit of inconsistency will have to be tolerated to get to the point where most or all UL code is in mixed case. Certainly, any new procedures should be written completely in mixed case.

As this example, illustrates, you don't have to learn anything new to enter UL in mixed case ('''all''' statements still work the same way) so there is no excuse not to start.
==Object-oriented syntax==
The most pernicious difference between O-O languages and procedural languages such as User Language (we'll just call it ''UL'' from here on) is the syntax. And the biggest syntactic difference between O-O and UL is how functions and subroutines are invoked. Let's start with functions. All UL programmers know how to invoke a function.

First, functions are called $functions (dollar-functions) or £functions (pound-functions) in the UK. $functions (except some of the Sirius $functions) '''always''' return a value so must either be on the right side of an assignment, input to a subroutine or other $function call, or inside some UL expression. The following example, has a $substr in all three contexts:
%x = $substr(%y, 3, 10)
call clever($substr(%y, %start, %len))
%z = $substr(%y, %len, 1) + 10
As the above example illustrates, and all UL programmers know, a $function can be followed by the $function arguments (inputs) in parentheses with multiple arguments separated by commas.

O-O functions, on the other hand, use a syntax where a function invocation consists of the thing (object, if you will) that the function is operating on specified '''before''' the function name, followed by its arguments inside parentheses. Many $functions have O-O equivalents and $substr is no exception: its O-O equivalent is called ''substring''. The following illustrates the use of the O-O ''substring'' function by replacing ''$substr'' in the previous example with ''substring'':
%x = %y:substring(3, 10)
call clever(%y:substring(%start, %len))
%z = %y:substring(%len, 1) + 10
While this might look strange to a User Language programmer, it uses the most common O-O syntax so can honestly be called O-O programming. So, if you find any ''$substr'' call in your system and change it to use substring (moving the first argument before a :substring) you have now done some O-O coding. It's that easy!

To further add to your bona fides as an object oriented programmer, don't call substring a function, but call it a ''method''. In addition, don't call %y just a string, call it a ''string object''. Now you're ready for something more advanced. Say “I applied the substring method to the string object”. Repeat until it feels natural to say it. Congratulations, you're well on your way to becoming an O-O programmer and, maybe even a guru. If you're curious about what you just said:
*Method is just a fancy word that means function or subroutine or any other called code that does something.
*Object is just a fancy word for a thingy.
Now, of course, there are many functions available other than just Substring. The functions that operate on strings are called ''Intrinsic String Methods''. You can find a list of the methods at [[List of Intrinsic String Methods]]. There are also functions that operate on numbers. The list of these can be found at [[List of Intrinsic Float Methods]].

Now, while congratulating yourself on your new-found skills, you might have the gnawing feeling inside that you really haven't accomplished a lot, as much as you have learned. So what have you accomplished? Is O-O syntax really better than what you're used to? At first blush, it would seem worse, as the traditional $function call is more like English, where verb (function name) precedes the object (first parameter), as opposed to the O-O syntax, where the order is reversed. For example, one would say “get the substring of %y” not “%y get the substring” so
%x = $substr(%y, 2, 3)
'''seems''' more natural than
%x = %y:substring(2, 3)
While this might be true, it's easy enough to get used to the second form — in many languages the object comes before the verb.

In any case, the chief advantage of O-O syntax is that because the input of a function is to the left of the function, one can invoke a function and then pass the result of that function to another function by placing the second function call after the first. Similarly, a third function can be placed to the right of second to process its output. To illustrate, consider the following:
%x = %y:substring(%start, %len):toUpper:unspace
This reads rather nicely, left to right: take ''%y'' get a substring, convert to upper case, and remove extra blanks. The traditional version doesn't read nearly as nicely:
%x = $unspace($upcase($substr(%y, %start, %len)))
Since the processing happens in inside out order, presumably one should read this code inside out but, of course, this is very difficult. In addition, because only a colon is required as a separator character, and because no dollar-sign is required to distinguish a function from other entities, the O-O version is shorter, in spite of the fact that the function names are somewhat longer, and so, more meaningful. Perhaps more important, the O-O expression contains fewer “noise” characters. All of these lead to much better readability for the O-O expression. And, just as spaces can be placed around parentheses in a $function invocation to improve readability, spaces can be placed around the colon used to separate the object and function name:
%x = %y : substring( %start, %len ): toUpper :unspace

This example used inconsistent spacing just to illustrate what's allowed, not to suggest that inconsistent spacing is recommended — it's not.

So, to continue the process of becoming an object-oriented User Language programmer, you should familiarize yourself with the list of intrinsic string and float methods and try to use them wherever possible and try to use them in lieu of the $function equivalents. There is no performance penalty for doing so — in some cases O-O functions and $functions share the same underlying code.
===Named parameters===
The Sirius object-oriented User Language implementation has support for named parameters, parameters that can be specified by name, rather than position. While, strictly speaking, this has nothing to do with O-O programming (in fact, few O-O languages support it -- Java and VB.Net do not) named parameters are used in many Sirius methods, so it is important to understand them. To specify a value for a named parameter, simply specify the name, followed by an equals sign (''=''), followed by the value. For example, the Right and Left String functions have a ''Pad'' named parameter that indicates the pad character to be used if the input string is shorter than the requested length:
%x = %y:right(20, pad='0')
In this case, the name simply makes the code clearer as without the name:
%x = %y:right(20, '0')
it's far less obvious what the second parameter means. In functions with large numbers of parameters, the named parameters can also be very useful for eliminating the need for placeholder commas, and for making the function invocations more readable. String and Float methods tend not to have a lot of parameters so named parameters are not heavily used for them, but they '''are''' used here and there, so it's important to understand them.
==Stringlists==
The object-oriented extensions to User Language are provided by Sirius Software and are only available at sites that can use $lists. Most sites that '''can''' use $lists, '''do''' use $lists because many Sirius $functions require them as input or outputs, and because they are just generally useful.
$lists are essentially objects because an object is a container for information that is accessed via a reference variable, and multiple reference variables can refer to the same object ($list). For example:
%list is float
%list2 is float
...
%list = $listNew
%list2 = %list1
$listAdd(%list, 'Now is the winter')
print $listInf(%list2, 1)
In this example, the ''Print'' statement would end up printing “Now is the winter” even though the ''$listAdd'' added the line to ''%list''.
Both ''%list'' and ''%list2'' ;point to the same $list (object) and, so, it is not surprising that what is added via ''%list'' can be seen via ''%list2''. It is clear, too, that %list and %list2 must be '''pointers''' to $list objects and cannot be the objects, themselves, since a Float value couldn't possibly hold the contents of a $list.

So, when you were using $lists, you were using object-oriented programming capabilities even though you might not have realized it. However, you were '''not'' using object-oriented syntax to access the $list objects and so the benefits of a pure object-oriented facility were not available to you.

The pure object-oriented equivalennt of $lists is called ''Stringlists''.

BATCH2 (TCP/IP)

2010-09-01T13:10:05Z

Jeff:

BATCH2 is the name for a program that allows a stream of Model 204 commands in a sequential file to be sent to a [[Model 204]] [[Online]] and to have the output from the Online to be saved to another sequential output file. There are basically two BATCH2 programs:
#A BATCH2 program written in assembler and provided by Rocket Software that uses CRAM as its transport. Because CRAM is an inter-address space transport, this BATCH2 can only work if the BATCH2 program is running on the same machine and [http://en.wikipedia.org/wiki/LPAR LPAR] as the target Online.
#A BATCH2 program written in C provided by [[Sirius Software]] that uses TCP/IP as its transport. Because TCP/IP allows communication between two different machines, there are no restrictions on where the BATCH2 program is relative to the target Online. This is the BATCH2 program that is the subject of this page.
The original TCP/IP BATCH2 was expected to be run on [http://en.wikipedia.org/wiki/Unix Unix]. As such, it originally used Unix-style command line parameters. The TCP/IP BATCH2 was then extended to support [http://en.wikipedia.org/wiki/Microsoft_Windows Microsoft Windows] and, finally, was extended to work on IBM mainframe operating systems [http://en.wikipedia.org/wiki/VM_%28operating_system%29 VM] and [http://en.wikipedia.org/wiki/MVS MVS] (now known as [http://en.wikipedia.org/wiki/Z/OS z/OS]).

The mainframe implementations of the TCP/IP BATCH2 continued to use the Unix-style parameters. Unfortunately, because the CRAM BATCH2 used a totally different parameter list, this made it difficult to easily convert programs that used the CRAM BATCH2 to use the TCP/IP BATCH2. The ability to do this would be useful at a site that had multiple mainframe LPARs or machines — it can be useful to have a BATCH2 program running on one LPAR or machine communicating with a an Online on another. Because of this, BATCH2 was modified so that there was a version that used a parameter list identical to that used by the CRAM BATCH2.
==Requirements==
For the TCP/IP BATCH2 program to comunicate with an Online, that Online must have a Janus IFDIAL port defined.
For this to be possible, the Online must be linked with the [[Sirius Mods]] and must be authorized for the Janus TCP/IP Base product.
If an Online is authorized for Janus TCP/IP Base, an IFDIAL port can be defined with the JANUS DEFINE command, as in:
JANUS DEFINE IFDIAL 2231 IFDIAL 5 IBSIZE 4096 OBSIZE 8192 MAXREC 256
This defines a port that can be accessed via BATCH2 at port number 2231 on all IP addresses (it can be more than one if the host is [http://en.wikipedia.org/wiki/Multihoming multi-homed]) on the Onine's host machine.

The IBM C run-time libraries must also be available on the host where the z/OS or CMS BATCH2 program is running. Since these are now part of the standard z/OS and CMS distribution, this should only be a problem insofar as locating the libraries.

==CRAM BATCH2 compatibility==
If one would like to migrate from an environment where all BATCH2 jobs run on the same machine and LPAR as the target Onlines to an environment where the machine or LPAR running the BATCH2 and Online jobs could be mixed and matched, it would be ideal if the change could be made by simply replacing the CRAM BATCH2 load module with the TCP/IP module without any changes to the BATCH2 JCL.

But providing a TCP/IP BATCH2 that is plug compatible with the CRAM BATCH2 presents some special challenges. Most importantly, the target Online for a CRAM BATCH2 program is indicated by the first comma-delimited parameter. This parameter is an 8-byte or shorter CRAM channel name. But the TCP/IP BATCH2 requires a host name (which is often 16 bytes or longer) or IP address, and a port number. So, to provide CRAM BATCH2 compatibility, the mainframe TCP/IP BATCH2 must be linked with an assembler program that maps CRAM channel names to host names and port numbers.

This program is called BATCH2CH (for BATCH2 CHannel) and consists of pairs of null-terminated CRAM channel names, and host names or IP addresses and port numbers. The host name and port number must be separated by the space character. For example:
ENTRY BATCH2CH
BATCH2CH RMODE ANY
BATCH2CH CSECT
DC C'IOCALE',AL1(0)
DC C'sirius-software.com 2231',AL1(0)
DC C'IOALE',AL1(0)
DC C'sirijes2.sirius-software.com 2231',AL1(0)
DC AL1(0)
END
In this example, CRAM channel IOCALE is mapped to host ''sirius-software.com'', port number 2231, and CRAM channel IOALE is mapped to host ''sirijes2.sirius-software.com'', port 2231. The list is terminated with a single null (AL1(0)) after the last host name and port number. This allows the TCP/IP BATCH2 to be invoked with one of the CRAM channel names in BATCH2CH:
//BATCH2 EXEC PGM=BATCH2,REGION=4096K,
// PARM='IOCALE'
In the above example, if the BATCH2 program was linked with the (assembled) preceding BATCH2CH, it would try to connect to host ''sirius-software.com'' port 2231.
==Program parameters==
To maintain compatibility with the CRAM BATCH, the TCP/IP BATCH2 for z/OS now supports a parameter list identical to that used by the CRAM BATCH2. The format of the parameter list is:
[channel][,[OMC={X'xx' | num}][,URCTYPE={N | O | B}]]
where
;channel : Is the name of the CRAM channel name mapped in IFDIALCH.
; OMC value : Is either the hexadecimal or decimal (value must be less than 256) mask to be use to indicate special processing for certain server messages. The default value of OMC is zero (as it is for the CRAM BATCH2) which means that there is no special processing for server messages. The OMC value bit's indicate which messages are to be specially processed:
:;X'04' : Informational messages are to be suppressed from the output stream.
:;X'08' : $read prompts are to be suppressed from the output stream.
:;X'10' : Password prompts are to be suppressed from the output stream.
:;X'20' : A user restart should immediately terminate the BATCH2 job. When this happens, the return code from BATCH2 is set to 300.
:;X'40' : New page indicators are to be ignored.
:;X'80' : Error messages are to be suppressed from the output stream.
;URCTYPE value : Indicates whether errors in processing the BATCH2 job stream in the Online are to be reflected in the BATCH2 return code and, if so, which error code is to be used. The default value value of URCTYPE is N (as it is for the CRAM BATCH2) which means that errors in processing the BATCH2 job stream in the Online are not reflected in the BATCH2 return code. Regardless of the setting of URCTYPE, communications errors between BATCH2 and the Online will result in a variety of BATCH2 return codes, depending on the nature of the error. Return codes from the Online above 99 are converted to BATCH2 return code of 99 to prevent confusion with communication error return code. This is almost never a problem because, generally, even the most severe errors don't set return codes greater than 16. The values of the URCTYPE parameter are:
:;N : Don't reflect any errors in the job stream in the BATCH2 return code.
:;B : Set the BATCH2 return code to the value that a BATCH204 job running the identical job stream would return.
:;O : Set the BATCH2 return code to the value set for Online jobs. Generally, the return code reflected for URCTYPE=O will be less than that for URCTYPE=B — non-severe errors will often return 4 for URCTYPE=B and 0 for URCTYPE=O.
The following is an example of an EXEC card that invokes BATCH2 for channel IOALE, requesting that a user restart terminate the run (OMC=X'20'), and that batch return codes are to be used to set the BATCH2 return code:
//BATCH2 EXEC PGM=BATCH2,REGION=4096K,
// PARM='IOALE,OMC=X''20'',URCTYPE=B'
The single quotes in the OMC values must be doubled because they occur inside single quotes for the job card.
==Trusted login==
Another compatibility issue with the CRAM BATCH2 is that CRAM BATCH2 job stream is capable of doing a “trusted login” in the server Online. A trusted login logs on to the Online with the same userid as the userid under which BATCH2 is running. This requires that the same userid be able to run batch jobs and to log into Model 204.
This is typically not much of a problem at sites where an external authorizer such as [http://en.wikipedia.org/wiki/RACF RACF], [http://en.wikipedia.org/wiki/ACF2 ACF2], and Top Secret (by [http://en.wikipedia.org/wiki/Computer_Associates Computer Associates]) because userids for both JES and Model 204 are managed from the same security server.

A trusted login is usually indicated by a “naked” ''LOGIN'', that is a ''LOGIN'' command with no userid (or anything else) specified:
LOGON
OPEN FILE ALEXPROC
V
...
With CRAM BATCH2 it is relatively easy to securely validate the userid under which the BATCH2 program is running because BATCH2 and Model 204 are running on the same machine or LPAR and so cross-memory services can be used to retrieve and validate the userid.
For the TCP/IP BATCH2 the picture is somewhat more complicated. While the TCP/IP BATCH2 always passes the userid under which it is running to the Model 204 server, there is no particular reason for Model 204 to trust that the BATCH2 job should be allowed to run as that userid. This is because that BATCH2 might be running on a different machine from the Online and so could, in theory, be a BATCH2 program or BATCH impostor that is being used by someone trying to breach security.

So, to add a bit of control to TCP/IP BATCH2 trusted login, the userid passed by BATCH2 will only be used for a trusted login if a ''TRUST'' clause was specified for the target IFDIAL port, and that ''TRUST'' clause indicated an IP address or subnet that matches the BATCH client's IP address. The ''TRUST'' keyword on a ''JANUS DEFINE'' for an IFDIAL port must be followed by one or more IP addresses or subnets, separated by an ''AND'' keyword. Up to 16 IP addresses of subnets are allowed in a ''TRUST'' clause.

An IP address must be specified using standard [http://en.wikipedia.org/wiki/Dotted_decimal_notation dotted decimal notation] as in, for example, 198.242.244.47 (the IP address of Sirius Software's corporate web server).

A subnet can be specified either with an IP address followed by a [http://en.wikipedia.org/wiki/Subnetwork_mask subnet mask], both using dotted decimal notation and separated by a / character, or an IP address followed by a number of leading bits in the subnet part of the address, separated by a dash.
So 198.242.244.0/255.255.255.0 and 198.242.244.0-24 both describe the same class C subnetwork that just happens to be Sirius Software's subnet.

The following is an example of a ''TRUST'' clause in a ''JANUS DEFINE'' for an IFDIAL port:
JANUS DEFINE IFDIAL 2231 IFDIAL 5 IBSIZE 4096 OBSIZE 8192 MAXREC 256 -
TRUST 198.242.244.0-24 AND 208.80.152.2
Generally, a TRUST list should only include specific IP addresses (as opposed to subnets) and should be limited to IP address for hosts that:
#Are themselves secure
#Limit outgoing access to the IFDIAL port to an authorized BATCH2 progam.