Import objects reference

The import objects function performs resource change tasks by calling the DBDGEN, PSBGEN, ACBGEN utilities, and, if IMS catalog is defined in the IMS system, the IMS catalog populate utility (DFS3PU00). If the Use COPYBOOK option is selected, the import objects function also performs copybook import before DBDGEN.

The import objects function requires an export data set as input. The export data set must contain DBD and PSB source codes generated by the export objects function.

Input and output data sets

You specify the following data sets, which are referred to during import objects, through the Import Objects panel (Table 1).

Export data sets: The import objects function requires an export data set as input. The export data set must contain DBD and PSB source codes generated by the export objects function.
Copybook and cross reference data sets.
DBD statement source updated with copybook import.
Backup data sets.

For ISPF interface users: For copybook and cross reference data sets and DBD statement source that is updated with copybook import, you can register them to a data set group and use them at run time.

You can select a data set group from Database and Application Administration > 0. Settings.

Step-by-step instructions for changing DBDs and PSBs are provided in Technote: How to change DBDs and PSBs by using IBM® IMS Administration Tool for z/OS®.

IMS data sets

DBD and PSB resources that are generated by this task will be stored to data sets such as DBD, PSB, and ACB libraries, IMS directory, and IMS catalog data sets. You do not need to specify these data sets through the panels because IMS Administration Tool discovers them according to the following rules:

ACB libraries (non-IMS-managed environment), IMS directory, and IMS catalog database

Data sets are discovered from the information defined in the IMS control region JCL and IMS PROCLIB members, which means that the data sets defined for the IMS online environment will be discovered.

ACB library (IMS-managed environment), DBD library, and PSB library

Because these data sets are not defined in the IMS control region JCL, IMS Administration Tool discovers them according to the following rules:

If Data Set Group ID is selected as data set selection method, discovers data sets from the IMS Administration Tool data set group.
If Discovered Data Sets is selected as data set selection method, IMS Administration Tool attempts to discover data sets in the following order:
1. If a RECON ID is specified for the IMS data sharing group, discovers data sets from the IMS Tools Base RECON ID.
2. Discovers DBD and PSB libraries from IMS PROCLIB data sets DBDGEN or PSBGEN member, and ACB library from the IMS control region JCL or the MDA library.

Related information:

For data set selection methods, see Database and application administration settings (ISPF interface only).
For data set groups, see Managing data sets and data set groups (ISPF interface only).
For IMS data sharing groups, see Managing IMS groups.

Although IMS-managed ACBs do not require DBD, PSB, and ACB libraries, you must ensure that the names of these data sets and resources are available in relevant resources so that IMS Administration Tool can discover the data sets.

By using these data sets, the import objects function updates the ACB library, IMS directory, and IMS catalog as follows:

During the ACBGEN process, the import objects function stores ACB members of DBD and PSB objects to the staging ACB library (IMSACB).

During IMS catalog population, the import objects function determines whether DBDs and PSBs should be active or pending according to the following conditions. Depending on the condition, the status of IMS online system (active or inactive) must be changed.

If initialization of the IMS catalog or migration to IMS-managed ACBs is requested, the import objects function stores ACB members to the IMS directory active data sets and loads DBDs and PSBs as active instances. You must stop the IMS system or stop any access to the IMS catalog database and the IMS catalog index database. For details, see Table 1.
For other requests, the import objects function stores ACB members to the IMS directory staging data set and inserts DBDs and PSBs to the IMS catalog database as pending instances. Import objects jobs can run whether the IMS system is active or inactive.

When ACB members are added to the staging ACB library or the IMS directory staging data set, after the IMS resource change completes, you must perform an IMS online change (OLC) or issue the IMPORT DEFN SOURCE(CATALOG) command to activate DBDs and PSBs in the online IMS system.

Tip: Runtime options for resource change tasks

You can predefine runtime options for resource change tasks.

Web interface

The following variables can be predefined.

IMSMAC DDname variable. IMS macro library data set. If it is not specified, the data set is discovered from the IMS PROCLIB data set.
ASMAOPT DDname variable. Data set (and member if it is partitioned) that contains assemble options for the assemble step of DBDGEN and PSBGEN.
CBLLIB, PLILIB, and CBLOPT. Variables for copybook import. For more information, see Runtime options for copybook import.

ISPF interface

Runtime options can be predefined from IMS Catalog and ACBLIB Management > 3. Import Objects > 0. Settings.

The following options allow you to set up the process of importing selected resource objects from the export data set to a new target destination. The import objects function generates a JCL job, ATY@OBJU, based on the options you select. For more information about ATY@OBJU, see Reference: DBD and PSB update (ATY@OBJU) JCL.

Table 1. Importing objects
Option	Description
Object Selection Criteria
Import Objects	Specification of resource types to import from the export data set: DBD PSB Both (DBD and PSB)
DBD and PSB Filters	Specify a wildcard expression to control the number of resource objects that display.
Import Object Options
Initial Load (web interface) Initialize IMSCat Database (ISPF interface)	This option is available if the IMS catalog is defined to the IMS system. Specify whether to initialize or update the IMS catalog and IMS directory. Y Initialize the IMS catalog and IMS directory. If an IMS catalog and IMS directory exist, the data sets are initialized. If they do not exist, IMS Administration Tool creates data sets. When the import objects job is run, all DBD and PSB objects in the ACB library are populated to the IMS catalog, not just the DBDs and PSBs that are processed in the import objects job. Specify Y for the following use cases: Recreate the IMS catalog and IMS directory that are currently being used. Make changes to the IMS environment; for example, when you start using the IMS catalog or when you migrate non-IMS-managed ACBs to IMS-managed ACBs. N Update the existing IMS catalog and IMS directory. Only the DBDs and PSBs that are processed in the import objects job are populated to the IMS catalog database. The import objects job can run whether the IMS online system is active or inactive. When ACBs are managed by IMS (IMS-managed ACBs), DBDs and PSBs are stored in the IMS directory staging data set and inserted into the IMS catalog as pending objects. When ACBs in the ACB library (non-IMS-managed ACBs) are used, DBDs and PSBs are stored in the ACB library staging data sets and the IMS catalog. After the import objects job ends, either issue the IMPORT DEFN CATALOG command of IMS or perform IMS online change (OLC) to activate the updated DBDs and PSBs.
Migrate to Managed ACBs (ISPF interface)	Use this option to migrate non-IMS-managed ACBs to IMS-managed ACBs. Y Migrate non-IMS-managed ACBs to IMS-managed ACBs. All DBD and PSB resources that are found in the exported data sets are migrated. The filtering option of DBD and PSB resources is ignored. All DBD and PSB objects in the ACB library are populated to the IMS catalog. DBDs and PSBs are stored in the IMS directory active data sets, and inserted to the IMS catalog database as active instances. By selecting the Initial Load option (web interface) or the Initialize IMSCat Database option (ISPF interface), you can control whether to store DBD and PSB instances that were used before migration. For details, see Migration scenarios using the export objects and import objects functions. N Do not migrate non-IMS-managed ACBs to IMS-managed ACBs.
Overwrite Existing Objects	Specify whether to overwrite existing DBD and PSB objects. For non-IMS-managed ACBs, specifies whether to overwrite the DBD and PSB members in the staging ACB library with the DBD and PSB members processed in this job. When you activate the staging ACB library after the import objects job is run: If you want to use the DBDs and PSBs that are processed in this job, specify Y. If you want to use the DBDs and PSBs that currently exist in the staging ACB library, specify N. For IMS-managed ACBs, specifies whether to populate all DBDs and PSBs identified by the filter (Y), or populate only the new DBDs and PSBs (N). Even when ACBs are managed by IMS, IMS Administration Tool checks the ACB library to determine if the members exist in the ACB library. It is recommended that in an IMS-managed ACBs environment, the ACB library used for DBDGEN, PSBGEN, and ACBGEN is in sync with the IMS directory. For this reason, DBDs and PSBs that exist in the ACB library should also exist in the IMS directory active or staging data sets. If you specify N (do not overwrite), only the new DBDs and PSBs that do not exist in the IMS directory (neither in the active data sets nor in the staging data set) are added. DBDs and PSBs that are selected will go through the DBDGEN, PSBGEN, and ACBGEN processes and then finally populated into the IMS catalog database. Whether the DBDs and PSBs will be populated into the IMS directory active data sets or into the IMS directory staging data set cannot be specified with this option. Generally, they will be populated into the IMS directory staging data set but if either or both of the following options are Y, they will be populated into the IMS directory active data sets: Initial Load (web interface) or Initialize IMSCat Database (ISPF interface)　 Migrate to Managed ACBs (ISPF Interface) Y Overwrite existing objects. N Do not overwrite existing objects.
Prefix of Export Data Sets	The high-level qualifier prefix of the export data set created by the export objects function.
Use COPYBOOK	This option is available only for DBD objects. Specify Y to import copybook information to the DBD source code. If you specify Y, the function analyzes the copybook and inserts corresponding metadata statements into the DBD source for DBDGEN.
COPYBOOK Data Sets Displayed when discovered data sets is selected.
COPYBOOK Cross Reference (XREF) Data Sets	The name of the data set that pairs the DBD with the copybook. You can specify up to 10 data sets. If you are using the ISPF interface, specify Y to view, change, or add data set names. For the format of COPYBOOK XREF files and examples, see Copybook XREF file.
COBOL or PL/I COPYBOOK Data Sets	The names of the data sets where the copybook resides. You can specify up to 120 data sets, maximum of 60 for COBOL copybook data sets and 60 for PL/I copybook data sets. If you are using the ISPF interface, specify Y to view, change, or add data set names.
DBD Source with COPYBOOK	Specify the name of the output data set for storing the updated DBD source.
Backup Options
Backup Existing Objects	To provide rollback capability, backup existing objects in the backup data sets before importing. This option creates backup copies of the library or the data sets that the import objects function might update. The backup copies contain DBDs and PSBs in the form of source codes. Yes Back up existing objects. The import objects function decodes ACB members in the ACB library or IMS directory into DBD and PSB source codes and stores them in the backup data sets. If the IMS management of ACBs is not enabled, creates a backup copy of the ACB staging library. If the IMS management of ACBs is enabled, creates backup copies of the following data sets: IMS directory active and staging data sets The ACB library that is pointed to from the IMSACB DD in the IMS control region JCL or that is registered to the IMS data sharing group. No Do not create backup data sets.
Initialize Backup Data Sets	Specify whether to delete object members in the backup data sets before import processing. Y Before creating new members in the backup data set, deletes all existing members that were created during previous import objects jobs. N Existing members in the backup data set are not deleted. During the import objects job, new members are added, and any member with the same name is overwritten. Specify N if you want to store backups created in multiple import objects job in a single data set.
Prefix of Backup Data Sets	The high-level qualifier prefix of the backup data sets (35 character maximum). The data sets must be PDS or PDSE.
JCL Output Options
JCL Output Data Set	The name of the partitioned data set where the generated import JCL is stored. The data set must be pre-allocated before you can generate the JCL
Member	The name of the member in the partitioned data set where the generated import JCL is stored.
Job Statements	Specification of the JOB statement of the import JCL.
Allocate Data Set	Allocate the data set where the generated import JCL is stored.