IBM Support

Updates to IMS Administration Tool V1.1 User's Guide and Reference (SC27-9011-01)

Product Documentation


Abstract

Updates to IMS Administration Tool V1.1 User's Guide and Reference (SC27-9011-01).

Content

The most recent updates appear at the top of the list.


Update 9

Date of change: October 2019

Change description: Documentation changes. The following messages, which are related to the IMS resource change function and the import function, have been added.

Topic: Troubleshooting > Command processing messages (ATY)

The following messages have been added:

image-20180716101203-34

ATY3001I Return Code: rc   Reason Code: rsn

Explanation: This message is presented with an accompanying message that describes the error condition. rc indicates the return code and rsn indicates the reason code.
System action: The job terminates with the indicated return code.
User response: Review the conditions that caused the error. Also look up the meanings of return and reason codes to identify the error cause, correct the error condition, and rerun the job. If the problem persists. contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3003I Dataset Name: dsn


Explanation: This message is presented with an accompanying message. dsn indicates the data set name.
System action: Processing continues.
User response: None. This message is informational.

image-20180716101203-35

---

image-20180716101203-34

ATY3004I DD Name: dd


Explanation: This message is presented with an accompanying message. dd indicates the DD name.
System action: Processing continues.
User response: None. This message is informational.

image-20180716101203-35

---

image-20180716101203-34

ATY3005I Member: member


Explanation: This message is presented with an accompanying message. member indicates the member name.
System action: Processing continues.
User response: None. This message is informational.

image-20180716101203-35

---

image-20180716101203-34

ATY3014I text1 text2 text3


Explanation: This message is presented with an accompanying message to provide further information.
System action: Processing continues.
User response: None. This message is informational.

image-20180716101203-35

---

image-20180716101203-34

ATY3104E CPOOL function call failed


Explanation: An error occurred while getting a storage area for the indicated function call. function is either BUILD or GET.
System action: The job terminates abnormally. Other messages are issued to provide more information about the error.
User response: If the cause of the error cannot be determined, contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3107E Dynamic Allocation (SVC99) type call Failed in program program


Explanation: An error occurred in the internal dynamic allocation call. type is one of ALLOCATE, CONCATENATE, DE-CONCATENATE, or FREE. program indicates the program in which the error occurred.
System action: The job terminates abnormally.
User response: This is an internal error. Contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3111E DD required for program pgm-func processing is missing


Explanation: A required DD statement is missing in the JCL. pgm-func indicates the program or the function that requires the missing DD statement.
System action: The job terminates abnormally.
User response: Supply the missing DD statement and rerun the job. If the problem persists, contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3119E ATTACH of program program from ATY@PRSB failed. Return Code: rc


Explanation: An error occurred in the ATTACH process. The compiler program (program), which is required for the copybook import process, could not be attached. rc indicates the return code. program is either IGYCRCTL (for COBOL compiler) or IBMZPLI (for PL/I compiler).
System action: The job terminates abnormally.
User response: This is an internal error. Contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3122I dsn allocated to dd


Explanation: The indicated data set (dsn) is allocated to the indicated DD (dd).
System action: Processing continues.
User response: None. This message is informational.

image-20180716101203-35

---

image-20180716101203-34

ATY3123E EXPORT data sets from both the Catalog and ACBLIB found


Explanation: Import processing failed because the export data set was found in both the IMS catalog and the ACB library. Message ATY3124E follows this message.
System action: The job terminates abnormally.
User response: Change the prefix of the export data set so that the export data set is found only in the IMS catalog or in the ACB library. Retry the import process.

image-20180716101203-35

---

image-20180716101203-34

ATY3124E Can only IMPORT objects from one source  


Explanation: Objects to import must be found only in one of the sources – either in the IMS catalog or in the ACB library. This message accompanies message ATY3123E.
System action: The job terminates abnormally.
User response: Change the prefix of the export data set so that the export data set is found only in the IMS catalog or in the ACB library. Retry the import process.

image-20180716101203-35

---

image-20180716101203-34

ATY3125E No data sets to IMPORT objects from located 


Explanation: Import processing failed because IMS Administration Tool could not find the import data set for the indicated objects. objects indicate either DBDs or PSBs.
System action: The job terminates abnormally.
User response: Ensure that the name of the import data set, which contains the objects to import, is specified correctly.

The import data set name consists of the export data set prefix followed by one of the following strings:

For DBDs:

  • CDBDACT
  • CDBDPND
  • ADBDSTG
  • ADBDINA
  • ADBDACT

For PSBs:

  • CPSBACT
  • CPSBPND
  • APSBSTG
  • APSBINA
  • APSBACT

image-20180716101203-35

---

image-20180716101203-34

ATY3128E Required DD or variable variable for copybook processing is missing


Explanation: Copybook processing failed because a required DD statement or variable was not found. variable is either CBLLIB or PLILIB.
System action: The job terminates abnormally.
User response: Ensure that the compiler library that corresponds to the language of the copybook is registered to the CBLLIB or the PLILIB variable, or supplied with a DD statement.

image-20180716101203-35

---

image-20180716101203-34

ATY3313E QSAM function call failed for DD dd  in PROGRAM program


Explanation: An error occurred in the indicated function call for a QSAM data set. function is one of PUT, OPEN, or CLOSE. dd indicates the DD for the data set. program indicates the program in which the error occurred.
System action: The job terminates abnormally.
User response: If the cause of the error cannot be determined, contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3327E text1 text2 text3 text4


Explanation: This message is composed of several texts to describe the error condition.
System action: The job terminates abnormally.
User response: If the cause of the error cannot be determined, contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3330E Keyword is an unsupported FUNCTION 


Explanation: The import objects function, the IMS resource change function, or the DBD resource change function failed because the indicated keyword, which is specified for the FUNCTION statement of the ATYMSGI DD statement, is invalid.  
System action: The job terminates abnormally.
User response: Correct the keyword for the FUNCTION statement. The FUNCTION statement keyword can be JCLGEN, IMPORT, or UPDATE.

image-20180716101203-35

---

image-20180716101203-34

ATY3331E Missing required parameter parameter for FUNCTION=function


Explanation: The import objects function, the IMS resource change function, or the DBD resource change function failed because the indicated parameter, which the function requires, is missing. function shows the value that is specified for the FUNCTION statement on the ATYMSGI DD statement, and it is one of JCLGEN, IMPORT, or UPDATE.
System action: The job terminates abnormally.
User response: Add the missing parameter.

If the cause of the error cannot be determined, contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3332E Invalid value (value) specified for parameter=parameter


Explanation: The import objects function, the IMS resource change function, or the DBD resource change function failed because the value specified for the indicated parameter is invalid. This invalid value is present on the ATYMSGI DD statement. 
System action: The job terminates abnormally.
User response: Correct the value specified for the indicated parameter. The value must be either Y or N.

If the cause of the error cannot be determined, contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3333E CATALOG=Y specified but Catalog not enabled on target IMS


Explanation: Although the CATALOG=Y parameter is present in the ATYMSGI DD statement, the IMS catalog is not enabled in the target IMS system.
System action: The job terminates abnormally.
User response: Ensure that the target IMS system, in which the IMS catalog will be populated, is specified correctly.

image-20180716101203-35

---

image-20180716101203-34

ATY3335E ACB update required to populate IMS Catalog   


Explanation: An error occurred while checking parameters required for IMS catalog population. To populate the IMS catalog, IMS Administration Tool updates ACBs, but the parameter that is required to process ACBGEN is not found in the ATYMSGI DD statement.
System action: The job terminates abnormally.
User response: Review the parameters in the ATYMSGI DD statement.

image-20180716101203-35

---

image-20180716101203-34

ATY3336W Some objects bypassed because they already exist  


Explanation: This message is printed when the Overwrite Existing Objects option is set to No and one or more objects with same names already exist in the ACB library.
System action: Processing continues. Objects with same names are not processed (imported or updated). Prints message ATY3338W to indicate which objects are not processed.
User response: None. This is an informational message.

image-20180716101203-35

---

image-20180716101203-34

ATY3337E All members to import already exist and OVERWRITE=N  


Explanation: This message is printed when the Overwrite Existing Objects option is set to No and IMS Administration Tool identified no objects that must be processed. 
System action: The job terminates abnormally.
User response: Ensure that the correct objects are selected. Also ensure that the Overwrite Existing Objects option is set correctly.

image-20180716101203-35

---

image-20180716101203-34

ATY3338E object member  already exists in library  and will not be replaced


Explanation: This message is printed during the import process when the Overwrite Existing Objects option is set to No and the indicated member already exists in the indicated library. The import process for this member is skipped. object is either DBD or PSB.
System action: Skips the import process for the indicated member and continues processing. If there are no more objects to import, the job terminates abnormally and issues message ATY3337E.
User response: None.

image-20180716101203-35

---

image-20180716101203-34

ATY3601E Unable to locate library information


Explanation: An error occurred while obtaining information about the indicated library. library is either Inactive ACBLIB or RECON.
System action: The job terminates abnormally.
User response: This is an internal error. Contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3608E Unable to locate variable-name variable setting


Explanation: The indicated variable is missing. This variable must be registered.
System action: The job terminates abnormally.
User response: Register the indicated variable.

image-20180716101203-35

---

image-20180716101203-34

ATY3609W Unable to locate library for Fast ACBGEN 


Explanation: The library that is required for the Fast ACBGEN process is not found.
System action: Processing continues.
User response: None. This message is informational.

image-20180716101203-35

---

image-20180716101203-34

ATY3609E Unable to locate library for Fast ACBGEN


Explanation: The library that is required for the Fast ACBGEN process is not found.
System action: The job terminates abnormally.
User response: If the cause of the error cannot be determined, contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3610E Catalog Update requires function to be run on same LPAR as active IMS


Explanation: Either the IMS system is not active or this task or job is not executed on the same LPAR as the active IMS system. To update the IMS catalog, this task or job must be executed on the LPAR as the active IMS system.
System action: The job terminates abnormally.
User response: Ensure that the IMS system is active and that this task or job is executed on the same LPAR as the active IMS system.

image-20180716101203-35

---

image-20180716101203-34

ATY3612E function to target cannot be run when IMS is active


Explanation: The indicated function cannot be performed because the IMS system is active. The indicated function requires that the IMS system be inactive. function is either Update or Import. target is either Active ACBLIB or Active Catalog.
System action: The job terminates abnormally.
User response: Ensure that IMS system is not active. For more information, see "Requirement: Status of the online IMS system".

image-20180716101203-35

---

image-20180716101203-34

ATY3613E ctl-1 not valid when ctl-2 specified 


Explanation: The combination of the indicated keywords, which are specified in the ATYMSGI DD statement, is not supported.

When ctl-2 is ACB=N, ctl-1 cannot be STAGEACB=Y, ACTACB=Y, or INACTACB=Y.

When ctl-2 is CATALOG=N, ctl-1 cannot be PENDACT=Y or ACTCAT=Y.

System action: The job terminates abnormally.
User response: Correct the indicated keywords. If the cause of the error cannot be determined, contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3902E MVS Service svc call from member failed


Explanation: An error occurred when indicated member issued the MVS service (svc) call. svc is one of ATTACH, ATTACHX, OPEN, LOCASCB, DESERV, IGGCSI00, or STOW.
System action: The job terminates abnormally.
User response: This is an internal error. Contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3904E Unable to open ddname DD


Explanation: An error occurred while trying to open a data set with the DDNAME of ddname.
System action: The job terminates abnormally.
User response: If the cause of the error cannot be determined, contact IBM Software Support.

image-20180716101203-35

---

image-20180716101203-34

ATY3950E Program ATY@PRSB received invalid parameter (x) in ATYMSGI


Explanation: The copybook language parameter, which was passed to ATY@PRSB during the copybook import process, is invalid. x indicates the 1-digit invalid parameter that was passed to ATY@PRSB. The copybook  language parameter must be either B for COBOL or P for PL/I.
System action: The job terminates abnormally.
User response: This is an internal error. Contact IBM Software Support.

image-20180716101203-35

--

image-20180716101203-34-

ATY3954E Catalog Populate ended process code rc 


Explanation: During the copybook import process, the process to update the IMS catalog ended with the indicated return code. process shows the type of the code, either Abend or Return.
System action: The job terminates abnormally.
User response: Locate messages issued by the IMS Catalog Populate utility (DFS3PU00). Identify the cause of the error and correct it.

image-20180716101203-35

---

image-20180716101203-34

ATY3956E Compiler ended with process code rc


Explanation: During the copybook import process, the compiler ended with the indicated return code. process shows the type of the code, either Abend or Return.
System action: The job terminates abnormally.
User response: Identify the cause of the error and correct it. Rerun the job.

image-20180716101203-35

---

image-20180716101203-34

ATY3999E Internal Logic Error: module (Code: number)


Explanation: An internal logic error occurred. module indicates the module in which the error occurred, and number indicates the code number, which is one of the following values:

  • 001-Invalid Handle passed
  • 002-Invalid Function passed
  • 003-Invalid Parameter passed

System action: The job terminates abnormally.
User response: This is an internal error. Contact IBM Software Support.

image-20180716101203-35


Update 8

Date of change: September 2019

Change description: Documentation changes by APAR PH15100. This APAR provides the following enhancements:

  • Support type-1 XREF file format for copybook import
  • Support multiple XREF files for copybook import
  • Save DBD source after copybook import
Topics: Changes apply to multiple topics.
----------
Topic: Overview and Roadmap > IMS Administration Tool overview > What does IMS Administration Tool do?
The "Database and application administration (Object management)" section has been replaced with the following information:
Database and application administration (Object management)

image-20180716101203-34The database and application administration function provides a method for IMS DBAs to view, create, and change IMS databases (DBDs) and application views (PSBs). Capabilities include:
  • Create, add, alter, migrate, and model IMS DBD and PSB objects.
  • Decode DBDs and PSBs in the IMS directory, DBD libraries, PSB libraries, and ACB libraries to DBD and PSB macro source codes.
  • Import COBOL and PL/I copybook changes into DBD macro source.
  • Run the DBDGEN, PSBGEN, ACBGEN, and IMS catalog populate utilities immediately, or generate JCL that can be run at a later time.image-20180716101203-35
The "IMS catalog and ACB library management" section has been replaced with the following information:
IMS catalog and ACB library management
image-20180716101203-34IMS Administration Tool provides access to the IMS catalog and promotes the use of the IMS catalog by adding significant functionality beyond what is currently available with this IMS feature. Capabilities include:
  • Copy objects between the IMS ACB library or IMS directory on one IMS system to the IMS ACB library or IMS directory on another IMS system.
  • Compare versions of DBD and PSB resources in the IMS directory with those in the IMS ACB library, or between the IMS directory active data sets and the IMS directory staging data set.
  • Generate reports to help analyze the databases (DBDs) and applications (PSBs) defined in the IMS catalog.
  • Perform space utilization analysis and view the number of objects and instances in the IMS catalog.
  • Include and update individual (or bulk) IMS database definitions (DBD) with schema from COBOL and PL/I copybooks during the import process to the IMS catalog.
    Adding or updating schema to individual databases or in bulk can be accomplished either interactively or schedule through a batch process.image-20180716101203-35
The "IMS command processing" section has been replaced with the following information:
IMS command processing
image-20180716101203-34IMS Administration Tool provides IMS DBAs the capability to issue IMS commands and review command responses. Capabilities include:
  • Issue IMS type-1 and type-2 commands and view responses
  • Build IMS commands to run against databases (DBDs) and applications (PSBs).image-20180716101203-35
 
----------
Topics:
The following new topics have been added:
  • Database and application administration > Copybook import
  • Database and application administration > DBD and PSB update (ATY@OBJU) JCL
Also, the following topics have been updated:
  • Database and application administration > Database and application administration reference
  • Database and application administration > IMS resource change
  • IMS catalog management > Export objects and import objects
The following PDF contains the new and updated contents:
image-20180716101203-34
image-20180716101203-35
Note: Page, figure, table, and cross-reference numbers in this PDF extract might not match your current user guide version. Use this documentation extract for content update purposes only. Change bar markings on the left side of the page indicate the new or changed information. This information will be included in any future refreshes of the entire user guide.

Update 7

Date of change: June 2019

Change description: Documentation changes by APAR PH12977. The ATYARCH0 utility has been enhanced to support archiving audit log records in addition to command log records.

Topics: Changes apply to multiple topics.

----------

Topic: Product configuration > Additional and optional product configuration > Command log: Configure data archiving

This topic has been updated to cover the new Command and Audit Log Archive (ATYARCH0) utility. The title has been changed from "Command log: Configure data archiving" to the following:
 

image-20180716101203-34Log data archiving : Configure the Command and Audit Log Archive (ATYARCH0) utilityimage-20180716101203-35

image-20180716101203-34IMS Administration Tool provides the Command and Audit Log Archive (ATYARCH0) utility that copies old log data to a DSORG=PS data set, and simultaneously marks it eligible for deletion. The ATYARCH0 utility supports both command log data and audit log data. You can select the log records to archive; command log records, audit log records, or both.image-20180716101203-35

image-20180716101203-34The ATYARCH0 utility provides several options for determining what log records are considered old, and therefore subject to archiving/deletion.
Most of the archiving options archive only log records that were written prior to the current date. Use the MAX control card if you must archive log records from the current date.image-20180716101203-35

If the log data needs to be kept for historical purposes, the retention period must be high enough so that the z/OS System Logger will not delete the log data before it is off-loaded by the ATYARCH0 utility.

image-20180716101203-34To control the size of the archived log data set, the utility provides the following options for controlling what information is archived:
  • Date (default)
  • Hours
  • Hours within Date
  • Number of records
  • All old log data
  • MAXimage-20180716101203-35

image-20180716101203-34The output log data is displayed in the same format as the log of "View Audit Log". To check the format, use either the IMS Administration Tool Web interface or the ISPF interface: Setup and Administration > View Audit Logimage-20180716101203-35
image-20180716101203-34ATYARCH0 JCL

Sample JCL for archiving  log data can be found in the SATYSAMP sample library, member ATYARCH0.

Figure. Sample JCL to archive log data (ATYARCH0)
image-20190625133825-1
EXEC statement
Specify PGM=ATYARCH0 for the EXEC statement.

DD statements
The following table lists the data set definitions that are required by the ATYARCH0 utility.
Table. ddname requirements for ATYARCH0
(Table 3 in PDF)
DD name Description
STEPLIB Specify the IMS Administration Tool product load library.
LOGOUT
Describes the output data set where the command and log data is written.
The data set is defined as LRECL=1024 and RECFM=VB.
The size of the data set is determined by the amount of data that is being archived.
SYSPRINT An output data set that provides informational messages about the utility.
SYSPRINT is defined as LRECL=80 and RECFM=FB.
The output can be written to SYSOUT or a data set.
SYSIN An input data set that contains control statements that specify archiving parameters.
SYSIN is defined as LRECL=80 and RECFM=FB.
SYSIN control statements 
The SYSIN data set contains your description of the processing to be done by the ATYARCH0 utility. 
Follow these coding conventions when you write control statements in the SYSIN data set:
  • Keywords and keyword values must be coded within column 1 and column 71. Keywords must start on column 1 or 2.
  • The column 72 must be blank.
  • A keyword and its value must be joined with an equal sign (=) and they must be coded on the same line.
  • More than one keyword can be coded on one line. Keywords must be separated by blank space.
  • Keywords are not positional parameters; they can be specified in any order.
  • A comment line must begin with an asterisk (*) in column 1.
  • Blank lines are ignored.

The following tables list the control statements.

Table. ATYARCH0 SYSIN control statements
Keyword Description
LSN=name Required. Specify the 1- to 26-byte log stream name.
FILTER=[A | C | X]
Optional. Specify the type of log records to archive.
A: Audit log records are archived.
C: Command log records are archived.
X: Both command log records and audit log records are archived. This is the default value.
To control the size of the archived log data set, the utility provides the following statements for controlling what information is archived:
Table.  ATYARCH0 SYSIN control statements to narrow the time range
Keyword Description
DATE Default. The utility starts archiving from the oldest record in the message log and continues until it encounters a log record with a different date.
HOURS=nn
The utility starts archiving from the oldest record in the message log and continues until nn number of hours of log records has been archived, or a log record with the current date is encountered.
Valid values for nn are 1-24.
When the HOURS definition is specified in conjunction with DATE, archiving continues until nn hours of records have been archived, or a log record with a date change has been encountered.
RECS=nnnnnn
The utility starts archiving with the oldest record in the message log, and continues until nnnnnn records have been archived, or a log record with the current date has been encountered.
Valid values for nnnnnn are 1-999999.
This control statement is not valid with any other control statements listed in this table.
ALL The utility starts archiving with the oldest record in the message log and continues until a log record with the current date has been encountered.
This control statement is not valid with any other control statements listed in this table.
MAX The utility starts with the oldest record in the message log and continues until a log record with the current date and hour has been encountered.
If using this option, it is recommended that the archive job (ATYARCH0) be scheduled at 15 minutes past the hour. This ensures at least 15 minutes of log data is always present in the message log.
This control statement is not valid with any other control statements listed in this table.
Examples of the SYSIN control statements

The following SYSIN control statement example is for archiving both command log records and audit log records. Because ALL is specified, the utility starts archiving with the oldest record and continues until it encounters a log record with the current date.
//SYSIN DD *
LSN=Logger data set name
FILTER=X
ALL 
/*
The following SYSIN control statement example is for archiving command log records.
  • The first line is a comment line because the first column has an asterisk.
  • The second line has keyword LSN starting from the second column. This is valid because keywords must start in column 1 or 2.
  • The third line is a blank line. The utility skips this line.
  • The forth line has multiple keywords in one line.
//SYSIN DD *
*  Comment line
 LSN=Logger data set name
 
 FILTER=C MAX
/*
image-20180716101203-35
----------

Topic: Troubleshooting > Command processing messages (ATY)

The following messages have been added:
image-20180716101203-34
ATY8269E FILTER= ALREADY SPECIFIED

Explanation: The FILTER control statement was specified more than once in the SYSIN DD data set.
System action: The job terminates with a completion code of 12.
User response: Delete unnecessary FILTER control statements and run the job again.
image-20180716101203-35
---
image-20180716101203-34
ATY8270E FILTER= VALUE MUST BE A, C, OR X

Explanation: An incorrect value is specified for the FILTER keyword.
System action: The job terminates with a completion code of 12.
User response: Specify A, C, or X for the FILTER keyword and run the job again.
image-20180716101203-35

Update 6

Date of change: June 2019

Change description: Documentation change by APAR PI99607.

Topic: Troubleshooting > IMS SPUFI messages (ATYE, ATYT)

The following new message has been added:

image-20180716101203-34
ATYE700W SQLIMS STATEMENTS SKIPPED DUE TO PREVIOUS ERROR.

Explanation: One or more errors were detected in SQLIMS statements.  
System action: Processing continues, but SQLIMS statements are ignored.
User response: Follow User Response for the previous error message.

image-20180716101203-35


Update 5

Date of change: April 2019

Change description: Documentation changes by APAR PH08089.

Topics:

A tip (below) has been added to the following tables:

  • Table. DBD and PSB change management (Table 17 in PDF)
  • Table. IMS resource change (Table 18 in PDF)
  • Table. Importing objects (Table 22 in PDF)

image-20180716101203-34Tip: If you want to change assembler options used for DBDGEN or PSBGEN, you can do so by describing the options in a sequential data set (PS) and registering the data set to DDNAME variable  ASMAOPT.image-20180716101203-35


Update 4

Date of change: March 2019

Change description: Documentation changes by APAR PI99608. This APAR:

  • Enhances DBD/PSB Compare
  • Adds PL/I copybook support

Topics: Changes apply to multiple topics.

==========

Topic: IMS Administration Tool overview > What does IMS Administration Tool do?

This topic has been updated as follows:

Database and application administration (Object management)
image-20180716101203-34The database and application administration function provides a method for IMS DBAs to view, create, and change, and delete IMS databases and application views (PSBs). Capabilities include:
  • Create, add, delete, alter, migrate, and model IMS DBD and PSB objects.
  • Import and export COBOL and PL/I copybook changes into and from the IMS catalog.
  • Run DBDGEN and PSBGEN to update ACBLIB and IMS catalog immediately, or generate JCL that can be run at a later time.
  • Manage and track changes that are made to IMS object definitions, and resolve any potential conflicts before running.
  • Process dynamic database and application DDL generation (IMS 14+).
  • Generate JCL for IMS utilities needed to implement changes to IMS objects (IMS 13+).
  • Generate DBDGEN/PSBGEN/ACBGEN control statements for a database or application  from the IMS directory, DBD library, PSB library, and ACB library
  • Comprehensive reporting of IMS objects (IMS Library Integrity Utility).
    • Databases (DBD)
    • Applications (PSB)
  • Validation of IMS Objects (IMS Library Integrity Utility)
    • DBDLIB and PSBLIB
    • ACBLIB
    • IMS catalogimage-20180716101203-35

IMS catalog and ACB library management
IMS Administration Tool provides access to the IMS catalog and promotes the use of the IMS catalog by adding significant functionality beyond what is currently available with this IMS feature. Capabilities include:
  •  Copy objects between the IMS catalog on one IMS system to the IMS catalog on another IMS system.
  • image-20180716101203-34Compare versions of DBD and PSB resources in the IMS directory with those in the IMS ACB library, or between the IMS directory active data sets and the IMS directory staging data sets. image-20180716101203-35
  • Generate reports to help analyze the databases and applications defined in the IMS catalog.
  • Perform space utilization analysis and view the number of objects and instances in the IMS catalog.
  • Perform impact analysis when either 1) planning for the IMS catalog or 2) adding a large number of objects to the IMS catalog.
  • Include and update individual (or bulk) IMS database definitions (DBD) with schema from COBOL and PL/I copybooks during the import process to the IMS catalog.
    Adding or updating schema to individual databases or in bulk can be accomplished either interactively or schedule through a batch process.

IMS command processing
IMS Administration Tool provides IMS DBAs the capability to issue IMS commands and review command responses. Capabilities include:
  • Issue IMS type-1 and type-2 commands and view responses
  • image-20180716101203-34Build IMS commands to run against databases and applications.image-20180716101203-35

==========

Topic: IMS catalog management > DBD/PSB compare

This topic has been updated as follows:

image-20180716101203-34The compare function of IMS Administration Tool allows you to compare versions of DBD and PSB resources in the IMS directory data sets and the IMS ACB library.

Compare business scenarios

You can use the compare function to:

  • Confirm consistency of resources in the IMS directory to resources in the ACB library. The IMS directory and the ACB library to compare can be for different IMS subsystems – for example, in a data sharing environment consisting of two IMS subsystems, you can compare the IMS directory for an IMS subsystem to the ACB library for the other IMS subsystem.
  • Identify and review differences in resources between the IMS directory active data sets and the IMS directory staging data set.
Here are some common business scenarios:
  • After migrating from the ACBLIB-managed ACBs to IMS catalog-managed ACBs (IMS management of ACBs), use the compare function to verify that the IMS directory is successfully populated from the ACB library.
  • When migrating from the ACBLIB-managed ACBs to IMS catalog-managed ACBs in a data sharing environment where one IMS subsystem uses ACBLIB-managed ACBs and the other IMS subsystem uses IMS catalog-managed ACBs, the resources in the ACB library and the IMS directory must be in sync. Use the compare function to ensure that the consistency is maintained during migration.
  • If IMS catalog-managed ACBs are used, use the compare function before activating changes to resources. The compare function reports the differences between the resources in the IMS directory active data sets and the IMS directory staging data set and you can ensure that the changes that will be activated are what you intended.
image-20180716101203-35
==========
***The following doc changes have been overwritten by doc changes accompanying APAR PH15100. For the latest information, see the PDF file attached to the Update 8 section of this techdoc. ***
Topics:
In the following tables, descriptions for COPYBOOK data set and COPYBOOK XREF data set have been updated
  • Table. DBD and PSB change management (Table 17 in PDF)
  • Table. IMS resource change (Table 18 in PDF)
Also, a restriction has been added after the tables.
Option Description
... ...
COPYBOOK data set
The name of the data set where the copybook resides.
This option allows you to import a COBOL or PL/I copybook that relates to the DBD's segments.
image-20180716101203-34You can specify up to 60 data sets.
Requirement: The compiler library must be specified as a DDNAME variable. DDNAME CBLLIB is for the COBOL compiler library, and DDNAME PLILIB is for the PL/I compiler library. Specify either or both depending on the language of the copybook that you want to import. To specify the library or change the library, use the ISPF or Management Console interface.

ISPF interface
Setup and Administration > Update Product Registry > Variable Management > DDNAME Variables
Management Console interface
Setup and Admin > Variable Management

Tip: To change COBOL compiler options, specify the data set that contains the IGYCDOPT program to DDNAME variable CBLOPT.
image-20180716101203-35
COPYBOOK XREF data set
The name of the data set that pairs the DBD with the copybook.
This option allows you to import a COBOL or PL/I copybook that relates to the DBD's segments.

Example scenario:
When using import to update or add a DBD in the IMS catalog, you can create the DBD information (FIELD and DFSMARCH statements) from a copybook. You then use a copybook cross-reference data set to indicate what copybook belongs to a particular segment.
1. The COPYBOOK XREF Data Set must be a PDS or PDSE (RECFM=F or FB, LRECL=80).
2. Establish a relationship between a COPYBOOK and a SEGMENT by creating a member in the XREF data set that has the same name as the DBD. This is a manual process.
3. Inside this member there can be any number of SEGMENT entries. There can be more than one SEGMENT entry for any individual segment in the DBD.
  • image-20180716101203-34A SEGMENT entry has the format of SEGMENT=ssssssss COPYBOOK=cccccccc LANG=aaaaa.image-20180716101203-35
  • ssssssss is a 1 to 8 character field that must match the NAME= value on a SEGM statement in the DBD.
  • cccccccc is a 1 to 8 character field that must match a member name in the specified COPYBOOK Data Set.
  • image-20180716101203-34aaaaa is a 5 character field that specifies the copybook language. Specify COBOL or PLI. If omitted, defaults to COBOL. You can change the default value for this keyword (COPYLANG variable) by using the ISPF or Management Console interface.
    ISPF interface
    Setup and Administration > Update Product Registry > Variable Management > Keyword Variables
    Management Console interface
    Setup and Admin > Variable Managementimage-20180716101203-35
4. For the import function, the COPYBOOK Data Set setting and the COPYBOOK XREF Data Set setting are optional. But, if either is specified, then both data sets must be specified.
The following restriction and considerations have been added after:
  • Table. DBD and PSB change management (Table 17 in PDF)
  • Table. IMS resource change (Table 18 in PDF)
image-20180716101203-34
Restriction:  The length of variable names specified in PL/I copybook must be equal to or less than 30. Otherwise, the variable names will be truncated.

Considerations for importing or updating DBDs using COBOL or PL/I copybook
  • When a structure in a PL/I copybook contains an array with the REFER option (variable for declared length), the PL/I compiler does not provide sufficient information about that structure. This may result in having an incorrect length in the DBD source.
    In the following PL/I copybook example, Y is an array with 20 bytes. However, when this structure is imported, the length is changed to 2 bytes in the DBD source.
    DECLARE 1 STR BASED(P),
               2 X FIXED BINARY(31,0),
               2 Y (10 REFER (X)),
                 3 DATA CHAR(2);
    To prevent this, review and remove all REFER options in the PL/I copybook before you import or update from the PL/I copybook.
  • Some data attributes described in COBOL or PL/I copybooks are not directly equivalent to the DBD DATATYPE attribute.
    The following table lists the data attributes that do no have a direct equivalent DBD DATATYPE attribute and which DBD DATATYPE attribute they are mapped to.

    Table. Data attribute mapping from COBOL copybook to DBD DATATYPE
Data attribute in COBOL copybook DBD DATATYPE mapped from COBOL copybook
PIC S9(4) BINARY SHORT
PIC S9(9) BINARY INT
PIC S9(18) BINARY LONG
PIC 9(4) BINARY USHORT
PIC 9(9) BINARY UINT
PIC 9(18) BINARY ULONG
COMP-1 FLOAT
COMP-2 DOUBLE
PIC S9(n) COMP-3 DECIMAL(n,p) INTERNALTYPECONVERTER=PACKEDDECIMAL
PIC X(n) CHAR
PIC G(n) BINARY(2n)
PIC N(n) DISPLAY-1 BINARY(2n)
PIC N(n) NATIONAL BINARY(2n)
PIC 9(n) DISPLAY DECIMAL(n,p) INTERNALTYPECONVERTER=ZONEDDECIMAL
Table. Data attribute mapping from PL/I copybook to DBD DATATYPE
Data attribute in PL/I copybook DBD DATATYPE mapped from PL/I copybook
REAL FIXED BINARY(15,0) SHORT
REAL FIXED BINARY(31,0) INT
REAL FIXED BINARY(63,0) LONG
REAL FIXED BINARY(16,0) UNSIGNED USHORT
REAL FIXED BINARY(32,0) UNSIGNED UINT
REAL FIXED BINARY(64,0) UNSIGNED ULONG
REAL FLOAT DECIMAL(6) FLOAT
REAL FLOAT DECIMAL(16) DOUBLE
FIXED DECIMAL(n,p) DECIMAL(n,p) INTERNALTYPECONVERTER=PACKEDDECIMAL
CHAR(n) CHAR
GRAPHIC(n) BINARY(2n)
GRAPHIC(n) BINARY(2n)
WIDECHAR(n) BINARY(2n)
PICTURE ‘(n)9’ CHAR(n)
WIDEPIC ‘(n)9’ CHAR(2n)
CHAR(n) VAR CHAR(n)+2
CHAR(n) VARYING4 CHAR(n)+4
CHAR(n) VARYINGZ CHAR(n)+1
image-20180716101203-35

Update 3

Date of change: March 2019

Change description: Documentation updates.

Topics: Changes apply to multiple topics.

==========

Topic: Database and application administration

This topic has been updated as follows:

image-20180716101203-34 The database and application administration function in IMS Administration Tool provides a way for you to view, create, and change, and delete IMS databases (DBDs) and application views (PSBs). image-20180716101203-35

==========

Topic: Database and application administration > DBD and PSB administration reference

This topic has been updated as follows:

image-20180716101203-34 The database and application administration function in IMS Administration Tool provides a way for you to view, create, and change, and delete IMS databases and application views (PSBs). image-20180716101203-35
IMS Administration Tool extracts the DBD and PSB source from either the DBDLIB, PSBLIB, ACBLIB, or IMS catalog depending on how IMS is configured.
For resource change operations, an editable update data set is created to contain the decoded source from the specified library.
After a resource change, you can build JCL to return the changes to the IMS system.
The JCL reads the DBD and PSB source libraries from the update data set, and runs DBDGEN and PSBGEN against these source libraries. You can then control when to run ACBGEN and place resource changes in the ACB staging library of the IMS system.
If the IMS system is configured for IMS management of ACBs (IMS catalog-enabled and ACBs are managed by IMS catalog), you can additionally place resource changes in the IMS directory staging data set.
==========
Topic: Database and application administration > DBD and PSB administration reference > DBD and PSB management reference
This topic has been updated as follows:
image-20180716101203-34 The database and application administration function in IMS Administration Tool provides a way for you to view, create, and change, and delete IMS databases and application views (PSBs). image-20180716101203-35
==========
Topic: Database and application administration > DBD and PSB administration reference > DBD and PSB change management reference
This topic has been updated as follows:
image-20180716101203-34 The database and application administration function in IMS™ Administration Tool provides a way for you to view, create, and change, and delete IMS databases (DBDs) and application views (PSBs). image-20180716101203-35

Update 2
Date of change: February 2019
Change description: Documentation updates.
Topics: Changes apply to multiple topics.

Topic: IMS command processing > Using IMS Command Processor - batch processing > Runtime options for batch jobs

This topic has been updated as follows:

image-20180716101203-34You can use global options to define certain processing characteristics for all jobs. You can override most processing options by defining the options for a specific job name record in the options data set.
You set the default processing options for all batch jobs in the options data set global options record.
You can override the default options that are specified in the global options record by specifying a job name options record or by specifying ATYOPTS ddname input statements. Any options that are specified as ATYOPTS ddname statements will override any previously specified processing options.image-20180716101203-35
...
==========

Topic: Troubleshooting > Command processing messages (ATY)

The following messages have been deleted:

ATY6025I JOB RECORD FOUND
Explanation: A Job name record in the ATY options data set matched the JES2 job name.
System action: ATY runtime options are obtained from the matching ATY Job name record in the ATY options data set.
User response: No action is required.
---
ATY6026I JOB RECORD FOUND - MASK=xxxxxxxx
Explanation: A Job name record in the ATY options data set containing wildcards matched the JES2 job name. The ATY Job name record is displayed in the MASK=xxxxxxxx field.
System action: ATY runtime options are obtained from the matching ATY Job name record in the ATY options data set.
User response: No action is required.
---
ATY6027W ATYOPTS "GROUP=" SPECIFICATION IGNORED
Explanation: A Job name record in the ATY options data set containing wildcards matched the JES2 job name. The ATY Job name record is displayed in the MASK=xxxxxxxx field.
System action: ATY runtime options are obtained from the matching ATY Job name record in the ATY options data set.
User response: No action is required.

Update 1
Date of change:
August 2018
Change description: Correction to product feature availability

PL/1 copybooks currently not supported

Currently, IMS Administration Tool V1.1 does not support PL/1 copybooks.
Please ignore all references in the current user guide to PL/1 copybook support.

This limitation has been removed by APAR PI99608. See Update 4 for PL/I Copybook support.

Publication Number

SC27-9011-01

Original Publication Date

01 December 2017

[{"Business Unit":{"code":"BU011","label":"Systems - zSystems"},"Product":{"code":"SSV7D2","label":"IMS Tools"},"Component":"IMS Administration Tool","Platform":[{"code":"PF035","label":"z/OS"}],"Version":"1.1.0","Edition":"SC27-9011-01"},{"Business Unit":{"code":"BU011","label":"Systems - zSystems"},"Product":{"code":"SSV7D2","label":"IMS Tools"},"Component":"IMS Database Solution Pack","Platform":[{"code":"PF035","label":"z/OS"}],"Version":"2.2.0","Edition":""}]

Document Information

Modified date:
09 October 2019

UID

ibm10720215