Page tree
Skip to end of metadata
Go to start of metadata

On this page:

Target audience:

Users of the extension providing Enterprise PL/I for z/OS support.

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

Extension ID

com.castsoftware.pl1

What's new?

Please see PL1 1.1 - Release Notes for more information.

Description

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

In what situation should you install this extension?

If your application contains source code written using PL/I and you want to view these object types and their links with other objects, then you should install this extension.

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/OSSupported

5.x

(tick)

4.x

(tick)

3.x

(tick)

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)
(tick)
Quality and Sizing(tick)

CAST AIP compatibility

This extension is compatible with:

CAST AIP release

Supported

8.3.x

(tick)
8.2.x(tick)

Supported DBMS servers

DBMSSupported?
CSS(tick)
Oracle(tick)
Microsoft SQL Server(error)

Prerequisites

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

Download and installation instructions

Please see:

The latest release status of this extension can be seen when downloading it from the CAST Extend server.

Packaging, delivering and analyzing your source code

The process of preparing and delivering your source code is described below:

Source code preparation

The following file extensions are recognised by the CAST Delivery Manager Tool/AIP 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 AIP 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.

Discovery

The presence of at least one .PLC or .PLI file in a folder (including post preprocessing) will mean that CAST will "discover" one PL/I project for each folder containing a .PLC or .PLI file and in turn one corresponding Analysis Unit for each folder will be created.

Packaging and delivery

CAST Delivery Manager Tool

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)$

AIP Console

The process is simple using AIP Console - see Advanced onboarding - add a new version and deliver source code and also Advanced onboarding - validate and accept the version

  • 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:

Click to enlarge

Analysis configuration and execution

CAST Management Studio

Accept and deploy the Version in the CAST Management Studio. Analysis Units will be created automatically relating to the PL/I source code:

Click to enlarge:

Run a test analysis on the Analysis Unit before you generate a new snapshot.

If your PL/I code calls Cobol programs, you will need to add a dependency to a "Mainframe" Analysis Unit. Note that because of a limitation in the Universal Analyzer, the link created will be of type "useLink" instead of "callProgLink".

AIP Console

Run an analysis/snapshot - see:

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

Parsing 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

IconMetamodel description

PLI DB2 Table

PLI Error Block

PLI FileStructure

PLI Function

PLI MainProcedure

PLI Procedure

PLI Project

PLC

IconMetamodel description

PLC DB2 Table

PLC FileStructure

PLC Function

PLC Include

PLC Procedure

PLC Project

Structural Rules

The following structural rules are provided:

You can also find a global list here:

https://technologies.castsoftware.com/rules?sec=t_1004000&ref=||

Limitations

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 AIP)

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.

  • No labels