Release notes - P3/COBOL Compiler - Version 8.3

General information

P3/COBOL 8.3.x is supported on Java 8, 11, and 17 (all are designated LTS by the OpenJDK project). P3/COBOL also has been tested on Java 19 and 20 (the current latest release). It is fully tested with on the LTS versions on the following binary providers:

• Eclipse Temurin®
• Oracle Java®
• Azul Zulu®

on the Windows, Linux, and macOS platforms.

P3/COBOL 8.3.x is planned to be the last feature release with Java 8 as the base requirement. Subsequent P3/COBOL versions will be based on more recent LTS Java versions (beginning with Java 17). P3/COBOL 8.3 will be maintained for any potential bug and/or security fixes in ongoing 8.3.x point releases until Java 8 itself is no longer supported. Typically new features and improvements not in 8.3, however, will only be available in subsequent P3/COBOL major releases based on more recent, supported Java versions.

Migration from 8.2 to 8.3

Running P3/COBOL on Java 11 or 17 (LTS)

In order to run P3/COBOL version 8.3.x on Java 11 or 17 using the java command you will need to specify a few Java (JVM) options. Future P3/COBOL major releases will not require these options, as they will be able to utilize the module system included in post-8 version Java releases.

Java command-line options:

--add-opens java.base/java.util=ALL-UNNAMED
--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.nio=ALL-UNNAMED

The Java (JVM) options are required at runtime only. They are not necessary at compile time.

P3-Utility & Java-Command

When running a P3/COBOL program from the p3 command line utility the options are set automatically. Running a P3/COBOL program from the command line using the java command, you must specify the additional Java (JVM) options:

p3 r -i hello-world

Running P3/COBOL on Java 17 (LTS) [incubating JEP 412]

In order to run P3/COBOL version 8.3.x on Java 17 (using incubating JEP 412) using the java command you will need to specify a few Java (JVM) options.

Java command-line options:

--add-opens java.base/java.util=ALL-UNNAMED
--add-opens java.base/java.lang=ALL-UNNAMED
--enable-native-access=ALL-UNNAMED
--add-modules jdk.incubator.foreign
--add-opens jdk.incubator.foreign/jdk.incubator.foreign=ALL-UNNAMED

Running P3/COBOL on Java 19 or 20 [Previewing JEP 424/434]

In order to run P3/COBOL version 8.3.x on Java 19 or 20 (using the preview Foreign Functions and Memory feature) using the java command you will need to specify two Java (JVM) options.

Java command-line options:

--enable-native-access=ALL-UNNAMED
--enable-preview

Running a P3/COBOL program from command line using the p3 command line utility, you may activate the FFM-feature using the Java property -Dp3.ffm. As shown in the sample below, no additional Java (JVM) options are required.

Running a P3/COBOL program from command line with the java command, you have to specify the additional Java (JVM) options, to activate the FFM-feature:

p3 r -Dp3.ffm -- -i hello-world

Refactored package structure

In 8.3.x there has been extensive package restructuring to separate internal P3/COBOL classes and those that may be used by user-written Java either within COBOL embedded Java or separate classes supporting the COBOL application. These changes are also accomplished in preparation for later modularized releases of P3/COBOL when the Java base is moved to LTS Java version 11 and beyond. They become required when the base moves to Java version 17, as the techniques that must be used for P3/COBOL to perform some functions will become incompatible with those required for versions 8 and below. When compiling traditional COBOL source code using P3/COBOL 8.3, all of the necessary changes for this refactoring will be performed automatically. If, however, you use the Java Augmented Syntax features such as embedded Java (JAS) or you have hand-written Java that interacts with generated P3/COBOL classes, you will need to check and correct any package names (in imports and/or the REPOSITORY paragraph) and within any embedded Java. If you use your own Java classes to interact programmatically with P3/COBOL generated Java, you might need to change the import package names that are satisfied by classes within the P3/COBOL distribution jars. In addition, Java code constructing class instances of classes within the P3/COBOL library will likely need to be changed to use equivalent static method invocations provided by the appropriate interface(s). For example, to instantiate a ByteStore object the static method ByteStore.newByteStore(...) should be used as the ByteStore is now an interface rather than an Object. In most cases the arguments are the same as the previous constructor arguments.

New static methods that replace constructors

RuntimeOptions

import com.turrettech.p3cobol.runtime.RuntimeOptions;
 
class RuntimeOptionsDemo {
    public static void main(String[] args){
        RuntimeOptions runtimeOptions = RuntimeOptions.newRuntimeOptions("-c", "runtime.p3c");
    }
}

or

import static com.turrettech.p3cobol.runtime.RuntimeOptions.newRuntimeOptions;
 
class RuntimeOptionsDemo {
    public static void main(String[] args){
        RuntimeOptions runtimeOptions = newRuntimeOptions("-c", "runtime.p3c");
    }
}

RunUnit

import com.turrettech.p3cobol.lib.RunUnit;
 
class RunUnitSample {
    public static void main(String[] args){
        RunUnit runUnit = RunUnit.newRunUnit(runtimeOptions);
    }
}

Launcher

import com.turrettech.p3cobol.server.Launcher;
 
class LauncherSample {
    public static void main(String[] args){
        Launcher launcher = Launcher.newLauncher(runtimeOptions);
    }
}

DataUtils

import com.turrettech.p3cobol.lib.common.DataUtil;
 
class DataUtilSample {
    public static void main(String[] args){
        DataUtil newDataUtil = DataUtil.newDataUtil(runtimeOptions);
    }
}

ByteStore

import com.turrettech.p3cobol.lib.ByteStore;
 
class ByteStoreSample {
    public static void main(String[] args){
        ByteStore byteStore = ByteStore.newByteStore(10);
    }
}

All of these changes are reflected in the Javadocs API documentation described below.

The hello-universe project template (which can be created in the P3/COBOL Project Wizard in the IDE) shows, how the new interfaces can be used.

Deprecated P3Main class

The P3Main class is now deprecated for future removal. While it may still be used, the main method and the getVersion method have been moved to the RunUnit interface and may also be used there in this release. The p3cobol.jar file now designates the RunUnit class as the Main-Class rather than the P3Compiler class formerly designated.

Enhanced Javadocs for public P3/COBOL library classes and methods

API Javadocs are now provided for all public classes, methods, and fields accessible to the user in the runtime library classes. If a class or public method is not to be invoked by user-written Java, it will be marked with either a @GeneratedReference annotation, meaning that the method is intended to be invoked by Java code generated by the P3/COBOL compiler, or by an @API annotation indicating a status other than "STABLE". Any public constructor or method not annotated can be presumed to have the characteristics of the enclosing class.

Changes to the way constant (78) expressions are evaluated

In order to provide better compatibility with other COBOL dialects, the evaluation of constant expressions in 78-level item definitions has been revised. It is now done in a manner that gives results consistent with those of Micro Focus's COBOLs. In previous P3/COBOL releases the expression was calculated with floating-point decimal arithmetic and the result could act as an integer, floating point or decimal constant literal. In this release intermediate and final results are optionally converted to 64-bit binary integers at each step and the final result is given as a 64-bit positive integer value.

In addition, the default P3/COBOL computation has been improved to detect more error conditions and to use the IEEE 754R standard DECIMAL128 to accumulate intermediate results. Also, the behavior of the NEXT keyword has been enhanced to return a meaningful offset value for cases that previously returned a useless value of 0. This behavior is also consistent with the Micro Focus behavior in those circumstances.

If you use other than simple literals for the value of 78-level items, and you expect other than Micro Focus values to be returned, in this unlikely case you should carefully check to see that these changes have not affected your program logic and make any necessary adjustments if they do. Since the capabilities are now a superset of the prior cababilities, this should always be possible and are likely straightforward.

Eclipse IDE improvements

There is now a new configurable editor key for toggling a "D" in the indicator column (if any). As you might remember, a "D" (or "d") indicator means that the line should be compiled as COBOL code only if the appropriate option is enabled for the compilation. In the case of P3/COBOL, this is the debug-lines option.

When launching a remote P3/COBOL debugger, only one port now need be specified. That port should match the --debug-port (replaces --debug-ports) runtime option for the program to be debugged.

JAS Changes

There have been several changes to the JAS syntax primarily to make it express intent more clearly and improve parsing. If you are using this experimental capability you should check for new compilation errors and, if present, change the program to adopt the revised syntax. The semantics and overall capabilities are typically unchanged.

ENTRY statement improvement

The ENTRY statement has been improved to allow any entry point names that do not conflict with other entry point names in the same program. This is more consistent with the IBM implementation of this extension, but note that the ENTRY in P3/COBOL is still not 100% equivalent to the native code implementations of IBM and other vendors due to Java language constraints. For the vast majority of programs, however, the resulting behavior is the same.

Zoned-decimal handling

The treatment of zoned-decimal DISPLAY number handling has been improved. The IS NUMERIC class test now strictly conforms to the behavior of other dialects and the ISO 2014 standard, in that it now verifies that signed values have the correct operational signs and that only valid digits are present. This differs from the previous behavior which indicated that retrieving the value would not result in a data exception condition given the current configuration for zoned-decimal validation. If the previous behavior is desired, the runtime option --not-strict-numeric-class-test may be used.

In addition to the class test, all retrieval of DISPLAY numeric values from memory now verifies that the stored form is compatible with the configured zoned-decimal-validation level. Prior releases verified only some retrievals, leaving others to produce unpredictable results. While that behavior was correct according to the standards, it did not detect corrupted data at the earliest point in time. This release tightens that detection while (via configuration of zoned-decimal-validation) permitting the relaxation of that testing for performance when it is known that the program is correct and will not encounter invalid values. If you normally use the runtime option --zoned-decimal-validation set to any value other than "STRICT", you should verify that this change does not affect your programs' results.

Issue Details

🐛 Bugfixes

• P3-270 Dots() production randomly fails in parsing (usually after program-id)
• P3-273 78 constants can be set in generated code
• P3-274 Creation of file symbol fails to initialize "offset"
• P3-277 Debugger should attempt to reattach to client after disconnect if suspend is false
• P3-331 DecimalMath getBigDecimal(BigInteger) gives incorrect answer
• P3-337 Arithmetic errors do not traceback to most precise location
• P3-340 MOVE ALL "" (quote quote) hangs in Pass 2
• P3-341 MOVE ALL my-78 TO ... gives non-specific syntax error indication
• P3-343 Debugging a nested program does not stop at first (and subsequent) breakpoint reached
• P3-347 NPE when calling ENTRY with debug enabled
• P3-348 return-code is not passed thru to the command line
• P3-349 p3bridge is not able to initialize the RunUnit
• P3-350 Debugger loses variable values when run unit reused (launcher)
• P3-351 The debug-kind compiler option is not documented
• P3-362 fix version string for Azul java 11 on windows x86
• P3-368 Stack annotation for dump-java-stack incorrect for wrapped statements
• P3-370 Program debug stack has no line, column information and cannot show source in editor
• P3-371 Debugger stops showing current (green) selection when calling an ENTRY point
• P3-372 MOVE 1 TO MY-88 (an 88 identifier) generates bad Java
• P3-373 88-conditions do not appear in the debug variable view unless the conditional variable is directly referenced
• P3-374 Location-free debug information does not work with nested programs
• P3-375 Extraneous stack traces going to console
• P3-376 Variables "Detail" view cannot show more than 100 characters regardless of configuration
• P3-384 NUMERIC class test throws BufferUnderflow exception when x-strict-numeric-class-test is true
• P3-385 MOVE ZEROS TO National yields 0x30303030... rather than 0x0030003000300030... in memory
• P3-387 PICTURE that includes two or more consecutive "/"s is truncated and the balance treated as a tail comment
• P3-388 In a numeric-edited picture simple insertion after the trailing sign is not allowed
• P3-392 Class data files left behind after "clean"
• P3-394 Symbolic character in abbreviated comparison fails to generate according to implied ALL characteristic
• P3-397 INITIALIZE ... REPLACING ALPHANUMERIC BY 12345 results in NPE in Pass2 when --fast-initialize
• P3-398 INITIALIZE ... REPLACING ALPHANUMERIC BY -123 initializes the item to -123 instead of 123
• P3-399 Incorrect implied picture for integer numeric items of precision <= 18
• P3-405 78 changes have resulted in MOVE checking rules too late for diagnostics
• P3-408 Launch configuration does not allow completion until focus is moved off of the first tab
• P3-416 Should allow ENTRY names that duplicate unqualified data names
• P3-417 Migration from a fixed-length binary sequential file fails to create the volume
• P3-429 AppClient closes System.out when running program with DISPLAY
• P3-432 AppClient times out any runProgram after a few seconds
• P3-438 NPE thrown upon debug shutdown if run unit "call"ed on user thread
• P3-439 An attached debugger can only be used for a single runUnit.call(...) method
• P3-446 Zero-length alphanumeric items and literals should be considered equivalent to SPACE(s)
• P3-458 Debug hover values for indexed references incorrect if "," used as separator
• P3-460 MOVE something TO group-with-internal-occurs-dependency should force fixed-length
• P3-462 Debugger variables view is not sorted by ID
• P3-465 88s with an alphanumeric range value of less than 9 characters generates bad code when LITTLE_ENDIAN

📝 Stories

• P3-383 Update IDE samples for 8.3.x
• P3-410 New p3-utility (b)uild now supports --version to print p3cobol version to console
• P3-411 Various updates/reviews to the documentation

🛠️ Improvements

• P3-136: UNSTRING should allow national delimiter to be specified
• P3-141: Soft fail when JNA not available (i.e., external call strategy not possible)
• P3-243: Set "isDerived" on compiler output folders and files
• P3-305: Use the @APIGuardian annotations to reflect the status of runtime APIs in P3/COBOL
• P3-312: Refactor RunUnit into RunUnit interface and RunUnitImpl implementation to hide internal public methods
• P3-339: Treat 78 items according to MF behavior (Optionally?)
• P3-363: Make generated files derived resources
• P3-364: Make temporary (Java) generated source files and directories hidden
• P3-367: Alphabetize compiler options in generated source and help output
• P3-377: Add the Prototype option for Launcher configurations
• P3-378: Pre-prompt for "*" when browsing in a launch configuration
• P3-381: Remove obsolete "Profiling" button on launch configuration
• P3-382: Make the new single-port debugger connection standard
• P3-389: Replace tree-based (JTB) picture parser with a tree-less CongoCC parser
• P3-396: Editor should use the configured diagnostic threshold
• P3-403: Allow LENGTH OF literal
• P3-404: Allow "WIN32DLL" to precede USING arguments in the PROCEDURE DIVISION header
• P3-426: Enable canceling build jobs
• P3-428: P3 Utility handles required Java option to run with 11 and 17
• P3-430: Replace panic with more meaningful error message in p3 utility
• P3-437: Add return File to beforeLoad file listener method
• P3-450: Update FFM support to JEP 434
• P3-456: PICTUREs with large repeat count(s) can consume large amounts of memory and compile time
• P3-457: Allow specification of minimum record size for trailing suppressed LINE SEQUENTIAL output
• P3-463: Remove all strictfp support in P3/COBOL
• P3-464: Deprecate the Decimal.canonicalOf() methods and always return a normalized int[] for valueOf methods

✨ New Features

• P3-49 Use the incubating Foreign Memory Access (JEP 412) capability as low-level direct store for native memory on Java 17
• P3-361 P3-Utility ships now arm64-Version for Darwin, Linux and Windows
• P3-366 Implement the project -> clean menu item
• P3-393 Add single-key toggle of debug lines
• P3-459 Expand the zoned decimal validation to include arithmetic operand items

🔧 Technical tasks

• P3-77 Complete syntax implementation for 2014 Report Writer
• P3-179 Implement the 2014 date/time intrinsic functions
• P3-180 Implement the 2014 constant value functions
• P3-181 Implement the 2014 arithmetic functions

🚀 Epics

• P3-196 Use the interface/impl model to hide public methods that should not be used by external developers