PL/I considerations for rule application development

If you want to execute rules in a PL/I application, you must develop your business rule application with PL/I structures as the reference point for your object model.

PL/I include file and XOM generation

When you identify a PL/I include file that you want to use to generate a XOM, you must know that not all PL/I data items and data types map, or map directly, to Java™ structures.

The following table outlines where special considerations apply when you generate the XOM from a PL/I include file.

Tip: Some of the following links point to distributed topics.

PL/I consideration	Description	Further information
Boolean type	The PL/I single BIT character is mapped to the Java boolean type. You can also use the predefined type converter to change the default mapping for PL/I items to a boolean type.	Mapping PL/I data items to boolean and date types
Date type	The PL/I string character Date attribute is not supported. You can use the predefined Date type converter to map PL/I items to the Java Date type you want.	Mapping PL/I data items to boolean and date types
PL/I to Java type mapping	When you generate a XOM from a PL/I include file, the PL/I types are mapped to default Java types.	PL/I to Java mapping
PL/I data item mapping to Java structures	PL/I data items map to different Java structures, depending on the level of the data item and the level at which it is defined.	PL/I data item mapping to Java structures
Custom data types	You can use the annotation extension point to add your own converters, so that you can map PL/I include file items to your own Java types.	Creating custom types for PL/I data items
Group items and data items	Each group item in the PL/I include file maps to a Java class in the XOM. Data items that have a parent in a PL/I include file map to an attribute in the parent Java class in the XOM.	Group items and data items in PL/I
Top-level data items	For a top-level data item, the include file creates one XOM class, which has one attribute.	Top-level data items in PL/I
Nested include files	How the PL/I importer generates the XOM depends on whether the include file contains %INCLUDE statements, or references other include files.	%INCLUDE statements in the include file
Arrays	Fixed-length arrays are supported. Variable-length arrays without the REFER option are not supported. If an array contains the REFER options, it maps to the Java array type with some limitations. For more information about the limitations, see PL/I Limitations.	Array mapping between PL/I and Java

Designing business object models

To define a business object model (BOM), you first generate a XOM from a PL/I include file, and you use the XOM to generate BOM, and then you define methods for the BOM.

PL/I consideration	Description	Further information
BOM-to-XOM mapping	When you add methods to the BOM, you create members in the BOM that are not defined in the XOM. This mismatch creates errors in your rule project.	Defining BOM to XOM mapping
Ruleset parameters	You can define ruleset parameters only for top-level data items. You define ruleset parameters by the name, the type, and the direction: For zRule Execution Server for z/OS® deployment you can define IN or IN-OUT parameters. You can use only primary types for ruleset parameters. You cannot define primitive types. Make sure that you select the Enable type check for COBOL XOM or PL/I XOM on the Ruleset Parameters page. The type check feature provides a filter for ruleset parameter selection. When you enable it, only the top-level BOM types are displayed.	Defining the ruleset content and signature

PL/I consideration

Description

Further information

BOM-to-XOM mapping

When you add methods to the BOM, you create members in the BOM that are not defined in the XOM. This mismatch creates errors in your rule project.

Defining BOM to XOM mapping

Ruleset parameters

You can define ruleset parameters only for top-level data items.

You define ruleset parameters by the name, the type, and the direction:

For zRule Execution Server for z/OS® deployment you can define IN or IN-OUT parameters.

You can use only primary types for ruleset parameters. You cannot define primitive types.

Make sure that you select the Enable type check for COBOL XOM or PL/I XOM on the Ruleset Parameters page. The type check feature provides a filter for ruleset parameter selection. When you enable it, only the top-level BOM types are displayed.

Defining the ruleset content and signature

BOM sharing between Java and PL/I

To be able to generate a PL/I include file from a Java BOM, you must use Java data structures, and Java class types and characters that map to PL/I code.

PL/I consideration	Description	Further information
Data structures and BOM type mapping	Where Java data structures in the BOM do not map to PL/I, you must either amend the BOM, or amend the XOM and then update the BOM.	Supported Java data types for mapping to PL/I data models
Dynamic XOM	If the BOM is derived from an XML Schema, you cannot use the BOM to generate a PL/I include file. The BOM must be based on a Java XOM.	Overview: Dynamic execution object model (XOM)
Tables	The Java List item creates a PL/I array.	Supported Java data types for mapping to PL/I data models
Unsupported characters	If a BOM variable name contains a character that PL/I does not support, an error message is reported.
BOM elements with BOM-to-XOM mapping	You can design BOM elements with a BOM-to-XOM mapping. When you generate an include file: BOM attributes with a BOM-to-XOM mapping do not generate PL/I items. A BOM with an execution class generates PL/I items according to the execution class structures. The execution class must be imported as a BOM class.	Enabling the BOM for PL/I include file generation

Authoring

PL/I consideration	Description	Further information
PL/I value checker	The PL/I management feature uses an automatic value checker that validates your rules against the definitions of the terms in the BOM.

Testing and simulation

You can use Decision Center to test the rules that you intend to deploy to zRule Execution Server for z/OS. To test and simulate your rules on z/OS, you must deploy one of the following environments and then set up your Scenario Service Provider (SSP):

Rule Execution Server on WebSphere® Application Server for z/OS
zRule Execution Server for z/OS. For more information, see Step 1: Adding the SSP to zRule Execution Server for z/OS.

PL/I consideration	Description	Further information
Testing and simulation	To test your rulesets, you deploy your RuleApps and the Java XOM to Decision Center and then run the required tests and simulations. When you finish testing, you can deploy your final RuleApps to zRule Execution Server for z/OS from Rule Designer or Decision Center. The actual running logic might differ slightly from the testing and simulation results, due to differences in how certain structures are handled in Java and PL/I. The differences occur only in the marshalling layer, so you can adapt your test inputs and expected results to compensate.	Testing and simulating rulesets

PL/I consideration

Description

Further information

Testing and simulation

To test your rulesets, you deploy your RuleApps and the Java XOM to Decision Center and then run the required tests and simulations.

When you finish testing, you can deploy your final RuleApps to zRule Execution Server for z/OS from Rule Designer or Decision Center.

The actual running logic might differ slightly from the testing and simulation results, due to differences in how certain structures are handled in Java and PL/I. The differences occur only in the marshalling layer, so you can adapt your test inputs and expected results to compensate.

Testing and simulating rulesets

The following list provides examples of when differences can occur between testing and simulation and run time:

PL/I strings are fixed length and Java strings are variable length. This difference can cause different results between testing and simulation and PL/I run time, due to the marshalling and unmarshalling process.
Numeric data out of range or truncation occurs during the Java to PL/I marshalling process
List size problem

In Java, the size of a list is dynamic, but for PL/I array mapping, an array has a maximum size limit. If the Java list size exceeds the maximum limit of the array, zRule Execution Server for z/OS execution throws a run time exception. Testing and simulation do not report an error.
Floating data precision problem during data conversion

Because Java and PL/I use a different representation for floating data, precision is lost during the marshalling and unmarshalling process. Testing and simulation do not report an error.
Using a NULL object test

In Java, you can provide a null object for simulation and testing. You can also write rules to test if an object is null or not. zRule Execution Server for z/OS execution never generates a null Java object from a PL/I data even when it contains a blank value. It means a rule to test a NULL object is never fired.