EPLI

java.lang.Object
- com.heirloomcomputing.epli.runtime.EPLI

```
public class EPLI
extends java.lang.Object
```
EPLI - Elastic PL/I runtime support libraries general methods and main() printing the runtime library version

Author:

Heirloom Computing, Inc.

Field Summary

Fields
Modifier and Type	Field and Description
`static java.math.RoundingMode`	`RoundingRound`
`static java.lang.String`	`ROUNDINGROUND`
`static java.math.RoundingMode`	`RoundingTruncation` BigDecimal changes in scale are done with "setScale(n, rounding-mode)" use "HALF_EVEN" for traditional numeric rounding and "DOWN" for truncation From IBM Ent PL/I Lang Ref Man p.79: "Converting arithmetic precision When an arithmetic value has the same data attributes (except for precision) as the target, precision conversion is required.
`static java.lang.String`	`ROUNDINGTRUNCATION`

Constructor Summary

Constructors
Constructor and Description

EPLI()

Constructors
Constructor and Description
`EPLI()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static java.util.Properties`	`Annotations(Group group, java.lang.String fullName)` look for a member (field) within a group (class) and return annotations attached to it.
`static void`	`Assert(boolean test, java.lang.String... msgs)` Throw an ERROR Condition if an unexpected situation occurs
`static BitN`	`BitN(BitN inBits)` Runtime copy constructor of BIT(n) since BitN doesn't have one.
`static BitN`	`BitN(int nbits, BitN inBits)` Runtime copy constructor of BIT(n) since BitN doesn't have one.
`static BitN`	`BitNAnd(BitN op1, BitN op2)` Runtime & operator for BIT(n) since BitN doesn't have one.
`static BitN`	`BitNNot(BitN inBits)` Runtime prefix ^ operator for BIT(n) since BitN doesn't have one.
`static BitN`	`BitNOr(BitN op1, BitN op2)` Runtime \| operator for BIT(n) since BitN doesn't have one.
`static BitN`	`BitNXor(BitN op1, BitN op2)` Runtime infix ^ operator for BIT(n) since BitN doesn't have one.
`static void`	`ByAddress(java.lang.Object to, java.lang.Object from)` Assign interior of one object to another matching object type, essentially copying one object to another "by address." allows changing immutable objects (e.g., String, Double, FixedBin) passed as parameters.
`static void`	`ByValue(java.lang.Object to, java.lang.Object from)` Assign an entire group to a copy of another matching group, essentially copying the interior fields of a Group "by value."
`static boolean`	`CheckLic()` Check licensing of the Elastic PL/I Runtime intended to be invoked by a static constructor of one of the core EPLI runtime classes, such as Group
`static java.nio.charset.Charset`	`DefaultCharset()` get PL/I's mirror of Charset.defaultCharset() that is initially set from the JVM's start-up Charset.defaultCharset() but can be modified with RuntimeOption("CHARSET=chechen").
`static java.lang.Object`	`GetAnnotation(java.lang.Class<?> annotation, java.lang.Object variable)` GetAnnotation - get the value of @BIT, @CHAR, @PIC or @VARY annotation associated with an object.
`static java.lang.Object`	`GetCopy(Group grp, java.lang.String name)` GetCopy - Use reflection to get a copy of a non-static field within a group
`static java.lang.Object[]`	`GetExternal(java.lang.String name, java.lang.Object var)` Define a new or return an existing External variable
`static boolean`	`Has(Group grp, java.lang.String name)` Has - Use reflection to answer whether a Group object has a named non-static member
`static java.lang.Object`	`LookupProgram(java.lang.Class<?> klass)` Lookup a pre-registered instance of an EXTERNAL PROCEDURE by its Java class and thread currently running.
`static void`	`main(java.lang.String[] args)` Runtime module main routine prints version info and double-check the Elastic PL/I Runtime license for the current user.
`static java.lang.Object`	`RegisterProgram(java.lang.Class<?> klass, boolean isStatic)` Create and register an instance of an EXTERNAL PROCEDURE by name and by this thread such that all threads that lookup this procedure by the java class in which it is contained.
`static void`	`ResetProgram()` During reinitialization of an entire JVM running this PL/I program (when would that occur? dunno) you might want to clear out the Program Manager cache
`static java.lang.String`	`RuntimeOption(java.lang.String option)` Interrogate runtime options that are set as either properties or environment variables.
`static void`	`RuntimeOptions(java.lang.String[] options)` interrogate String args (from main method) for runtime option assignments (those with "name=value") and assign them as well as remove them from the list
`static java.lang.String`	`toFixedChar(java.lang.String inString, int len)` Simulate CHAR(n) datatypes by padding or truncating string to length
`static java.lang.String`	`toVarChar(BitN inBits)` Runtime conversion from BIT(n) to CHAR(m) VARYING
`static java.lang.String`	`toVarChar(BitN inBits, int N)` Runtime conversion from BIT(n) to CHAR(m) VARYING
`static java.lang.String`	`toVarChar(java.lang.String inString, int maxLen)` Runtime conversion CHAR(n) or CHAR(n) VARYING to CHAR(m) VARYING

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - RoundingTruncation
```
public static final java.math.RoundingMode RoundingTruncation
```
    BigDecimal changes in scale are done with "setScale(n, rounding-mode)" use "HALF_EVEN" for traditional numeric rounding and "DOWN" for truncation From IBM Ent PL/I Lang Ref Man p.79: "Converting arithmetic precision When an arithmetic value has the same data attributes (except for precision) as the target, precision conversion is required. For fixed-point data items, decimal or binary point alignment is maintained during precision conversion. Therefore, padding or truncation can occur on the left or right. If nonzero bits or digits on the left are lost, the SIZE condition is raised. For floating-point data items, truncation on the right, or padding on the right with zeros, can occur." thus, likely RoundingMode.DOWN should be used in most places. traditionally throughout EPLI development, RoundingMode.HALF_EVEN has been used. changes to this require extensive customer arithmetic calculation checking. Only when real rounding is called for (ROUND, ROUNDDEC builtin functions) should HALF_UP be used. IBM Ent PL/I Lang Ref Man specifies the rounding function as: round(x,n) = sign(x)*(b**-n )* floor(abs(x)* (b**n ) + 1/2) where b is 2 for FIXED BIN and b is 10 for FIXED DEC which appears to be "half up," with Q always translated to DEC digits Thus, RoundingTruncation and RoundingRound are defined here. needs to be the same as c.h.e.p.CodeBlock definitions
  - ROUNDINGTRUNCATION
```
public static final java.lang.String ROUNDINGTRUNCATION
```
    See Also:
    
    Constant Field Values
  - RoundingRound
```
public static final java.math.RoundingMode RoundingRound
```
  - ROUNDINGROUND
```
public static final java.lang.String ROUNDINGROUND
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - EPLI
```
public EPLI()
```
- Method Detail
  - RuntimeOption
```
public static java.lang.String RuntimeOption(java.lang.String option)
```
    Interrogate runtime options that are set as either properties or environment variables. special case to turn off the ability to interrogate these options.
    
    Parameters:
    
    option - - the option to interrogate and return the value or, if NOEXECOPS, ignore all further attempts to interrogate these options and EXECOPS, resume attempts to interrogate. if name=value then the option is set instead of interrogated
    
    Returns:
    
    the value of the option or null if it is not set
  - DefaultCharset
```
public static java.nio.charset.Charset DefaultCharset()
```
    get PL/I's mirror of Charset.defaultCharset() that is initially set from the JVM's start-up Charset.defaultCharset() but can be modified with RuntimeOption("CHARSET=chechen").
    
    Returns:
    
    epli's mirror default charset
  - RuntimeOptions
```
public static void RuntimeOptions(java.lang.String[] options)
```
    interrogate String args (from main method) for runtime option assignments (those with "name=value") and assign them as well as remove them from the list
    
    Parameters:
    
    options - - an array of arguments to the main procedure some of which may be of the form name=value in which case set those runtime options (and remove them from the list of options)
  - GetExternal
```
public static java.lang.Object[] GetExternal(java.lang.String name,
                                             java.lang.Object var)
```
    Define a new or return an existing External variable
    
    Parameters:
    
    name - - the name of this external object (all upper case)
    
    var - - an Object of the type expected for this external name
    
    Returns:
    
    - the one or more externals objects corresponding to the name
  - toFixedChar
```
public static java.lang.String toFixedChar(java.lang.String inString,
                                           int len)
```
    Simulate CHAR(n) datatypes by padding or truncating string to length
    
    Parameters:
    
    inString - - input string
    
    len - - defined fixed length of the string
    
    Returns:
    
    outString - padded or truncated string
  - toVarChar
```
public static java.lang.String toVarChar(java.lang.String inString,
                                         int maxLen)
```
    Runtime conversion CHAR(n) or CHAR(n) VARYING to CHAR(m) VARYING
    
    Parameters:
    
    inString - - input String
    
    maxLen - - the maximum length of this var char
    
    Returns:
    
    String - perhaps truncated
  - toVarChar
```
public static java.lang.String toVarChar(BitN inBits)
```
    Runtime conversion from BIT(n) to CHAR(m) VARYING
    
    Parameters:
    
    inBits - - input BitN
    
    Returns:
    
    outString - padded or truncated string
  - toVarChar
```
public static java.lang.String toVarChar(BitN inBits,
                                         int N)
```
    Runtime conversion from BIT(n) to CHAR(m) VARYING
    
    Parameters:
    
    inBits - - input BitN
    
    N - - the number of bits to return or 0 meaning the length of the BitN
    
    Returns:
    
    outString - padded or truncated string
  - BitN
```
public static BitN BitN(BitN inBits)
```
    Runtime copy constructor of BIT(n) since BitN doesn't have one.
    
    Parameters:
    
    inBits - - input BitN
    
    Returns:
    
    BitN with duplicate values of input
  - BitN
```
public static BitN BitN(int nbits,
                        BitN inBits)
```
    Runtime copy constructor of BIT(n) since BitN doesn't have one.
    
    Parameters:
    
    nbits - - only copy of to this number of bits (returned BitN cardinality)
    
    inBits - - input BitN
    
    Returns:
    
    BitN with duplicate values of input
  - BitNAnd
```
public static BitN BitNAnd(BitN op1,
                           BitN op2)
```
    Runtime & operator for BIT(n) since BitN doesn't have one. closest is BitN.and(), but it modifies the original. we are treating BIT(n) variable as immutable, like all other Java wrappered classes (Long, etc.)
    
    Parameters:
    
    op1 - - input BitN to and with ...
    
    op2 - - ... the other set of BitN
    
    Returns:
    
    BitN with each bit of the two inputs are anded, without modifying either input BitN
  - BitNOr
```
public static BitN BitNOr(BitN op1,
                          BitN op2)
```
    Runtime | operator for BIT(n) since BitN doesn't have one. closest is BitN.or(), but it modifies the original. we are treating BIT(n) variable as immutable, like all other Java wrappered classes (Long, etc.)
    
    Parameters:
    
    op1 - - input BitN to and with ...
    
    op2 - - ... the other set of BitN
    
    Returns:
    
    BitN with each bit of the input are orred, without modifying eotjer input BitN
  - BitNNot
```
public static BitN BitNNot(BitN inBits)
```
    Runtime prefix ^ operator for BIT(n) since BitN doesn't have one. closest is BitN.flip(), but it modifies the original. we are treating BIT(n) variable as immutable, like all other Java wrappered classes (Long, etc.)
    
    Parameters:
    
    inBits - - input BitN
    
    Returns:
    
    BitN with each bit of the input flipped, without modifying the input BitN
  - BitNXor
```
public static BitN BitNXor(BitN op1,
                           BitN op2)
```
    Runtime infix ^ operator for BIT(n) since BitN doesn't have one. closest is BitN.flip(), but it modifies the original. we are treating BIT(n) variable as immutable, like all other Java wrappered classes (Long, etc.)
    
    Parameters:
    
    op1 - - input BitN
    
    op2 - - input BitN
    
    Returns:
    
    BitN with exclusive-ored with one another modifying the input BitN
  - CheckLic
```
public static boolean CheckLic()
```
    Check licensing of the Elastic PL/I Runtime intended to be invoked by a static constructor of one of the core EPLI runtime classes, such as Group
    
    Returns:
    
    true if licensing is OK, false if failed
  - Assert
```
public static void Assert(boolean test,
                          java.lang.String... msgs)
```
    Throw an ERROR Condition if an unexpected situation occurs
    
    Parameters:
    
    test - - boolean - do nothing if true, raise a Condition if false
  - ByAddress
```
public static void ByAddress(java.lang.Object to,
                             java.lang.Object from)
```
    Assign interior of one object to another matching object type, essentially copying one object to another "by address." allows changing immutable objects (e.g., String, Double, FixedBin) passed as parameters.
    
    Parameters:
    
    to - - the destination object
    
    from - - the source object
  - ByValue
```
public static void ByValue(java.lang.Object to,
                           java.lang.Object from)
```
    Assign an entire group to a copy of another matching group, essentially copying the interior fields of a Group "by value."
    
    Parameters:
    
    to - - the target group
    
    from - - the source group
  - Annotations
```
public static java.util.Properties Annotations(Group group,
                                               java.lang.String fullName)
```
    look for a member (field) within a group (class) and return annotations attached to it. annotations are returned in a properties object with the following (String) name and values
  - NAME - the field name
  - CHAR - the @CHAR(n) value
  - BIT - the @BIT(n) value
  - PIC - the @PIC("pic-spec") value
  - VARY - the @VARY value of anything if it exists
  - OFF - the @OFF(n) value

Parameters:: group - - a group containing ...; fullName - - ... a member name
Returns:: Properties containing annotation information defined on this field

Has
```
public static boolean Has(Group grp,
                          java.lang.String name)
```
Has - Use reflection to answer whether a Group object has a named non-static member

Parameters:

grp - - the source group

name - - a potential field within that group

Returns:

true if name is a non-static field name within grp

GetCopy
```
public static java.lang.Object GetCopy(Group grp,
                                       java.lang.String name)
```
GetCopy - Use reflection to get a copy of a non-static field within a group

Parameters:

grp - - the source group

name - - a potential field within that group

Returns:

either the same immutable object in grp or a copy of that object named in grp

GetAnnotation
```
public static java.lang.Object GetAnnotation(java.lang.Class<?> annotation,
                                             java.lang.Object variable)
```
GetAnnotation - get the value of @BIT, @CHAR, @PIC or @VARY annotation associated with an object. return different objects for each

Parameters:

annotation - - the interface class of the annotation requested, sBIT.class, CHAR.class, PIC.class or VARY.class.

variable - - the variable to test for the annotation

Returns:

the value of the annotation or null if it is not defined. the object returned is different for each annotation requested,
@BIT - an Integer value of the number of bits or null if not defined
@CHAR - an Integer value of the number of characters or null if not defined
@PIC - an String value of the picture specification or null if not defined
@VARY - an Boolean.TRUE value if the annotation is defined or null if not defined Note: the ability to do this relies on JSR308 which was implemented in Java 8 but the APIs have not yet been updated to reflect this. So, will not work on LOCAL_VARIABLE Target({ ElementType.LOCAL_VARIABLE }) with Java 8

RegisterProgram
```
public static java.lang.Object RegisterProgram(java.lang.Class<?> klass,
                                               boolean isStatic)
```
Create and register an instance of an EXTERNAL PROCEDURE by name and by this thread such that all threads that lookup this procedure by the java class in which it is contained.

Parameters:

klass - - the class containing the external procedure to register. for Elastic PL/I classes it is the CamelCase of the camelBack procedure name to be called (PL/I PROC MY_PROC is generated by epli as procedure myProc() in class MyProc).

isStatic - - lookup is done on a per thread basis, unless isStatic is defined in which case there is effectively one instance of this class used by all threads, making it effectively static. in either case variables declared as STATIC or EXTERNAL within the procedure will be shared across all threads within the JVM.

Returns:

the instance either created or registered by another user of this Class

Throws:

Condition.ERROR - with condition code PROCEDURENOTFOUND if this is not a PL/I procedure that has been declared and whose class is avalable to this JVM's class loader. If this is a COBOL or JAVA program that must be invoked, declare your procedure with the correct LINKAGE and other Program Managers for them.

LookupProgram
```
public static java.lang.Object LookupProgram(java.lang.Class<?> klass)
```
Lookup a pre-registered instance of an EXTERNAL PROCEDURE by its Java class and thread currently running. if the instance is defined as "static" (to be shared across all users of it), return that one first.

Parameters:

klass - - the class containing the external procedure to register. for Elastic PL/I classes it is the CamelCase of the camelBack procedure name to be called (PL/I PROC MY_PROC is generated by epli as procedure myProc() in class MyProc).

Returns:

the instance either created or registered by another user of this Class

ResetProgram
```
public static void ResetProgram()
```
During reinitialization of an entire JVM running this PL/I program (when would that occur? dunno) you might want to clear out the Program Manager cache

main
```
public static void main(java.lang.String[] args)
```
Runtime module main routine prints version info and double-check the Elastic PL/I Runtime license for the current user. See http://support.heirloom.cc for info on how to obtain a license

Parameters:

args - - arguments ignored, unless "-test" is given

Class EPLI

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

RoundingTruncation

ROUNDINGTRUNCATION

RoundingRound

ROUNDINGROUND

Constructor Detail

EPLI

Method Detail

RuntimeOption

DefaultCharset

RuntimeOptions

GetExternal

toFixedChar

toVarChar

toVarChar

toVarChar

BitN

BitN

BitNAnd

BitNOr

BitNNot

BitNXor

CheckLic

Assert

ByAddress

ByValue

Annotations

Has

GetCopy

GetAnnotation

RegisterProgram

LookupProgram

ResetProgram

main