PL1 1.1

Summary: This document provides information about the extension providing Enterprise PL/I for z/OS support.

Extension ID

com.castsoftware.pl1

What's new?

Description

This extension provides support for applications written using Enterprise PL/I for z/OS languages.

Supported Versions of PL/I

Although this extension is officially supported by CAST, please note that it has been developed within the technical constraints of the CAST Universal Analyzer technology and to some extent adapted to meet specific customer needs. Therefore the extension may not address all of the coding techniques and patterns that exist for the target technology and may not produce the same level of analysis and precision regarding e.g. quality measurement and/or function point counts that are typically produced by other CAST AIP analyzers.

This version of the extension provides support for:

Enterprise PL/I for z/OS	Supported
5.x
4.x
3.x

Function Point, Quality and Sizing support

This extension provides the following support:

Function Points (transactions): a green tick indicates that OMG Function Point counting and Transaction Risk Index are supported
Quality and Sizing: a green tick indicates that CAST can measure size and that a minimum set of Quality Rules exist

Function Points (transactions)
Quality and Sizing

Compatibility

CAST Imaging Core release	Supported
8.3.x

Prerequisites

An installation of any compatible release of AIP Core (see table above)

Download and installation instructions

The extension will be automatically downloaded and installed in CAST Console when you deliver PL/1 code. You can manage the extension using the Application - Extensions interface:

Prepare and deliver the source code

The following file extensions are recognised by CAST Console:

.PLC
.PLI

However, PL/I source code files can sometimes be created with any extension (most commonly a .TXT extension) or no extension at all. If these type of files are encountered during the source code delivery process, CAST will try to determine whether the file is a valid PL/I source file and if so, a built-in preprocessor will change the extension to .PLI or .PLC (for files with extensions other than .PLI or .PLC, such as .TXT) and will add a .PLI or .PLC extension for files with no extension.

Please note the following recommendations and notes about source code:

It is important to organize the PL/1 source code in a specific way otherwise the preprocessor will not be launched during the delivery:
- In general, CAST recommends ensuring that all PL/I source code (.PLC / .PLI / .TXT / files with no extension) is located in one single folder dedicated to PL/1 in the delivery. You can also use multiple folders for your PL/1 source code if necessary. Other source code for other technologies should be located in separate dedicated folders.
- When using CAST Console, to trigger the PL/1 preprocessor, the presence of at least one .PLC or .PLI file in a folder in the delivery (including the root if this is used) is OBLIGATORY - this is not the case when delivering source code using the CAST Delivery Manager Tool when the preprocessor will always be triggered.
- Do not mix other file types with the PL/1 source code in the same folder (including the root if this used) - these other files may be processed by the PL/1 preprocessor rendering them corrupt and causing the subsequent analysis to fail.
The PL/I extension ignores empty files and they will not be considered as valid source code files.
Binary files should be avoided since it is not always possible to detect whether a given file is binary or not. Presenting binary files in the source code delivery will not result in a packaging failure, but an error message can be expected in the packaging/extraction log.

Source code discovery

A discoverer is provided with the extension to automatically detect PL/1 code: a PL/1 project will be discovered for the package's root folder when at least one .PLC or .PLI file in a folder (including post preprocessing) is detected in the root folder or any sub-folders. For every PL/1 project located, one Universal Technology Analysis Unit will be created:

Deliver the source code

Using CAST Console

Upload the ZIP file containing your Application source (or define a folder in which to deposit your source code)
Configure any file/folder exclusions and objectives
If you want to inspect the version (recommended), disable the analysis/snapshot at this point
Start the delivery process - the extension will be auto-downloaded during this phase.
Validate and accept the version - inspect the delivered files and ensure that you have an Analysis Unit for your PL/I source code:

Using CAST Management Studio

Click here to expand...

Create a new Version and create a new Package for your PL/I source code using the PL/1 option in the vendor specific repository section and choose the location of your source code:

Now choose the PL1 Library Files option and click Finish:

Configure the Package in the Package configuration tab - at a minimum you need to specify the location of your target PL1 library files in the Folder path field (for example a location on disk):

Click to enlarge:

Please do not change the option selected in the SCM or File system targeted dropdown - it must be set to PL1 library files. Selecting another option will cause erroneous results to be produced.

Run the Package action: the CAST Delivery Manager Tool will discover any "projects" related to the PL1 application source code:

Click to enlarge:

Before delivering the source code, check the packaging results.

Excluding files

If you need to exclude certain files from being packaged (since files from other technologies can be present in PL/I source code), you can use regular expressions in the Advanced Extractions settings > Files or folders to ignore section. Please ensure that you enter the regular expression in the File Selection Regex field (marked in black) and not in the standard field (marked in red):

Click to enlarge

The matching engine uses https://docs.oracle.com/javase/7/docs/api/java/util/regex/Matcher.html#matches() and therefore follows all the requirements of this API. If a given regular expression is correct, and if it matches the entire file path, that file will be excluded.

Examples:

To exclude all files that have any extension: ^.*\.[a-zA-Z0-9]+$
To exclude all files that have any extension but include pli extension: ^.*\.[a-zA-Z0-9]+(?<!\.pli)$
To exclude all files that have any extension but include pli and txt extension: ^.*\.[a-zA-Z0-9]+(?<!\.pli)(?<!\.txt)$

Logging mechanism

Analysis log files

Analysis logs are stored in the default locations used by the CAST Management Studio/AIP Console:

Error/Warning Message	Action
Unable to find the object end for type 'XXXXXXX'	This is caused by complex source code that makes the engine miss the end of the object, whereas the begin of object type was captured. Object won't be created in Analysis Service, will lead to incomplete analysis. Issue must be reported to CAST Support, along with source code (original source file + preprocessed source code) to allow reproduction and investigation. A few such warnings for object types like PLIProcedure, PLCProcedure, PLIFunction could be acceptable. Same warning for PLIMainProcedure is problematic : the whole program is not saved in Analysis Service.
An unnamed object of type 'PLIWhenCall' has been detected	This is because PLIWhenCall has no specific name, as such, the CAST framework will give them the name "unnamed". You can safely ignore this warning.
Duplicate object of type 'PLIWhenCall' has been detected: '<unnamed>' Duplicate object of type 'PLIErrorBlock' has been detected	As mentioned above, PLIWhenCall and PLIErrorBlock have no specific name and are automatically given the name "unnamed" by CAST - as such multiple objects with the name "unnamed" will exist and will cause this error. You can safely ignore this warning. Same for PLIProcSubscriptedVar object type.
Duplicate object of type 'PLIProcedure' has been detected Duplicate object of type 'PLCProcedure' has been detected	PLIProcedure and PLCProcedure are supposed to be unique within the same source file. So such warning is the sign of an incorrect object type identification. Issue must be reported to CAST Support.
end of string ''' not found end of string '[']' not found File skipped	UA engine did not find the end of a string, whereas the begin of the string was captured. This generally leads to a second warning : File skipped, meaning the source file and contained objects have not been saved in Analysis Service. On large applications, a few such warnings could be acceptable. Otherwise, issue must be reported to CAST Support, along with source code (original source file + preprocessed source code) to allow reproduction and investigation.
end of comment '[\*][/]' not found	Alone, this warning can be safely ignored. Check if other warnings are present for the same source file.
Could not calculate code depth correctly for file File: <file path> Could not calculate code depth correctly for file, added <TAG> File: <file path> where TAG can be $END or $$END.	The analyzer is not capable of detecting the source code depth correctly.
PL1 Extractor Version: <version>	A simple information message to help identify the version of the extractor that is being used.

PL/I Preprocessor

PL/I source code needs to be preprocessed so that CAST can understand it and analyze it correctly. This source code preprocessing is actioned automatically. In other words you only need to package, deliver and launch an analysis/generate a snapshot for the preprocessing to be completed.

Note that as part of the source code pre-processing phase, from PL1 1.0.5 onwards, CAST will now add "$$" to all PL/I source code just prior to the ";". For example:

Original source code

someproc:proc;

Source code after pre-processing in ≥ 1.0.5

someproc:proc$$;

The impact of this change is as follows:

When upgrading to PL1 ≥ 1.0.5, existing objects will be shown as updated when a post upgrade snapshot is run.
There will be a reduction in the number of messages of the type "end of object of type <PLC\PLIProcedure|Function> not found" that were previously displayed in the log.

This change has been implemented because of a limitation in the analyzer with regard to the way object start and end patterns are handled. In PL/I, object start and end patterns do not match (contrary to most other languages, such as PHP where { and } are used) and therefore the analyzer is not able to correctly identify when an object ends.

Analysis failures

The PL1 extension needs to process all the file extensions delivered in the version because PL/I files can have any extension. During this parsing if the file is from a different technology, a failure will occur. The file that has caused the failure will be stored under a "ParsingFailures" folder at the package level and the file extension of the file will be changed to "pfail". A reason for the failure will also be recorded in each subfolder with name of the exception that caused it. For example StringCommentProcessorException:

What results can you expect?

Objects

PL/I

Icon	Metamodel description
	PLI DB2 Table
	PLI Error Block
	PLI FileStructure
	PLI Function
	PLI MainProcedure
	PLI Procedure
	PLI Project

PLC

Icon	Metamodel description
	PLC DB2 Table
	PLC FileStructure
	PLC Function
	PLC Include
	PLC Procedure
	PLC Project

Structural Rules

The following structural rules are provided:

1.1.6-funcrel	https://technologies.castsoftware.com/rules?sec=srs_pl1&ref=\|\|1.1.6-funcrel
1.1.5-funcrel	https://technologies.castsoftware.com/rules?sec=srs_pl1&ref=\|\|1.1.5-funcrel
1.1.4-funcrel	https://technologies.castsoftware.com/rules?sec=srs_pl1&ref=\|\|1.1.4-funcrel
1.1.3-funcrel	https://technologies.castsoftware.com/rules?sec=srs_pl1&ref=\|\|1.1.3-funcrel
1.1.2-funcrel	https://technologies.castsoftware.com/rules?sec=srs_pl1&ref=\|\|1.1.2-funcrel
1.1.1-funcrel	https://technologies.castsoftware.com/rules?sec=srs_pl1&ref=\|\|1.1.1-funcrel
1.1.0-funcrel	https://technologies.castsoftware.com/rules?sec=srs_pl1&ref=\|\|1.1.0-funcrel

You can also find a global list here: https://technologies.castsoftware.com/rules?sec=t_1004000&ref=||.

Known Limitations

PL/1 integration

PL/I integration with Database is supported.
PL/I integration with IMS DB, IMS DC, CICS is not supported.

Rules searching for the use of the builtin DATE function

The following two rules do not work as expected. Instead of searching for use of the DATE builtin function, they search for inclusion of the function. This is a limitation. These rules are disabled from 1.1.0-funcrel "out of the box". If they are enabled, it will list all the files that include DATE function through "declare DATE BUILTIN;" statement rather than actual use of function DATE.

Avoid Main procedures using the DATE builtin function (PL1) - 1001164
Avoid Main procedures using the DATE builtin Function via include PLC (PL1) - 1001166

Metrics Assistant (embedded in CAST Imaging Core)

Searches not limited only to embedded SQL

The MA (Metric Assistant) which is used for metric search cannot search only in embedded SQL. In order to overcome this limitation the processing for some metrics/rules has been moved to the extractor in 1.1.0-funcrel. However, the following rules still can be affected by this limitation and may produce false violations:

Avoid Main Procedures having queries with joins on more than 4 Tables (PL1) - 1001128
Avoid Main Procedures with High Raw SQL Complexity (SQL complexity greater than X) (PL1) - 1001130

Cannot calculate metric excluding comments

The MA (Metric Assistant) which is used for metric search cannot search correctly while excluding comments especially if comments start or end adjacent to the keyword. If such a condition exists, random false violations may occur.