Adding Files to Project Folders

After you create the project and its folders, the files to be analyzed must be added to the appropriate project folders. Following are the project folders and the sources that can be placed in each one of them.
Note:
  • Project folders depend on the type of selected project at project creation time. Therefore, for some projects, some of the following folders are not available.
  • When adding files, if the limit of 40000 files is reached, additional virtual folders are created at the project's level. They do not have correspondent on disk and they cannot be deleted manually from IBM® AD Build Client. The additional virtual folders are different than the existing virtual folders by having a special naming convention, suffixed by @&@<incremental_number>. Examples of additional virtual folders for zOS Cobol:
    zOS Cobol@&@1
    zOS Cobol@&@2
The project folders that are created, differ according to the environment selected as shown in the following table:
Environment Folders- Description
z/OS®
  • AAuto Scheduling - A-AUTO Dataset Flag Report.
  • AAuto Scheduling - A-AUTO Scheduling programs.
  • ADS Dialog - N/A.
  • ADS Map - N/A.
  • ADS Process - ADS Process files.
  • API Config - Files containing configurations for the API calls.
  • Assembler - Assembler files.
  • Assembler Include - "Assembler include" files.
  • Assembler Macro - Assembler macros.
  • BMS - BMS assembler definitions (relevant only for CICS®® projects).
  • Cobol IDMS - Cobol IDMS files.
  • Cobol IDMS Record - Cobol IDMS Record files.
  • Cobol Include - COBOL copybooks and include files.
  • Configuration - CSD files.
  • Configuration - IMS/T PGM
  • Configuration - PGM Aliases.
  • Control-M - XML files (exported from Control-M Enterprise Manager) containing jobs and conditions.
  • Data area - Natural data area that includes Local Data Area, Parameter Data Area, and Global Data Area.
  • DBD - IMS DBD files.
  • DT Cobol - Data Type Cobol files.
  • DT Cobol pre-compiled - Pre-compiled data type Cobol files.
  • IMS MAP - MFS files (relevant for IMS projects only).
  • JCL - JCL Jobstream files.
  • JCL Control files - JCL Control files.
  • JCL Include - JCL Include files.
  • JCL Procs - JCL procedure files.
  • MQ - MQ configuration files.
  • Natural - Natural programs
  • Natural DDM - Natural DDM files.
  • Natural Include - Natural include files.
  • Natural Map - Natural map definitions.
  • PL1 - PL/I programs.
  • PL1 IDMS Record - PL/I IDMS record files.
  • PL1 Include - PL/I copybooks and include files.
  • PreProc Before - User's original sources.
  • PreProc Config - Files containing mappings between the folders of the before, meta and after files.
  • PreProc MetaData - Files that map the before files with after files.
  • PSB - IMS PSB files.
  • Schema - IDMS schema
  • Subschema - IDMS Sub-schema.
  • zOS Cobol - Simple Cobol files.
Some environment files are not added directly to one of the project folders. Instead, they are put under the project directory on the hard disk. The project directory is the location where the project was created, specified in the path field at project creation time. Following is a list of these environment files.
Files under the project directory on the hard disk
Control files
These files can be placed by default into the CTRL directory that is automatically created under the project directory. Control files must not have any extension in order for IBM AD Build Client to locate them. In case you have several control files with the same name that are taken from different libraries and used by the JCL files according to the search order, create a directory under the project directory for each library. For example, if two control files with the same name that are taken from two libraries LIB1.MYCTRL and LIB2.MYCTRL, create two directories that are named LIB1.MYCTRL and LIB2.MYCTRL under the default CTRL directory and place each procedure in the corresponding directory. The IBM AD Build Client JCL compiler searches for the right folder according to the search order specified in the JCL.
Note: This procedure is needed only if you have two control files with the same name, in which case they cannot be both put in the default directory CTRL.

The Control files (or the PARM files) are the source members referenced in DD cards in the format of DSN=MY.PDS.NAME(CTRLMMBR). These Control files may contain SORT parameters, or SYSIN data, or Db2® command (if in SYSTSIN card for Db2 invocation programs), all depending on the step they are used in and the DD card name.

The JCL include files are files that are included in the JCL source using the INCLUDE command, e.g.//LABEL001 INCLUDE MEMBER=INCFILE1INCFILE1 is the JCL include member. Usually these will have list of DD cards commonly used together in many JCL sources, and put into one shared file to simplify maintenance in case you want to add/remove/change a DD card. They can also contain full steps.

Procedure files (also known as PROCS)
These files, which are referenced from JCL files, can be placed by default into the SYS1.PROCLIB directory that is automatically created under the project directory. Procedure files must not have any extension in order for IBM AD Build Client to locate them. In case you have several procedure files with the same name that come from different libraries and used by the JCL files according to the search order, create a directory under the project directory for each library. For example, if two procedure files with the same name that are taken from two libraries LIB1.MYPROC and LIB2.MYPROC, create two directories that are named LIB1.MYPROC and LIB2.MYPROC under the project directory and place each procedure file in the corresponding directory. The IBM AD Build Client JCL compiler searches for the right folder according to the search order specified in the JCL.
Note: This procedure is needed only if you have two procedure files or include files with the same name, in which case they cannot be both put in the default directory SYS1.PROCLIB.
PSB files
These files, used only by the IMS application, must be placed in a directory that is named PSB under the project directory. This directory is not created automatically and therefore must be created if needed.
The AAuto scheduling folder
This folder can host two types of files: AAuto scheduling files and AAuto Dataset Flag report files.

Before you run the build process, make sure to set the correct type for the AAuto Dataset Flag report file: In the Project pane, right-click on the Dataset flag report file that is loaded in the AAuto Scheduling folder of the project and select Properties. In the File Properties window, verify that the Type is set to AAuto Dataset Flag Report. (the file type verification can be done either when the file is loaded in the project or at a later moment, but before the build step is run).

The CICS CSD configuration file
A CICS administrator can use the LIST command of CICS utility DFHCSDUP to extract CSD information into a report. The report can be stored under the Configuration virtual folder and can be added to a build project as a CSD type of file. The build process parses the CSD configuration file and stores the information into the MFCICS tables.
The name of the CSD configuration file must have maximum eight characters, because the file name is used as the CICS region name. For more information, see chapter CICS CSD Information Handling.
The IMS transaction mapping file
This configuration file is used to map between IMS transactions and programs. The file must be placed under the Configuration virtual folder in the project. The type of the file must be IMS/T PGM. See the following example of mapping configurations in an IMS transaction mapping file:
TRANSACTION(TRAN1) PROGRAM(PROG1) IMS-TM
TRANSACTION(TRAN2) PROGRAM(PROG2) IMS-TM
The Pgm_Aliases file
This configuration file for aliases is used to specify external alias names coming from outside the source files. The file will be added in the Configuration virtual folder, in the project, with type PGM Aliases. The configuration file for aliases is a comma separated file, having the following format:
* - a commented line starts with '*'
<optional disambiguation file path>, <procedure/program name defined in file>, <alias name 2>, <alias name 3>
In case the alias name is not configured with a file path, the file format is as following:
<program/procedure defined in file>, <alias name 1>, <alias name 2>
* procedure name in case of PLI/I file
PGM Aliases (Configuration) Files Example:
* this is a commented line
\\shared-resoures-dir\Projects\Pgm_Alias_002\PL1\PLI1, PLI1, PLI01, PLI001
\\shared-resoures-dir\Projects\Pgm_Alias_002\PL1\PLI1_1, PLI01, PLI_1, PLI_01, PLI1
PLI2, PLI002, PLI0002
PLI3, PLI03
Note:
  • These program aliases, <program/procedure defined in file>, <alias name 2>, <alias name 3>, can be declared in any order, provided <program/procedure defined in file> exists among the aliases names. Example: if only <alias name 2>, <alias name 3> are present and <alias name 3> is called, while <alias name 2> is not found as a program/procedure definition in any source file, then <alias name 3> will not be replaced with <alias 2> in the call.
  • The first item <optional disambiguation file path> which is the fully-qualified-name of the file, is optional and only needed when the same alias name refers to actually different programs: in the example above, the same program alias name PLI01 refers to two different programs, defined in two different files. If only one fully-qualified-file-names of the two will be present or the two lines meant to be told apart have no alias name in common, the fully qualified file name would not make any difference.
  • If disambiguation between two alias groups is needed, the fully-qualified-file-name of a PL/I file must be added in the 1st position, as it shows in Project > Properties. Example: if the file was added with a network path, the same syntax must be used into the PGM Aliases file.
  • After adding new alias name(s) into the PGM Aliases configuration file, it is recommended to (re)compile both the configuration and the PL/I files, where <procedure/program name defined in file> exists, in this order. Example: configuration file > PL/I file.
    Note: When (re)building the entire project, the configuration file is build first by default.
Important: Currently, the external alias names feature is only available for PL/I programs.
The CheckReportConfiguration file
In Check Report, programs from a z/OS system and subsystems (MQ, CICS, Db2, IMS...) are reported to be missing and it's not possible to load them in IBM AD. Actually, these programs should not be reported as missing since they are part of the system or subsystems. The missing components that need to be excluded from the Missing Component Report can be added in a configuration file.
The file must be placed under the Configuration virtual folder in the project. The type of the file must be Check Exclude. The configuration file for Check Report is a comma separated file. It contains the name of the program, the entity type and program type. The configuration file has the following structure:
IDENTIFIER1, TypeOfEntity1, TypeOfProgram1
IDENTIFIER2, TypeOfEntity2, TypeOfProgram2
Where TypeOfEntity can have the following values:
"PGM" - PROGRAM
"INC" - INCLUDE
"TRN" - TRANSACTION
"CPY" - COPYBOOK
"CTR" - CONTROL
"JOB" - JOB
"MAP" - MAP
"PRC" - PROCEDURE
"DLG" - DIALOG
"PRS" - PROCESS
"DA"  - Data Area
Where TypeOfProgram can have the following values:
"COB" - COBOL
"ASM" - ASSEMBLER
"PLI" - PL1
"NAT" - NATURAL
"JCL" - JCL
"BMS" - BMS
"ADS" - ADS
"ANY" - All the types mentioned above
Example:
ICEGENER, PGM, JCL
IDCAMS, PGM, JCL
IEFBR14, PGM, JCL
TEST1, PGM, COB
JCLINC, INC, JCL
AC01, TRN, COB
AC02, TRN, ANY
COPY1, CPY, COB
INCLUDE, CPY, ANY
CTR1, CTR, JCL
MAPSET:MAP, MAP, BMS
:MAP1, MAP, BMS
PROCJCL, PRC, JCL
NCAMOD, DLG, ADS
ADSAGES, PRS, ADS
DACI, MAP, ADS
DA1, DA, NAT
LAPL1, PGM, PLI
SORT, PGM, JCL
The MQ configuration files
ADDI supports the MQ usage analysis in COBOL programs. During the analysis, each CALL to MQ, such as the MQPUT, MQGET and MQCONN call, is handled and the dynamic values that are passed as Queue Manager name and Queue name are resolved. If the MQ Queue and Queue Manager names can be resolved by using initial values or transitive MOVEs and data lineage within the program, ADDI can resolve the names well; However, if the names come from outside of the program at run time, such as the names that are passed as Linkage Section records or come from Db2 table or file content, ADDI cannot resolve the names and will use default names to indicate the names that cannot be resolved respectively.
To ensure that ADDI can resolve the MQ Queues correctly during the build and display the correct information about MQ usages in ADDI analysis, the following two MQ configuration files can be provided:
  • The MQQueueMgrInfo.txt file is used to map MQ Queue Manager names, which helps ADDI know which Queue Manager name is mapped to a specific connection record variable in the program.
    The file should be a .CSV file with lines to specify the mapping information, including the program name, the variable name that is used in MQ calls for Queue Manager name, and the actual Queue Manager name that is used. For example, the .CSV file should have lines like the following:
    PROGRAM1, HCONN-VAR-NAME, QUEUEMGR1
PROG0340, HCON-REC, QMGR4
  • The MQQueueInfo.txt file is used to map MQ Queue names, which helps ADDI know which Queue name is mapped to a specific connection record variable in the program.
    The file should be a .CSV file with lines to specify the mapping information, including the program name, the variable name that is used in MQ calls for Queue name, and the actual Queue name that is used. For example, the .CSV file should have lines like the following:
    PROGRAM2, HOBJ-VAR-NAME, QUEUE1
PROG0200, HOBJ-VAR-NAME, CRM.Q123
The PgmModuleMap file
This file is used to map between load module and the first program that is called in the module (relevant only for batch applications). By default, IBM AD Build Client assumes the module name and the name of first program that is called are identical. In case they are not identical, a mapping must be described in the PgmModuleMap.txt file, which must be placed under the project directory. Following is an example of the file content:
OKC82     OKC8201
OKC75     OKC7501
OJC07     OJC0701
On the left side, the module name is specified and on the right side, the first program name is specified.
The PSBmap file
This file is used to link the program and the PSB file names (the format contains: PgmName, PgmType, PSBFileName).

If IMS related calls (CBLTDLI and CEETDLI for Cobol programs and PLITDLI for PL1 programs) are used, IBM AD Build Client assumes the program name and the name of the PSB file are identical. In case they are not identical, a PSBmap.txt file needs to be created and configured to describe the mapping between the program name and the name of the PSB file.

If EXEC DLI (IMS related) is used, IBM AD Build Client assumes the program includes the schedule command EXEC DLI SCHD PSB. In case that the EXEC DLI SCHD PSB command is not present in the program, a PSBmap.txt file needs to be created and configured to describe the mapping between the program name and the name of the PSB file.

Important: The PSBmap.txt file needs to be placed in the root of the project's directory, to <Project Path>\<ProjectName>\ folder. The ProjectName folder was created when the project was initially defined in IBM AD Build Client. It is located, by default, directly under the Default project path filled in IBM AD Configuration Server > Install Configurations > IBM AD Discovery Build Client.
Following is an example of the file content:
EDADL3M,Cobol,EDADL3P
EDADM2M,Cobol,EDADM2P
EDADM4M,PL1,EDADM4P
EDADN2M,PL1,EDADN2P
On the left side, the program name is specified, in the middle the program type (Cobol or PL1) is specified, and on the right side, the PSB file name is specified. For Cobol programs, in case the PROGRAM-ID and the file name are not identical, PROGRAM-ID name is used to map (link) the Cobol program with the PSB file name.
To add files to a folder, follow these steps:
  1. In the Project tab, click the folder name, and then select Project > Add Files. Alternatively, right-click the folder name and choose Add Files. A file selection window opens.
  2. Locate the files (they can be on any drive and directory) and select them individually or in groups (by using the Windows SHIFT key or CTRL key mechanism).
  3. Click OK to add the selected files to the project. The names of the files appear in the expanded file structure in the project tree.
  4. Repeat the Add Files procedure to add all necessary files to each of the project folders.
  5. If you need to add a long list of files, you can use the option Add All Files from Folder. Selecting this option presents you with the following window:
    Start of changeThis image shows a dialog box. You can specify wildcards and a folder path in the dialog box.End of change
    Note: Make sure that the folder path is correct; click OK to add all the files from that folder to the corresponding project folder.
  6. To save the programs, files, and projects in their current states, select File / Save All.
    Note: It is possible that the process of adding files can take a long time during which you cannot use the application. If you need to use the application, you can run the Add files process in the background. To make the Add files operation to run in the background, follow these steps:
    1. Click Start, select Run then type cmd to open the command window.
    2. Go to the folder where your IBM AD Build Client is installed and locate the IBMApplicationDiscoveryBuildClient.exe file. Drag the IBMApplicationDiscoveryBuildClient.exe file into the command window then enter “/?” and press ENTER. A window is displayed containing detailed instructions about how to make a specific process to run in the background.