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 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-34 Log data archiving : Configure the Command and Audit Log Archive (ATYARCH0) utility image-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-34 To 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
  • MAX image-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 Log image-20180716101203-35



image-20180716101203-34 ATYARCH0 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 catalog image-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 sets.

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 sets and you can ensure that the changes that will be activated are what you intended.
image-20180716101203-35

==========

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

Copyright Date

05/2018

Original Publication Date

2017-12-01


Cross reference information
Product Component Platform Version Edition
IMS Tools IMS Database Solution Pack z/OS 2.2.0

Document information

More support for: IMS Tools

Component: IMS Administration Tool

Software version: 1.1.0

Operating system(s): z/OS

Software edition: SC27-9011-01

Reference #: 0720215

Modified date: 28 June 2019