COBOL considerations for rule application development

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

The following tables outline special considerations when you choose zRule Execution Server for z/OS® as an execution option.

COBOL copybook and XOM generation

When you identify a COBOL copybook that you want to use to generate a XOM, you must know that not all COBOL data items and data types map, or map directly, to Java™ structures.

COBOL consideration	Description	Further information
Boolean type	The boolean type does not exist in COBOL. However, you can use the predefined boolean type converter to map COBOL items to a boolean type.	Mapping COBOL data items to boolean and date types
Date type	IBM® Enterprise COBOL Date Format clause is not supported. You can use the predefined Date type converter to map COBOL items to the Java Date type you want.	Mapping COBOL data items to boolean and date types
COBOL to Java type mapping	When you generate a XOM from a COBOL copybook, the COBOL types are mapped to default Java types.	COBOL to Java mapping
COBOL data item mapping to Java structures	COBOL data items map to different Java structures that depend on the level of the data item and the level at which it is defined.	COBOL data item mapping to Java structures
COBOL domains	You can convert COBOL data items to a domain type by using the copybook import wizard.	Working with domains and z/OS data models
Custom data types	You can use the annotation extension point that is provided to add your own converters so that you can map COBOL copybook items to your own Java types.	Creating custom types for COBOL data items
Group items and data items	Each group item in the COBOL copybook maps to a Java class in the XOM. Data items that have a parent in a COBOL copybook map to an attribute in the parent Java class in the XOM.	Group items and data items
Top-level data items	For a top-level data item, the copybook creates one XOM class, which has one attribute.	Top-level data items
COBOL SYNC clause support	A COBOL copybook that contains a SYNC clause does not support COBOL code generation.
Nested copybooks	How the COBOL importer generates the XOM depends on whether the copybook contains COPY statements, or references other copybooks that do.	COPY statements in the copybook
REDEFINES statements	If the copybook contains REDEFINES statements, the COBOL copybook importer generates Java type mappings for each data item that is associated with the REDEFINES statement. However, you can select only one data item for the XOM.	REDEFINES statements in the copybook
Tables	Fixed-length tables are fully supported and you can use them with no restrictions. For variable length tables, the following structures are not supported: ODO tables in the copybook that share the same `depending on` item. ODO tables in the copybook that do not have a 01 top-level item.	Table mapping between COBOL and Java

Designing business object models

To define a business object model (BOM), you first generate a XOM from a COBOL copybook, you use the XOM to generate BOM, and then you define methods for the BOM.

COBOL 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. You can keep the BOM synchronized with the XOM in two ways: You can map the new methods to the XOM. In this case you have the flexibility to generate COBOL code for rule execution, or to deploy to zRule Execution Server for z/OS. You can disable BOM to XOM checking. Do this only if you are sure that the rules are executed only by using generated COBOL code. To disable BOM to XOM checking: Click Window > Preferences > Rule Designer > Build, and then clear the Perform BOM to XOM checks during build check box. This consideration does not apply if you choose to generate COBOL code for rule execution.	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 COBOL code generation, you can define only IN-OUT parameters for your BOM classes. For zRule Execution Server for z/OS deployment you can define IN or IN-OUT parameters. In both cases, 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

COBOL 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.

You can keep the BOM synchronized with the XOM in two ways:

You can map the new methods to the XOM. In this case you have the flexibility to generate COBOL code for rule execution, or to deploy to zRule Execution Server for z/OS.
You can disable BOM to XOM checking. Do this only if you are sure that the rules are executed only by using generated COBOL code.

To disable BOM to XOM checking:

Click Window > Preferences > Rule Designer > Build, and then clear the Perform BOM to XOM checks during build check box.

This consideration does not apply if you choose to generate COBOL code for rule execution.

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 COBOL code generation, you can define only IN-OUT parameters for your BOM classes.
For zRule Execution Server for z/OS deployment you can define IN or IN-OUT parameters.

In both cases, 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 COBOL

To be able to generate a COBOL copybook from a Java BOM, you must use Java data structures, and Java class types and characters that map to COBOL copybook code.

COBOL consideration	Description	Further information
Data structures and BOM type mapping	Where Java data structures in the BOM do not map to COBOL, you must either amend the BOM, or amend the XOM and then update the BOM.	Supported Java data types for mapping to COBOL data structures
Dynamic XOM	If the BOM is derived from an XML schema, you cannot use the BOM to generate a COBOL copybook. The BOM must be based on a Java XOM.	None
Reserved words	If BOM variable names match COBOL reserved words, an error message is reported.	None
Tables	The Java List item creates a COBOL fixed-length table and an integer.	Supported Java data types for mapping to COBOL data structures
Unsupported characters	If a BOM variable name contains a character that COBOL does not support, an error message is reported.	Unsupported characters and reserved words
BOM elements with BOM-to-XOM mapping	You can design BOM elements with a BOM-to-XOM mapping. When you generate a copybook: BOM attributes with a BOM-to-XOM mapping do not generate COBOL items. A BOM with an execution class generates COBOL items according to the execution class structures. The execution class must be imported as a BOM class.	None

Authoring

COBOL consideration	Description	Further information
COBOL value checker	The COBOL management feature uses an automatic value checker that validates your rules against the definitions of the terms in the BOM. You set the constraints in the COBOL copybook.	COBOL rule validation

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.

COBOL 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 finished 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 COBOL. The differences occur only in the marshalling layer, so you can adapt your test inputs and expected results to compensate. Testing and simulation are not supported if you choose to generate COBOL code for rule execution. The running logic between test scenarios and COBOL code execution is not similar enough to give useful test results.	Testing and simulating rulesets Handling data type differences between Java and COBOL

COBOL 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 finished 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 COBOL. The differences occur only in the marshalling layer, so you can adapt your test inputs and expected results to compensate.

Testing and simulation are not supported if you choose to generate COBOL code for rule execution. The running logic between test scenarios and COBOL code execution is not similar enough to give useful test results.

Testing and simulating rulesets

Handling data type differences between Java and COBOL

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

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

For example, if COBOL PIC 9 maps to Java short. If the Java data is marshalled back as 10, zRule Execution Server for z/OS execution throws an out of range exception. Testing and simulation do not report an error.
List size problem

In Java, the size of a list is dynamic, but for COBOL ODO table mapping, a table has a maximum size limit. If the Java list size exceeds the maximum limit of the ODO table, 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 IBM Enterprise COBOL 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 COBOL data even if it contains a blank value. It means a rule to test a NULL object is never fired.