Support for JCL Datasets

The Mainframe Analyzer is able (in CAST AIP ≥ 8.3.25) to detect the following specific types of JCL Dataset, which will be visible in CAST Enlighten, Architecture Checker and CAST Transaction Configuration:

//GDGFIL DD DSN=MYTELCO.COBDYNSQ.GDG(+1)

//SYSTSIN  DD  DSN=MY.FILE.PDS(MBR)

DBD NAME=DBDCOMP1,ACCESS=HISAM
DATASET DD1=CASTCMP1,DEVICE=3380

PCB TYPE=DB,NAME=DBDCOMP1,KEYLEN=3,PROCOPT=A,PCBNAME=DEPTPCB

//CASTCMP1 DD DSN=MYTELCO.IMSHISAM.DATA

PCB TYPE=GSAM,NAME=GSASEQ,PROCOPT=A,PCBNAME=GSAPCB

//GSASEQ DD DSN=MYTELCO.IMSGSAM.DATA

SELECT EMPDATA ASSIGN TO VSAMF
ORGANIZATION IS INDEXED
ACCESS IS SEQUENTIAL
RECORD KEY IS EMPDATA-EMPNO.

//VSAMF DD DSN=MYTELCO.EMPDATA.VSAM

DSNAME=&&dsname

DSNAME=&&dsname(member)

No DSNAME parameter

Support for IMS/DC

See Mainframe - IMS DC support.

Support for IBM MQSeries

The Mainframe Analyzer (both the extension and the embedded analyzer in AIP Core ≥ 8.3.16) supports the publisher/subscriber mode and point-to-point mode for IBM MQSeries. Publisher/Subscriber objects will be generated and Call links between Cobol objects and IBM MQ objects and between IBM MQ objects and Cobol objects will be generated by the Web Services Linker extension - you must ensure that v. ≥ 1.6.8 of this extension is installed, otherwise no links will be generated.

Main supported patterns

Point-to-point: MOVE MQOT-Q TO MQOD-OBJECTTYPE

In point-to-point, message producers are called senders and message consumers are called receivers. Senders produce messages to a queue, and receivers asynchronously consume messages from that queue. For point-to-point to work, connected applications need to know the name of the queue through which they interact. A queue could have a single receiver or be scaled to many, in which case each message is only consumed by one receiver, distributing the workload across them all. This style of messaging is built around the concept of message queues, and around the processing of messages by a single consumer.

Publisher/Subscriber: MOVE MQOT-TOPIC-Q TO MQOD-OBJECTTYPE

The producer of a message is known as a publisher and message consumers are known as subscribers. The publishing and subscribing applications within the infrastructure agree on the name of a topic. For a consumer to signal that they want to receive messages on that topic, they create a subscription to it. Any message published to a topic will be delivered to all the subscriptions, so every subscriber gets a copy. There could be many publishers and many subscribers to each topic, MQ handles the delivery of messages between all of them. For example:

Support for links between different technologies

The Web Services Linker extension will take all IBM MQ publisher and IBM MQ subscriber (of all technologies). Then it will check if they have the same:

• queue manager connection.
• queue name
• at least one topic from the topic list. 

For example:

• Publisher TOTO publishes the topics (A, B, C)
• Subscriber TOTO subscribes to the topics (A, D, E) with the same queue manager so in this case a link between publisher and subscriber is created.

API support

The Mainframe Analyzer supports MQI calls and dynamic calling of IBM MQ, see: https://www.ibm.com/docs/en/ibm-mq/8.0?topic=zos-dynamically-calling-mq-stub.

• Batch environment: 
  • CONNECT: CSQBCONN, CSQBCONNX
  • OPEN: CSQBOPEN
  • GET: CSQBGET, CSQBSUB
  • PUT: CSQBPUT, CSQBPUT1
• CICS environment: 
  • CONNECT: CSQCCONN, CSQCCONNX
  • OPEN: CSQCOPEN
  • GET: CSQCGET, CSQCSUB
  • PUT: CSQCPUT, CSQCPUT1
• IMS environment: 
  • CONNECT: MQCONN, MQCONNX
  • OPEN: MQOPEN
  • GET: MQGET, MQSUB
  • PUT: MQPUT, MQPUT1

Automatic support of CMQODV copy book IBM MQ

IBM provides some default .cpy files for object queue name variables, topic name variables or queue manager name variables and sometimes these copybooks are not included in source code deliveries. Note that the file CMQODV is automatically supported.

Example basic Publisher/Subscriber

Publish a topic:

01 OBJECT-DESCRIPTOR.
	COPY CMQODV.
MOVE MQOT-TOPIC TO MQOD-OBJECTTYPE.
MOVE MQOD-VERSION-4 TO MQOD-VERSION.
MOVE ‘Fruit/Vegetal’ TO TARGET-TOPIC.
SET MQOD-OBJECTSTRING-VSPTR TO ADDRESS OF TARGET-TOPIC.
MOVE 18 TO MQOD-OBJECTSTRING-VSLENGTH.
...
DD MQOO-OUTPUT
        MQOO-FAIL-IF-QUIESCING GIVING OPTIONS.

CALL 'MQOPEN' USING HCONN,
              OBJECT-DESCRIPTOR,
              OPTIONS,
              Q-HANDLE,
			  MQCC, 
			  REASON.

CALL 'MQPUT' USING HCONN, 
			Q-HANDLE, 
			MESSAGE-DESCRIPTOR, 
			PMOPTIONS, 
			BUFFER-LENGTH, 
			BUFFER, 
			MQCC, 
			REASON.

Subscribe to a topic:

01 SUB-DESCRIPTOR.
	COPY CMQSDV.
ADD MQSO-CREATE MQSO-MANAGED MQSO-FAIL-IF-QUIESCING
									GIVING MQSD-OPTIONS.
MOVE ‘Vegetal/Meal’ TO TARGET-TOPIC.
SET MQSD-OBJECTSTRING-VSPTR TO ADDRESS OF TARGET-TOPIC.
MOVE 18 TO MQSD-OBJECTSTRING-VSLENGTH.
...
CALL 'MQSUB' USING HCONN,
			SUB-DESCRIPTOR,
			Q-HANDLE,
			SUB-HANDLE,
			MQCC,
			REASON.

CALL 'MQGET' USING HCONN,
			Q-HANDLE,
			MESSAGE-DESCRIPTOR,
			GMOPTIONS,
			BUFFER-LENGTH,
			BUFFER,
			DATA-LENGTH,
			MQCC,
			REASON.

Result in CAST Enlighten:

Some main properties are available:

Request/Reply method

The Request/Reply is described by IBM here: https://www.ibm.com/docs/en/was/8.5.5?topic=server-request-reply-messaging-using-websphere-mq. Just as in the send-and-forget pattern sample, this request/reply sample contains two programs. The first one sends a request message to a queue (the REQUEST queue) and waits for a response in another queue (the REPLY queue). The second program acts as the replier and it starts reading messages from a queue (the REQUEST queue). Whenever a message is put onto that queue, it sends a generic response to the REPLY queue.

Example:

049833 01 WS-MQ-FIELDS.
049834 03 WS-PGM1 PIC X(8) VALUE SPACES.
049835 03 WS-MQ-HCONN PIC S9(9) BINARY.
049836 03 WS-OPEN-OPTIONS PIC S9(9) BINARY.
049837 03 WS-MQ-HOBJ PIC S9(9) BINARY.
049838 03 WS-MQ-RC PIC S9(9) BINARY.
049839 03 WS-MQ-RC-DISPLAY PIC 9(18).
049840 03 WS-MQ-REASON PIC S9(9) BINARY.
049850 03 WS-MQ-REASON-DISPLAY PIC 9(18).
049900**** 03 WS-QUEUE-MANAGER PIC X(48) VALUE 'MGT0'.
049900 03 WS-QUEUE-MANAGER PIC X(48) VALUE 'MGP0'.
050000 03 WS-REQUEST-QUEUE-NAME PIC X(48) VALUE
050100 'TE.CDS.REQUEST'.
050200 03 WS-REPLY-QUEUE-NAME PIC X(48) VALUE
050300 'TE.CDS.REPLY'.

The Cobol program (publisher) OPENS the REQUEST queue and PUT the message:

236500 3330-MQ-PUT-PROCESS.
236600*****************************************************************
236700* THIS PARA PERFORMS THE REQUEST QUEUE CONNECTION AND ALSO THE
236800* DATA FROM THE TECMQSTU COPYBOOK TO THE CDS.
236900*****************************************************************
237000
237100     PERFORM 3331-OPEN-REQUEST-QUEUE
237200        THRU 3331-EXIT
237300
237400     PERFORM 3332-PUT-MESSAGE
237500        THRU 3332-EXIT
237600
237700     PERFORM 9100-CLOSE-REQUEST-QUEUE
237800        THRU 9100-EXIT.
237900
238000 3330-EXIT.
238100     EXIT.
238200
238300 3331-OPEN-REQUEST-QUEUE.
...
241000     MOVE  WS-REQUEST-QUEUE-NAME      TO TEMQPUT-REPLYTO-QUEUE
...
241900     MOVE TEMQPUT-REPLYTO-QUEUE       TO MQOD-OBJECTNAME OF
242000                                         MQM-OBJECT-DESCRIPTOR
...
241000     MOVE  WS-REQUEST-QUEUE-NAME      TO TEMQPUT-REPLYTO-QUEUE
...
241900     MOVE TEMQPUT-REPLYTO-QUEUE       TO MQOD-OBJECTNAME OF
242000                                         MQM-OBJECT-DESCRIPTOR
...
246200 3332-PUT-MESSAGE.
246300*****************************************************************
246400* THIS PARA PUTS THE MESSAGE INTO THE REQUEST QUEUE.
246500*****************************************************************
...
247900     MOVE TEMQPUT-REPLYTO-QUEUE       TO MQMD-REPLYTOQ OF
248000                                         MQM-MESSAGE-DESCRIPTOR
248100     MOVE TEMQPUT-REPLYTO-QMGR        TO MQMD-REPLYTOQMGR OF
248200                                         MQM-MESSAGE-DESCRIPTOR
...
249900     CALL 'MQPUT'        USING TEMQPUT-HCONN
250000                               TEMQPUT-HOBJ
250100                               MQMD OF MQM-MESSAGE-DESCRIPTOR
250200                               MQPMO OF PM-OPTIONS-O
250300                               TEMQPUT-PUT-DATA-SIZE
250400                               TEMQPUT-PUT-DATA
250500                               WS-MQ-RC
250600                               WS-MQ-REASON

The Cobol Program (subscriber) tries to get the reponse from the request (PUT). Then the response message could be resent to the publisher by REPLY Queue:

252700 3340-MQ-GET-PROCESS.
252800*****************************************************************
252900* THIS PARA PERFORMS THE REPLY QUEUE CONNECTION AND ALSO GETS THE
253000* REPLY MESSAGE FROM THE CDS IN TECMQSTU COPYBOOK.
253100*****************************************************************
253200
253300     PERFORM 3341-OPEN-REPLY-QUEUE
253400        THRU 3341-EXIT
253500
253520     DISPLAY '=> MQGET CORREL ID => ' WS-MSGID
253600     PERFORM 3342-GET-MESSAGE
253700        THRU 3342-EXIT UNTIL WS-END-OF-PROCESSING
253800
253900     PERFORM 9200-CLOSE-REPLY-QUEUE
254000        THRU 9200-EXIT.
254100
254200 3340-EXIT.
254300     EXIT.
254400
254500 3341-OPEN-REPLY-QUEUE.
...
257200     MOVE  WS-REPLY-QUEUE-NAME        TO MQOD-OBJECTNAME OF
257300                                         MQM-OBJECT-DESCRIPTOR

Supported behavior

The Mainframe Analyzer supports the main REQUEST queue, however publisher and subscriber items defined by the REPLY queue will not be created by the analyzer.

Limitations

• When complex situations arise (i.e. due to the use of if_else, evaluate, when etc.), results may be ambiguous and potentially erroneous.
• If the queue names do not detect the request and reply queues, the analyzer cannot correctly detect the REQUEST Publisher/Subscriber queue name. Note that the analyzer attempts to detect items using REQUEST/REPLY keywords and if none are found, all publisher/subscribers are created (no REPLY publishers/subscribers are removed).

Unknown publisher/Unknown subscriber

When the analyzer cannot find the correct resolution between objects, the unknown publisher and unknown subscriber objects will be created, including the ID of the item. Note however that no links are created between unknown publisher and unknown subscriber objects.

Objects

MQ Publisher and MQ Subscriber objects are created by the Mainframe Analyzer:

	Subscriber IBM MQ
	Publisher IBM MQ

Links

Call links will be generated by the Web Services Linker extension - you must ensure that v. ≥ 1.6.8 of this extension is installed, otherwise no links will be generated:

• between Cobol objects and IBM MQ objects
• between IBM MQ objects and Cobol objects

Support for VSAM files

• The analyzer will detect VSAM files in COBOL programs, just like other files, however, no specific object type for VSAM will be resolved in the results. Instead, VSAM files are resolved as follows (see Mainframe - Analysis results):
  
  • COBOL: File Link objects 
  • JCL: Dataset objects
• Some structural rules have been adapted to take into account this VSAM files, for example:
  • Avoid using SORT - 5058
  • Avoid using MERGE - 5060

  • File descriptor block must be defined with 0 record - 7366

• The analyzer does not analyze the VSAM system tables that contain technical information about file system management.
• Support for commands in "SYSIN" clauses (in CAST AIP ≥ 8.3.24), for example:
  • ALLOCATE
  • ALTER
  • DEFINE
  • DELETE
  • EXAMINE
  • LISTALC
  • LISTCAT
  • LISTDS
  • PRINT
  • REPRO
  • VERIFY
• Support for If IDCAMS utility and VSAM data-set types (for Cobol and JCL) when they call indexed, relative and sequential organisation (in CAST AIP ≥ 8.3.24):

  • Entry-sequenced data set (ESDS)

  • Key-sequenced data set (KSDS)
  • Relative-record data set (RRDS)
  • Linear data set (LDS) (since 1.0.14-funcrel)
• Support since Mainframe Analyzer 1.0.14 funcrel:
  • Support to abbreviations command VSAM e.g:
    • DEFINE is DEF
    • CLUSTER is CL
    • EXPORT is EXP, ...
  • By default, the VSAM data-set types is KSDS
  • Support property for KEYS in KSDS VSAM

File Management

IF condition A
<do this>
END-IF

IF condition B
<do that>
END-IF

//STEP1 EXEC PGM=MYPROG1
//MYDD1 DD DSN=MY.DATA.SET
//MYDD2 DD DSN=*.MYDD01
//STEP2 EXEC PGM=MYPROG2
//MYDD3 DD DSN=*.STEP1.MYDD1

Links between JCL and JEE technologies

AIP Core ≥ 8.3.22 and the Mainframe Analyzer extension support links from JCL Steps to Java Methods through the creation of a JCL_To_JavaProgram object. The JCL_To_JavaProgram object is created when the following utilities are detected in the code:

• JVMLDM
• JZOSVM
• BPXBATCH
• BPXBATSL

Example code with the JVMLDM utility:

//LMGHWRLD JOB (MY,ACCOUNTING,INFO),'HELLO WORLD', 
//   CLASS=A,MSGCLASS=H,REGION=0M,NOTIFY=&SYSUID     
//STEP1    EXEC PGM=JVMLDM60,                        
//   PARM='com.foo.bar.HelloWorld'      
//STEPLIB  DD DSN=<MY.LIBRARY.PATH>,DISP=SHR
//SYSPRINT DD SYSOUT=*                               
//SYSOUT   DD SYSOUT=*                               
//STDOUT   DD SYSOUT=*                               
//STDERR   DD SYSOUT=*                               
//STDENV   DD *                                      
. /etc/profile                                       
. ~/.profile                                         
export CLASSPATH=~/HelloWorld                        
for i in ~/HelloWorld/*.jar; do                      
    export CLASSPATH=$i:$CLASSPATH                   
    done                                             
//

Result:

//JCLTEST JOB (8452200000),'COBTEST',CLASS=M,MSGCLASS=P,USER=JCH
//*
//PS10 EXEC PGM=IKJEFT01,
//STEPLIB DD DSN=ENV.APPL.LOADLIB,
// DISP=(SHR,KEEP,KEEP)
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
*//SYSTSIN DD **
DSN SYSTEM(DB2P)
RUN PROGRAM(COBTEST) PLAN(TESTPLAN) PARM('1')
END
//* 

//JCLTEST JOB (8452200000),'COBTEST',CLASS=M,MSGCLASS=P,USER=JCH
//*
//PS10 EXEC PGM=IKJEFT01,
//STEPLIB DD DSN=ENV.APPL.LOADLIB,
// DISP=(SHR,KEEP,KEEP)
//SYSOUT DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD DSN=ENV.APPL.PARMLIB(PARMTEST),
// DISP=(SHR,KEEP,KEEP)
//*
External parameter file PARMTEST:
DSN SYSTEM(DB2P)
RUN PROGRAM(COBTEST) PLAN(TESTPLAN) PARM('1')
END

Support for REPLACE statement

The Replace statement (used to replace some keywords in COBOL programs) is supported in the Mainframe Analyzer extension ≥ 1.0.10-funcrel.

PARA-1.
    PERFORM PARA-TERMINATION.
PARA-2.
...
PARA-TERMINATION.
   GOBACK.

PARA-1.
    PERFORM PARA-TERMINATION.
PARA-2.
...
PARA-TERMINATION.
  IF <condition>
    GOBACK.

Cobol data links with file handling COBOL statement

See Cobol data links with file handling cobol statement.

Sensitive data in Mainframe Analyzer

Supported in the Mainframe Analyzer extension ≥ 1.0.10-funcrel. The Mainframe Sensitive Data extension (com.castsoftware.mainframe.sensitivedata) is required. Some dataset and IMS Segment will raise an indicator property if these are a sensitive data.

Unknown / unresolved objects

An unknown unresolved object generally means that there is a missing component, directly or not. Usually unknown/unresolved objects are listed in the analysis log with a "Mainframe.09" warning message:

Warning MODULMSG ; Job execution Mainframe.09: Cannot resolve Entry or program

It is important to distinguish objects which have associated source files from the other objects which do not have a source file.

For instance, a program, a copybook, a screen map, a JCL job or a JCL procedure all have an associated source file. If they are involved in a log message which indicates they are unresolved, then you can immediately assume they are missing. On the contrary, data structures, paragraphs, and DD Names do not have a source file. Instead they are defined in a program or in a copybook.

So why is the analyzer not able to find a component? Because it has not been delivered or because the analyzer does not have any information about its location (source file directories or working folders). In the first case you must ask the application team to deliver it. You will find the complete list of missing components at the end of the analysis log. In the second case you must modify the parameters of the analysis unit.

You can also see missing components using the CAST Enlighten tool. The unknown / unresolved objects are classified in "Unknown" folders and you can easily find them with the Object Browser.

There are technical/system/utility programs which are called by application programs and JCL jobs. The Mainframe Analyzer can also produce "Unresolved objects" messages about them. Their name usually begins with the "DFH", "DSN", "IKJ", "DFS" or "IEB" prefixes. The "DFH" programs are dedicated to CICS, the "DSN" and "IKJ" programs are usually dedicated to DB2 and the "DFS" programs are dedicated to IMS. The JCL job can also invoke utilities such as the IEB family, IEF family or IDCAMS, FILE-AID… Do not ask the application team to deliver them because they do not have the corresponding source files. If they are used to run another program in a JCL job then you should change the analysis parameters. Otherwise, you can ignore the messages.

Cobol Data object Bookmarks

Currently the Mainframe Analyzer is designed such that bookmarks between Cobol Data object do not point to the exact line in which the data is being written to the Cobol Data object (for example MOVE statements) Instead the bookmark is placed at the start of the Cobol Data object.