Download CA XCOM Data Transport for z/OS Release Notes

CA XCOM Data Transport for
z/OS
™
®
Release Notes
r11.5.0 RE1
This documentation, which includes embedded help systems and electronically distributed materials, (hereinafter
referred to as the ―Documentation‖) is for your informational purposes only and is subject to change or withdrawal by
CA at any time.
This Documentation may not be copied, transferred, reproduced, disclosed, modified or duplicated, in whole or in part,
without the prior written consent of CA. This Documentation is confidential and proprietary information of CA and may
not be disclosed by you or used for any purpose other than as may be permitted in (i) a separate agreement between
you and CA governing your use of the CA software to which the Documentation relates; or (ii) a separate
confidentiality agreement between you and CA.
Notwithstanding the foregoing, if you are a licensed user of the software product(s) addressed in the Documentation,
you may print or otherwise make available a reasonable number of copies of the Documentation for internal use by
you and your employees in connection with that software, provided that all CA copyright notices and legends are
affixed to each reproduced copy.
The right to print or otherwise make available copies of the Documentation is limited to the period during which the
applicable license for such software remains in full force and effect. Should the license terminate for any reason, it is
your responsibility to certify in writing to CA that all copies and partial copies of the Documentation have been
returned to CA or destroyed.
TO THE EXTENT PERMITTED BY APPLICABLE LAW, CA PROVIDES THIS DOCUMENTATION ―AS IS‖ WITHOUT
WARRANTY OF ANY KIND, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NONINFRINGEMENT. IN NO EVENT WILL CA BE LIABLE TO YOU OR ANY
THIRD PARTY FOR ANY LOSS OR DAMAGE, DIRECT OR INDIRECT, FROM THE USE OF THIS DOCUMENTATION,
INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST INVESTMENT, BUSINESS INTERRUPTION, GOODWILL, OR
LOST DATA, EVEN IF CA IS EXPRESSLY ADVISED IN ADVANCE OF THE POSSIBILITY OF SUCH LOSS OR DAMAGE.
The use of any software product referenced in the Documentation is governed by the applicable license agreement and
such license agreement is not modified in any way by the terms of this notice.
The manufacturer of this Documentation is CA.
Provided with ―Restricted Rights.‖ Use, duplication or disclosure by the United States Government is subject to the
restrictions set forth in FAR Sections 12.212, 52.227-14, and 52.227-19(c)(1) - (2) and DFARS Section
252.227-7014(b)(3), as applicable, or their successors.
Copyright © 2010 CA. All rights reserved. All trademarks, trade names, service marks, and logos referenced herein
belong to their respective companies.
CA Technologies Product References
This document references the following CA Technologies products:
■
CA ACF2™ (CA ACF2)
■
CA Top Secret® (CA Top Secret)
■
CA XCOM™ Data Transport® (CA XCOM Data Transport)
■
CA XCOM™ Data Transport® Management Center (CA XCOM Management
Center)
Contact CA Technologies
Contact CA Support
For your convenience, CA Technologies provides one site where you can access
the information you need for your Home Office, Small Business, and Enterprise
CA Technologies products. At http://ca.com/support, you can access the
following:
■
Online and telephone contact information for technical assistance and
customer services
■
Information about user communities and forums
■
Product and documentation downloads
■
CA Support policies and guidelines
■
Other helpful resources appropriate for your product
Provide Feedback
If you have comments or questions about CA Technologies product
documentation, you can send a message to [email protected].
If you would like to provide feedback about CA Technologies product
documentation, complete our short customer survey, which is available on the
CA Support website at http://ca.com/docs.
Contents
Chapter 1: Enhanced Features
7
Database for History ........................................................................... 7
New History Fields ............................................................................. 7
Create with New Allocations .................................................................... 7
PDS Compression .............................................................................. 8
New and Changed Messages ................................................................... 8
Chapter 2: Database for History
9
Create and Administer the DB2 Database ...................................................... 10
New Parameters .............................................................................. 10
HISTORY ................................................................................. 10
SYSID .................................................................................... 11
SYSNAME ................................................................................ 11
XCOMHIST ............................................................................... 11
XCOMHIST_OWNER ....................................................................... 12
XCOMHIST_PASSWORD ................................................................... 12
XCOMHIST_TBL ........................................................................... 12
XCOMHIST_USER ......................................................................... 13
Modify Commands ............................................................................ 13
Create a Database (Optional).................................................................. 14
Create a Tablespace (Optional) ................................................................ 14
Create the History Table ...................................................................... 15
Grant Database Permissions ................................................................... 16
Establish a Bind Plan .......................................................................... 17
Create the XCOMODBI Data Set ............................................................... 18
Modify JCL for CA XCOM Data Transport ........................................................ 20
Changes for ISPF ............................................................................. 21
Migrate VSAM History Databases .............................................................. 22
STEPLIB DD .............................................................................. 24
Database Availability.......................................................................... 25
Update the Database from the Overflow Data Set ........................................... 25
Security...................................................................................... 26
New and Changed Messages .................................................................. 27
Chapter 3: New History Fields and Search Facility
31
New SYSIN01 Parameters ..................................................................... 31
Contents 5
OFILE .................................................................................... 32
OFILECASE ............................................................................... 32
OJOB .................................................................................... 32
OVOL .................................................................................... 32
Updated ISPF Panels .......................................................................... 33
History Record Detail Screen .............................................................. 33
File Transfer Display Select ................................................................ 34
Chapter 4: Create with New Allocations
37
New Parameters and Operands ................................................................ 37
CREATEDELETE=[YES|NO] ................................................................ 38
CREATEDELETE=[ALLOW|NO|YES] ......................................................... 39
CREATEDELOVRD=[NO|YES] .............................................................. 40
F XCOM DFLT,CREDL,[ALLOW|NO|YES] .................................................... 40
Updated Parameter ........................................................................... 40
FILEOPT .................................................................................. 41
ISPF Update .................................................................................. 42
New Messages................................................................................ 42
Chapter 5: PDS Compression
45
CMPRS_PDS_ALLOW .......................................................................... 46
CMPRS_SYSOUT_CL .......................................................................... 47
COMPRESS_PDS .............................................................................. 48
Output ................................................................................... 49
New and Changed Messages .................................................................. 49
Index
6 Release Notes
55
Chapter 1: Enhanced Features
This document describes the enhancement requests listed by CA XCOM Data
Transport for z/OS r11.5.0 RE1 problem XCMVS #852
This section contains the following topics:
Database for History (see page 7)
New History Fields (see page 7)
Create with New Allocations (see page 7)
PDS Compression (see page 8)
New and Changed Messages (see page 8)
Database for History
History records can now be stored in a DB2 database, which provides the ability
to review history from multiple CA XCOM Data Transport for z/OS systems,
either collectively or selectively, from a central location, using ISPF.
New History Fields
The following additional fields are now stored in the history record and can be
used as search filters:
■
The job name that performed or scheduled a transfer
■
The volume serial numbers used at the local and remote locations
■
The local and remote data set names
Create with New Allocations
Allows CA XCOM Data Transport for z/OS to choose (on an individual transfer
basis) whether to recreate a file and use the allocations from the incoming
transfer .
This option applies to data sets defined as sequential.
Chapter 1: Enhanced Features 7
PDS Compression
PDS Compression
Provides the ability to compress a PDS file as follows:
■
Before the transfer
■
After the transfer
■
Both before and after the transfer
■
When needed after an out-of-space abend
New and Changed Messages
There are new and changed messages for these enhanced features. For more
information, see the chapter for each enhanced feature.
Message XCOMM0021I (an informational message) has been changed to
XCOMM0021E (an error message). This message is not specific to any of the
enhanced features.
0021E
DEFAULT OPTIONS TABLE MUST BE RE-ASSEMBLED.
GEN-LEVEL/VERSION (xxxx-xxx) DOES NOT MATCH XCOMXFER
(yyyy-yyy).
Reason:
The default options table and the version of CA XCOM Data Transport do not
match. xxxx-xxx represents the version of CA XCOM Data Transport macro
libraries used to assemble the default table. yyyy-yyy is the version of the CA
XCOM Data Transport server. Both xxxx-xxx and yyyy-yyy indicate the service
pack sequence number within the service pack.
Action:
Reassemble the default options table with the correct macro libraries. For more
information, see the CA XCOM Data Transport for z/OS Administration Guide.
8 Release Notes
Chapter 2: Database for History
CA XCOM Data Transport for z/OS currently writes history records into a VSAM
file. The history records can then be retrieved by the following means:
■
ISPF
■
CA XCOM Management Center
■
XCOMJOB TYPE=HISTORY
This enhancement of CA XCOM Data Transport for z/OS r11.5 can record history
in a relational database, using ODBC. The supported database is DB2 for z/OS,
version 9.
Also provided with this feature is the ability to write history records when
TYPE=EXECUTE transfers are performed by XCOMJOB.
When this feature is installed, you can choose to continue to record History
Records using VSAM (the default) instead of ODBC. In this case, TYPE=EXECUTE
transfers do not record any history records.
You can convert your current CA XCOM Data Transport history VSAM files to a
relational database by using the new conversion program, XCV2ODBC.
Currently, each CA XCOM Data Transport server must have its own VSAM file for
history. If you choose is to use ODBC then servers can share the same relational
database. That is, z/OS, Windows, and UNIX can all be using the same relational
database.
This section contains the following topics:
Create and Administer the DB2 Database (see page 10)
New Parameters (see page 10)
Modify Commands (see page 13)
Create a Database (Optional) (see page 14)
Create a Tablespace (Optional) (see page 14)
Create the History Table (see page 15)
Grant Database Permissions (see page 16)
Establish a Bind Plan (see page 17)
Create the XCOMODBI Data Set (see page 18)
Modify JCL for CA XCOM Data Transport (see page 20)
Changes for ISPF (see page 21)
Migrate VSAM History Databases (see page 22)
Database Availability (see page 25)
Security (see page 26)
New and Changed Messages (see page 27)
Chapter 2: Database for History 9
Create and Administer the DB2 Database
Create and Administer the DB2 Database
To set up a relational database to house CA XCOM Data Transport history
records, the following administrative tasks are required:
■
Add settings for new parameters in the CA XCOM Data Transport Default
Options Table.
■
Create the database, tables, and indexes for CA XCOM Data Transport
history.
■
Grant database permissions to users.
■
To access a DB2 database on a remote system, establish a bind plan to allow
CA XCOM Data Transport to access the database.
■
Create a data set to store ODBC configuration parameters.
■
Modify JCL for the CA XCOM Data Transport started task, Admin Server, and
XCOMJOB to include additional data sets required for ODBC processing.
New Parameters
The following new parameters have been added to the Default Options Table to
describe the information required to connect and work with ODBC history:
■
HISTORY
■
SYSID
■
SYSNAME
■
XCOMHIST
■
XCOMHIST_OWNER
■
XCOMHIST_PASSWORD
■
XCOMHIST_TBL
■
XCOMHIST_USER
Note: By default, history will be stored in a VSAM file, as is the case with the
current version of CA XCOM Data Transport for z/OS.
HISTORY
Specifies whether history records are written using VSAM, ODBC, or NONE.
Default: VSAM
10 Release Notes
New Parameters
SYSID
Specifies the system ID (one to four characters). SYSID and SYSNAME together
provide a unique system identifier.
A special value, *SMF, indicates that the z/OS SMFID is to be used for the system
ID value.
You can specify this parameter on the JCL PARM card for the CA XCOM Data
Transport started task to override the value in the Default Options Table.
Default: *SMF
SYSNAME
Specifies the system name (one to eight characters). SYSID and SYSNAME
together provide a unique system identifier.
A special value, *JOBNAME, indicates that the job name of the CA XCOM Data
Transport started task or XCOMJOB batch job is to be used as the system name
value.
You can specify this parameter on the JCL PARM card for the CA XCOM Data
Transport started task to override the value in the Default Options Table.
Default: *JOBNAME
XCOMHIST
The name of the ODBC Data Source location where the relational database is
defined.
You can specify this parameter on the JCL PARM card for the CA XCOM Data
Transport started task to override the value in the Default Options Table.
Range: 1 to 128 characters
Note: This name must be specified in the DB2 for z/OS system catalog table
SYSIBM.LOCATIONS.
Chapter 2: Database for History 11
New Parameters
XCOMHIST_OWNER
Specifies the schema name of the History Table. Can be omitted if it is the same
as XCOMHIST_USER
You can specify this parameter on the JCL PARM card for the CA XCOM Data
Transport started task to override the value in the Default Options Table.
Range: 1 to 128 characters
Default: XCOMHIST or the value of XCOMHIST_USER in the default options
table if not specified.
Note: The sample CBXGSAMP(XCOMDFLT) specifies XCOMHIST for the value.
This value corresponds to the schema name provided in CBXGSAMP(HISTDDL).
XCOMHIST_PASSWORD
The encrypted password for the XCOMHIST_USER. If the XCOMHIST_USER does
not require a password, this parameter should be omitted.
Range: Exactly 70 characters
Note: The XCOMENCR utility program should be used to create this encrypted
password.
XCOMHIST_TBL
The name of the table created for the CA XCOM Data Transport history records.
You can specify this parameter on the JCL PARM card for the CA XCOM Data
Transport started task to override the value in the Default Options Table.
Range: 1 to 128 characters
Default: XCOM_HISTORY_TBL
12 Release Notes
Modify Commands
XCOMHIST_USER
Specifies the user ID that has complete access to the XCOMHIST database.
You can specify this parameter on the JCL PARM card for the CA XCOM Data
Transport started task to override the value in the Default Options Table.
Range: 1 to 128 characters
Default: XCOMUSER
Modify Commands
Additional operand values have been added for the DFLT modify command to
allow for modifying the SYSID and SYSNAME of the CA XCOM Data Transport
started task server.
The new operands are as follows:
f xcom,dflt,sysid,<new_sysid>
new_sysid
Specifies a new four-character system ID.
A value of *SMF indicates to use the z/OS SMFID as the system ID.
f xcom,dflt,sysname,<new_sysname>
new_sysname
Specifies a new one- to eight-character system name.
A value of *JOBNAME indicates to use the jobname of the CA XCOM Data
Transport started task as the system name.
Chapter 2: Database for History 13
Create a Database (Optional)
Create a Database (Optional)
The history table needs to reside in a database.
You can do one of the following:
■
Use an existing database.
■
Create a new database specifically for CA XCOM Data Transport history. You
can select any name for this database. You can specify additional options
according to the needs of your installation.
To create a new database
CREATE DATABASE database_name <additional_options>;
Create a Tablespace (Optional)
A tablespace is the storage mechanism used by DB2 for storing table data.
Tablespaces are implicitly created when creating a table, but can be explicitly
created in order to customize or optimize storage.
To create a tablespace
CREATE TABLESPACE tablespace_name <additional_options>;
14 Release Notes
Create the History Table
Create the History Table
Note: The history table name can be selected by the installation.
CA XCOM Data Transport history requires a single database table and three
indexes, which are used for history queries. The DDL is provided in member
HISTDDL in the CBXGSAMP data set provided by the CA XCOM Data Transport
installation. HISTDDL can be used as input to SPUFI.
To customize HISTDDL
1. If the default database name is not desired or additional options are needed,
customize the DDL statement as desired.
Note: If an existing database is to be used, then you need to comment out
the statements or remove them.
2. If a customized tablespace is desired, include the DDL to create the
tablespace, following the database and before the creation of the table.
3. Change the DDL for the table creation to include the desired schema name,
table name, database name, and, if defined, tablespace name.
4. Change the DDL for the indexes to include the desired schema name and
index name.
5. If desired, create additional indexes to improve the performance of history
searches, based on the fields commonly used for searches.
You can include the following columns in indexes:
■
user_name
■
error_message
■
initiated_by
■
remote_system
■
invoking_jobname
■
volume
■
local_volume
■
file
■
lfile
■
rluname
■
conversation_type
■
byte_count
Chapter 2: Database for History 15
Grant Database Permissions
Notes:
■
Not all columns are used by all operating systems. The subset of fields used
by CA XCOM Data Transport for z/OS are those fields defined in the
HSTDSECT control block.
■
Column names cannot be modified or deleted.
Grant Database Permissions
Note: This step is required only if the creator of the table is not the user ID that
will be used to access the table.
Example:
User TSOUSER creates the XCOM_HISTORY_TBL, but does not want to put his or
her encrypted password into the CA XCOM Data Transport Default Options Table.
So a user called XCOMUSER is created, only having access to the DB2 system.
Therefore the default table would have the following values:
■
XCOMHIST_OWNER=TSOUSER
■
XCOMHIST_USER=XCOMUSER
■
XCOMHIST_PASSWORD=(the 70-character encrypted password of
XCOMUSER)
Access must be granted by TSOUSER (or another user with authority) to
XCOMUSER, as follows:
GRANT ALL ON XCOMHIST.XCOM_HISTORY_TBL TO XCOMUSER;
16 Release Notes
Establish a Bind Plan
Establish a Bind Plan
Because CA XCOM Data Transport is an ODBC application with no imbedded SQL,
you can run CA XCOM Data Transport using the default plan DSNACLI. For more
information, see member DSNTIJCL in the DB2 SDSNSAMP dataset for binding
the DSNACLI plan.
The DSNACLI plan uses a package list that includes all of the ODBC packages. If
your CA XCOM Data Transport server is to be run on the same processor where
this plan is bound, then using the default plan is sufficient. However, if your CA
XCOM Data Transport server is to be run on a processor that is not where the
table is defined, then you will have to create your own plan for CA XCOM Data
Transport.
Example:
DSN SYSTEM(D91B)
BIND PLAN(XCOMODBC)
PKLIST(DSNAOCLI.DSNCLICS
DSNAOCLI.DSNCLINC
DSNAOCLI.DSNCLIRR
DSNAOCLI.DSNCLIRS
DSNAOCLI.DSNCLIUR
DSNAOCLI.DSNCLIC1
DSNAOCLI.DSNCLIC2
DSNAOCLI.DSNCLIF4
DSNAOCLI.DSNCLIMS
DSNAOCLI.DSNCLIQR
D91APTIB.DSNAOCLI.DSNCLINF
)
END
This example shows two processors, CA11 and CA31. The DB2 system D91B
runs on CA11, but the XCOM_HISTORY_TBL is defined on system D91A on CA31.
There is an entry in SYSIBM.LOCATIONS for D91BPTIB, pointing to the DB2 on
CA31.
Chapter 2: Database for History 17
Create the XCOMODBI Data Set
Create the XCOMODBI Data Set
DB2 for z/OS uses an initialization file DSNAOINI for setting ODBC configuration
options.
To allow CA XCOM Data Transport to run on any processor capable of handling
DB2 requests, an XCOMODBI data set must be defined to contain model ODBC
configuration statements. A sample data set is provided in member DSNAOINI of
the CBXGSAMP data set when you install CA XCOM Data Transport.
XCOMODBI allows you to specify the appropriate DB2 subsystem ID, based on
the processor that CA XCOM Data Transport has been started on. You can specify
substitution parameters to allow configuration information to be tailored based
on the system that CA XCOM Data Transport is running on. On startup of CA
XCOM Data Transport, the data set is processed and appropriate configuration
statements are written to DSNAOINI for ODBC initialization.
You can add special control statements as needed, in the following format:
;CONVERT SMFID,DB2ID
Example:
;CONVERT CA11:D91B
;CONVERT CA31:D91A
[COMMON]
MVSDEFAULTSSID=*
APPLTRACE=1
APPLTRACEFILENAME=DD:APPTRACE
DIAGTRACE=1
; EXAMPLE SUBSYSTEM STANZA FOR D91B SUBSYSTEM
[*]
MVSATTACHTYPE=CAF
PLANNAME=XCOMODBC
- CA11
Notes:
■
18 Release Notes
When these statements are processed, MVSDEFAULTSSID=* is translated to
one of the following values:
–
MVSDEFAULTSSID=D91A if CA XCOM Data Transport is started on CA31
–
MVSDEFAULTSSID=D91B if CA XCOM Data Transport is started on CA11
Create the XCOMODBI Data Set
■
[*] is changed to one of the following values:
–
[D91A] if CA XCOM Data Transport is started on CA31
–
[D91B] if CA XCOM Data Transport is started on CA11
■
The above statements are used by DSNAOCLI to establish a connection to
the appropriate database in conjunction with the ODBC datasource name
specified by the XCOMHIST= parameters defined in the CA XCOM Data
Transport Default Options Table.
■
Use of this file is required when CA XCOM Data Transport is writing to a
database on a remote system, because the DSNAOCLI bind plan generated
in the previous step needs to be specified.
Note: When writing to a database on the local system, this file is not
required, and can be allocated as a dummy file in JCL (//XCOMODBI DD
DUMMY).
To create the XCOMODBI data set
1. Copy the sample CBXGSAMP(DSNAOINI) to a desired location and edit it.
2. Code your XCOMODBI statements (as shown in the example above).
3. Add the following statement:
//XCOMODBI DD DISP=SHR,DSN=your.hlq.DSNAOINI
//DSNAOINI DD UNIT=SYSDA,SPACE=(TRK,(1)),DISP=(,DELETE)
CA XCOM Data Transport initializes the startup file using the XCOMODBI
statements described above.
Note: For a complete description of the contents of this startup file, see the IBM
manual DB2 V9.1 for z/OS ODBC Guide and Reference.
Chapter 2: Database for History 19
Modify JCL for CA XCOM Data Transport
Modify JCL for CA XCOM Data Transport
To allow for the writing of history records to an ODBC database, you need to
modify the JCL for all of the following:
■
The CA XCOM Data Transport started task
■
The CA XCOM Data Transport Admin Server
■
XCOMJOB batch processing
To modify the JCL
1. Add data sets to //STEPLIB for ODBC processing, as follows:
// DD DISP=SHR,DSN=DB2.DB2910.GA.SDSNEXIT
//*
This data set usually contains the user-defined DSNHDECP module.
// DD DSN=DB2.DB2910.GA.SDSNLOAD,DISP=SHR contains the DB2/ODBC load modules.
// DD DSN=CEE.SCEERUN,DISP=SHR
// DD DSN=CBC.SCLBDLL,DISP=SHR
Note: The SDSNEXIT and SDSNLOAD data sets are installation-dependent,
based on the version and maintenance level of DB2 for z/OS. You need to
modify the names accordingly.
2. Add DD definitions for ODBC initialization, as follows:
//XCOMODBI DD DISP=SHR,DSN=XCOM.MODEL.&SYSNAME..DSNAOINI
//* SYSNAME is provided by z/OS when the operator issues a start procedure command.
//* &SYSNAME will only be resolved in the server, as it is valid only for started
tasks.
//* XCOMJOB JCL will require the actual dataset name
//*XCOMODBI DD DISP=SHR,DSN=XCOM.MODEL.CA11.DSNAOINI *For XCOMJOB
// DSNAOINI DD UNIT=SYSDA,SPACE=(TRK,(1)),DISP=(,DELETE)
// XCOMHOVR DD DISP=SHR,DSN=&PREFIX..XCOMHOVR
//* This sequential data set is used for overflow records when the database is
not available.
//* Refer to CBXGJCL(DEFHOVR) for sample allocation JCL.
20 Release Notes
Changes for ISPF
Changes for ISPF
To allow for the writing of history records to an ODBC database with an
immediate execution of file transfers from ISPF (Queue for Execution = N), the
CLIST used to invoke the ISPF panel requires additional data set allocations to be
included. These data sets are for the DB2 libraries, ODBC initialization, and CA
XCOM Data Transport history overflow. The optional global data set, created in
CBXGJCL(DEFQSAM) allows this.
You need to add the following statements need to be added to the CLIST to allow
writing history to the database:
Following the START: label
ALLOCATE
ALLOCATE
ALLOCATE
ALLOCATE
ALLOCATE
ALLOCATE
DD(DSNAOINI)
DD(XCOMODBI)
DD(XCOMHOVR)
DD(XCOMGLOB)
DD(APPTRACE)
DD(DSNTRACE)
NEW SPACE(1,1) TRACKS DELETE UNIT(SYSDA)
DA(‘your.hlq.DSNAOINI’)SHR
DA(‘your.hlq.XCOMHOVR’) SHR
DA(‘your.hlq..XCOMGLOB’) SHR REUSE
DUMMY
DUMMY
At the end of the CLIST
FREE
DD(DSNAOINI,XCOMGLOB,XCOMODBI,XCOMHOVR,APPTRACE,DSNTRACE)
You also need to add the following data sets to the STEPLIB:
■
DB2.DB2910.GA.SDSNEXIT
■
DB2.DB2910.GA.SDSNLOAD
Note: The names of these data sets are installation-specific, based on the
version and maintenance level of DB2.
Chapter 2: Database for History 21
Migrate VSAM History Databases
Migrate VSAM History Databases
You can optionally convert one or more existing VSAM history databases to a
relational table by using the new CA XCOM Data Transport conversion program
XCV2ODBC. Sample JCL is provided in CBXGSAMP(XCV2ODBC) when you install
CA XCOM Data Transport.
Input to XCV2ODBC is a control data set that describes the relational
environment. This data set is called SYSIN01.
To define the existing CA XCOM Data Transport history file to convert, use the
following format:
//XCOMHIST DD disp=shr,dsn=your.vsamfile
Input Example:
//SYSIN01 DD *
XCOMHIST=D91APTIB
XCOMHIST_USER=XCOMUSER
XCOMHIST_PASSWORD=SECRET
XCOMHIST_OWNER=MALMA12
XCOMHIST_TBL=XCOM_HISTORY_TBL
SYSNAME=XCOMPM
SYSID=CA11
SSID=D91A
DEBUG=N
XCOMHIST=
Specifies the name of the ODBC Data Source location as defined in
SYSIBM.LOCATIONS; is analogous to the CA XCOM Data Transport Default
Options Table parameter.This parameter is required.
Range: 1 to 128 characters
XCOMHIST_USER=
Names the authorization ID to use when doing the connect. This parameter
is required.
Range: 1 to 128 characters
XCOMHIST_PASSWORD=
Is the plain text password of the authorized user. If the XCOMHIST_USER
does not require a password, this parameter should be specified as a null
value (' '). This parameter is required.
Range: 1 to 8 characters
22 Release Notes
Migrate VSAM History Databases
XCOMHIST_OWNER=
(Optional) Specifies the owner of the table; can be omitted if the table was
created by XCOMHIST_USER. If not specified XCOMHIST_USER will be used
as the table owner.
Range: 1 to 128 characters
XCOMHIST_TBL=
Specifies the 1- to 128-character table name to insert rows in. This
parameter is required.
SYSNAME= / SYSID=
Specifies the system name and SMFID to be used if the existing history
record does not contain that information. If you are converting a CA XCOM
Data Transport r11 VSAM history database, this information will not be
present, and it is very important to uniquely identify the CA XCOM Data
Transport server from which this data originated.
SYSNAME (one to eight characters) is generally the name of the CA XCOM
Data Transport started task.
SYSID should be the four-character SMFID on the system that the CA XCOM
Data Transport started task runs on.
These parameters are required.
SSID=
Specifies the DB2 subsystem ID used at connect time.
This parameter is optional but is required for remote database connections.
DEBUG=
(Optional) Specifies whether to collect trace information for CA Technologies
Technical Support.
Range: Y or N
Note: Y should be specified only when directed by CA Technologies Technical
Support.
SYSNAME/SYSID Example 1:
The CA XCOM Data Transport started task XCOMPM is usually started on system
CA11. When converting the history file written by this task specify the following
values:
SYSNAME=XCOMPM
SYSID=CA11
Any existing VSAM record not containing values for SYSNAME and SYSID will use
these specifications when inserting the row into the relational database.
Chapter 2: Database for History 23
Migrate VSAM History Databases
SYSNAME/SYSID Example 2:
The CA XCOM Data Transport started task XCOMDMP is started on system CA31.
When converting the history file written by this task specify the following values:
SYSNAME=XCOMDMP
SYSID=CA31
Any existing VSAM record not containing values for SYSNAME and SYSID will use
the above specifications when inserting the row into the relational database.
Note: You can convert one or more VSAM history files to the same relational
table. You need to run the job for each VSAM history file to be converted,
modifying the XCOMHIST DD statement to reflect the appropriate file.
//STEPLIB DD
//STEPLIB DD should contain the following:
//STEPLIB
//
//
//
//
//
DD
DD
DD
DD
DD
DD
DISP=SHR,DSN=your.XCOM.load.library
DISP=SHR,DSN=D91A.PRIVATE.SDSNEXIT (CA11)
DSN=DB2.DB2910.GA.SDSNEXIT,DISP=SHR
DSN=DB2.DB2910.GA.SDSNLOAD,DISP=SHR
DSN=CEE.SCEERUN,DISP=SHR
DSN=CBC.SCLBDLL,DISP=SHR
//SYSPRINT DD SYSOUT=*
Note: The SDSNEXIT and SDSNLOAD data sets are installation dependent,
based on the version and maintenance level of DB2. You need to modify the
names accordingly.
24 Release Notes
Database Availability
Database Availability
There may be occasions where the DB2 database is unavailable to CA XCOM Data
Transport for writing history records. To maintain history data while the
database is not available, CA XCOM Data Transport writes information to a
sequential overflow data set named XCOMHOVR. The INSERT statements that
would be executed against the database are written to this file, which is used
later to update the database when it becomes available.
The data set definition must be present in the JCL when using ODBC history, or
the job will not execute. The DD statement is as follows:
//XCOMHOVR DD DISP=SHR,DSN=your.hlq.dataset
For sample allocation JCL, see CBXGSAMP(DEFHOVR). On startup of CA XCOM
Data Transport, a message is issued indicating how many records currently exist
in the overflow file, as follows:
XCOMM0862I XCOMHOVR contains
1 records at startup
This message is also issued for every 10 records that are written to the overflow
file.
Update the Database from the Overflow Data Set
When the DB2 database becomes available, the overflow file can then be used to
add the accumulated history records into the database.
To update the database
1. Copy the overflow dataset.
This step copies the current contents of the overflow data set to another data
set and clears the data set, allowing it to remain available to CA XCOM Data
Transport. To perform this step, issue the following command to the CA
XCOM Data Transport started task:
f xcom,COPYHIST,dataset_name
The data set name is the name of a new data set to be created. The DCB is
defined by CA XCOM Data Transport. If the data set already exists, CA XCOM
Data Transport fails the command and does not overwrite this data set.
This data set is compatible with SPUFI.
2. Update the database using SPUFI or any other DB2 utility, using the file
created in Step 1.
Chapter 2: Database for History 25
Security
Security
The user ID defined in the Default Options Table with parameter
XCOMHIST_USER must be granted use of the history table defined with
parameters XCOMHIST_TBL and XCOMHIST_OWNER.
With VSAM history files, each CA XCOM Data Transport server worked with its
own history file. However, using a relational database to store CA XCOM Data
Transport history records allows multiple CA XCOM Data Transport servers
(including CA XCOM Data Transport systems running on Windows and UNIX) to
share the database. So you need to be able to restrict access to rows in the
database, so that a user on system A is not allowed to see history for system B
unless the user is given explicit permission. To provide this level of security, CA
XCOM Data Transport Command Security has been enhanced with an additional
ALLHIST command resource.
CA XCOM Data Transport implements command security through the parameters
OPERSEC and EXIT13, which are coded in the Default Options Table.
If OPERSEC=SAF is coded in the Default Options Table, CA XCOM Data Transport
makes a standard SAF call to a security package (CA ACF2, IBM RACF, or CA Top
Secret) to determine whether the user has access to the ALLHIST command
resource. This resource, when permitted to a user, allows that user to view
history records for any system that is maintaining history in that database. If the
user is not permitted to this resource then the user is allowed to see history
records for the system of the originating request only.
Command: ALLHIST
Access: READ
Resource Name: XCOM.applsec.ALLHIST
applsec
The identifier for the CA XCOM Data Transport server as defined in the
Default Options Table, unless it is NONE, in which case the expression XCOM
appears in this position. This component of the security call identifies the CA
XCOM Data Transport server.
Note: If OPERSEC=NONE is coded in the Default Options Table, CA XCOM Data
Transport runs with no security check, giving the user unrestricted access to
view history records for any system that is maintaining history in that database.
This level of security is in addition to the current security provided by CA XCOM
Data Transport, as documented in the CA XCOM Data Transport for z/OS
Administration Guide.
26 Release Notes
New and Changed Messages
New and Changed Messages
This section describes the new and changed messages to support this
enhancement.
0241E
ERROR OPENING FILE - suffix
Reason:
There has been an error opening a file. The suffix provides information to
determine the problem.
Suffix Examples:
■
DD:XCOMHOVR EDC5087I—Means that the specified file characteristics did
not match those of the existing file.
■
DD:ddname or FILE:dsn may be displayed—The following text shows what is
obtained from the system when a failure occurs.
■
dsn output file must not exist—The data set name specified for output is an
existing data set and cannot be used for this function.
Action:
Adjust the file characteristics or specify a data set name that does not exist,
based on the explanation in the message suffix.
0650E
LENGTH OF XCOMHIST_PASSWORD MUST BE 70
Reason:
You attempted to compile the CA XCOM Data Transport Default Options table
with a password that is not 70 characters. The password should be entered in
encrypted format.
Action:
Use sample CBXGJCL(XCOMENCR) to encrypt the password, and then copy the
encrypted password into the Default Options table source.
Chapter 2: Database for History 27
New and Changed Messages
0859E
History xxxxxxx FAILED, rc = nnnn, mmmmmmmmmmm
Reason:
An SQL function failed.
■
xxxxxxx is the SQL function attempted. Connect and Insert are the two most
common failures.
■
nnnn is the SQLCODE, if available, or the return code from the failing
function. For example, rc = -922 is an authorization failure.
■
mmmmmmmmm is the value of SQLERRMC at the time of the failure. It
usually contains helpful information in pinpointing the cause the of the
problem. For example, CONNECT.00D31024.
Examples:
XCOMM0859E History Connect FAILED, rc = -922, CONNECT.00D31024
XCOMM0859E History Insert FAILED, rc = -204, MALMX11.XCOM_HISTORY_TBL
Action:
Check the SQLCODE, return code, or SQLERRMC in the IBM manual DB2 V9R1
for z/OS Codes.
0860E
HISTORY=ODBC specified and DSNAOCLI failed to load
Reason:
Module DSNAOCLI, the ODBC interface module for DB2, failed to load. ODBC
functions will abend if this module cannot be loaded.
Action:
Add DSN=DB2.SDSNLOAD to your STEPLIB DD statement.
28 Release Notes
New and Changed Messages
0861E
HISTORY=ODBC specified and XCOMHOVR DD missing
Reason:
Something has failed during the attempt to insert a row to the history table. CA
XCOM Data Transport makes every attempt to save the insert statement so that
you can manually insert the row when the database is once again operational.
Action:
Add the following statement to the CA XCOM Data Transport started procedure:
//XCOMHOVR DD dsn=xxxx,DISP=SHR
Allocate the file as a sequential, variable blocked file with LRECL=20000.
If a connect to ODBC fails, or the insert fails then the insert statement is written
to this file. The contents of this file can be transferred to a file suitable for use by
SPUFI, for example, by issuing the CA XCOM Data Transport modify command
COPYHIST,dsn (explained later).
If the write to the XCOMHOUT DD fails for some reason, then the insert
statement is dumped in 72-byte chunks to stderr (//SYSOUT DD). CA XCOM Data
Transport makes every attempt to ensure that all records get written to the
history data set.
0862I
(a) XCOMHOVR contains xxxxxx records at startup
(b) XCOMHOVR contains xxxxxx records
Reason:
(a) When CA XCOM Data Transport is started, a check is made to determine how
many records exist in the data set pointed to by XCOMHOVR. Unless there are no
records, this message is issued once at startup.
(b) Whenever a failure occurs and CA XCOM Data Transport writes the insert
statement to XCOMHOVR, a counter is incremented. Whenever that counter is
evenly divisible by 10, this message is issued.
Action:
None
Chapter 2: Database for History 29
New and Changed Messages
0863E
DATASET NAME REQUIRED ON COPYHIST COMMAND
Reason:
The COPYHIST command has the following format:
f xcom,copyhist,dsn
The dsn specified must not already exist. CA XCOM Data Transport creates the
file as 80-byte records. The data in XCOMHOVR is copied to this dataset as
72-byte records padded with spaces. This format is compatible with IBM’s SPUFI.
Action:
Specify a valid data set name that does not already exist.
0864I
XXXXXX HISTORY INSERT STATEMENTS COPIED
Reason:
When the HISTORY INSERT modify command is issued, CA XCOM Data Transport
copies the data from XCOMHOVR to the specified data set and this message is
issued to let you know how many records were copied.
Action:
None
30 Release Notes
Chapter 3: New History Fields and
Search Facility
This enhancement allows you to search history records using the following new
criteria:
■
Job name
■
Volume serial number (volser)
■
File name
This section contains the following topics:
New SYSIN01 Parameters (see page 31)
Updated ISPF Panels (see page 33)
New SYSIN01 Parameters
The following new SYSIN01 search parameters for TYPE=HISTORY requests
have been added for this enhancement:
■
OFILE
■
OFILECASE
■
OJOB
■
OVOL
Chapter 3: New History Fields and Search Facility 31
New SYSIN01 Parameters
OFILE
Specifies the file name (local or remote) to match for a TYPE=HISTORY request.
Note: You can use the following wildcard characters when you specify the file
name:
* or %
Represents a string of zero or more characters.
_
Represents any single character.
Example:
An OFILE value of %MASTER.FIL_.G* tells CA XCOM Data Transport to locate
a file with following attributes:
■
Starting with anything
■
Ending with anything
■
With the characters MASTER.FIL found in the name, followed by any single
character, followed by .G
OFILECASE
Specifies whether the specified file name (OFILE parameter) search should be
case sensitive.
Default: N
OJOB
Specifies the invoking job name to match for a TYPE=HISTORY request.
Note: You can use the * wildcard character when you specify the job name.
OVOL
Specifies the volser (local or remote) to match for a TYPE=HISTORY request.
Note: You can use the * wildcard character when you specify the volser.
32 Release Notes
Updated ISPF Panels
Updated ISPF Panels
The following ISPF panels have been changed for this enhancement:
■
Selection screen
■
Display screens
These changes are described in the following sections.
History Record Detail Screen
The History Record Detail screen provides information on the set of file transfers
defined on the File Transfer Display Select screen.
CA XCOM SEND
FILE
REQ.#
001302 QUEUED MONDAY
AUG. 02, 2010
09:32:15
COMMAND INPUT ===>
Local System Identification
Server: 1234XCOM
Port: 8040
Protocol: TCP
History System ID: XC12 History System Name: XCM123 Invoking Job: USER01
Sched. Start Time: MONDAY
AUG. 02 2010
09:32:19
Transfer ID: USER01234
End Time: MONDAY
AUG. 02 2010
09:32:19
Last Action: * NOT USED* Status: COMPLETED Priority Sel: 016 Exec: 016
Compress Mode: RLE
Trans. Time (Secs): 1
Compress Factr: 02.0
Transfrd. Records: 1
Bytes: 48
Bytes/Sec: 1
Compress Bytes: 49
Last Ms: XCOMM0137I 0000000001 RECORDS SENT SUCCESSFULLY - FILE=XCOM.USERID01. MG
----------System ID:
User ID:
Unit:
File Name:
S E N D I N G
*LOCAL*
USER01
----------System ID:
User ID:
Unit:
File Name:
R E C E I V I N G
USER01-LAPTOP
user01
F1=Help
F7=UP
S Y S T E M
I N F O R M A T I O N -----------Notify ID: N/A
File Type: FLAT FILE
Volume:
XCOM.USER01.MGTCENT.TXT
S Y S T E M
I N F O R M A T I O N --------
Volume:
c:\temp\mgtcent.txt
F2=SPLIT
F8=DOWN
F3=End
F9=SWAP
F4=RETURN
F5=RFIND
F10=Language F11=Hold
Notify ID: user01
File Type: REPLACE
F6=RCHANGE
F12=Alloc
The following field has been added to this screen:
Invoking Job
Specifies the job name that invoked the transfer.
Chapter 3: New History Fields and Search Facility 33
Updated ISPF Panels
File Transfer Display Select
The File Transfer Display Select screen is the entry point for displaying a list of
one or more of the following options:
■
Inactive file transfers; file transfers that have not started yet
■
Active file transfers; file transfers that are currently in progress
■
Completed file transfers
Use the display to view information and change the processing parameters
applicable to one or more file transfers.
------------------------------------------------------------------------------10/08/02
CA XCOM Release r11.5 SP00
USER01
10.214
File Transfer Display Select
09:45:42
------------------------------------------------------------------------------COMMAND ===>
Local System Identification
Server: 1234XCOM
Select Transfers ===>
Port: 8040
Inactive
Active
Limit display to transfers for the following:
History System ID ===>
| History System Name
Requesting User ID ===>
|
Request Number
Transfer ID ===>
|
Last Message
Local or Remote ===>
(L/R)
|
File Type
Transfer Type ===>
(S/R)
Remote System
ID ===>
TCP/IP ===>
Protocol: TCP
x Completed
===>
===>
===>
===>
(J/R/F)
(Y/N)
Range Start Date ===> 20100715
Range End Date ===> 20100801
Range File Size ===>
Maximum Entries ===>
(YYYYMMDD)
(YYYYMMDD)
(Min.)
Time ===> 000000
Time ===> 235959
===>
(HHMMSS)
(HHMMSS)
(Max.)
(NNNN)
Jobname ===>
Vol ===>
Case Sensitive? ===> N
(Is the search on File Case sensitive?)
File ==>
------------------------------------------------------------------------------PFK 1/Help
3/End
Copyright (c) 2008 CA, INC.
34 Release Notes
Updated ISPF Panels
The following fields have been added to this screen for this enhancement:
Jobname
Specifies the invoking job name to match for a TYPE=HISTORY request.
Note: You can use the * wildcard character when you specify the job name.
Vol
Specifies the volser (local or remote) to match for a TYPE=HISTORY request.
Note: You can use the * wildcard character when you specify the volser.
Case Sensitive?
Defines (Y or N) whether the search on the file name pattern specified in the
File field is to be case sensitive.
Default: N
File
Specifies the file name (local or remote) to match for a TYPE=HISTORY
request.
Note: The file name field is limited to 70 characters. However, you can use
the following wildcard characters when you specify the file name:
* or %
Represents a string of zero or more characters.
_
Represents any single character.
Chapter 3: New History Fields and Search Facility 35
Chapter 4: Create with New Allocations
In the current release of CA XCOM Data Transport for z/OS, a transfer with
FILEOPT=CREATE fails if the target data set already exists.
This enhancement provides a new option, which, when selected, does the
following when a transfer with FILEOPT=CREATE is received and the target data
set already exists:
■
Deletes the existing target data set
■
Allows the FILEOPT=CREATE to proceed as a standard create
Notes:
■
The new option applies only if the target data set is a sequential data set or
an entire PDS/PDSE. CREATEDELETE is ignored for other types of data sets
(such as PDS members, PDSE members, VSAM, and USS files).
■
The new option does not apply to relative GDGs unless the data set is
specified using the fully qualified GxxxxVxx name.
■
For information about creating a default table or destination members, see
the CA XCOM Data Transport for z/OS Administration Guide.
This section contains the following topics:
New Parameters and Operands (see page 37)
Updated Parameter (see page 40)
ISPF Update (see page 42)
New Messages (see page 42)
New Parameters and Operands
The new option uses a SYSIN01 parameter (CREATEDELETE=[YES|NO]), which
you can specify for individual transfers.
To enable this SYSIN01 parameter to be used, your site's CA XCOM Data
Transport administrator needs to allow it by setting another new parameter
(CREATEDELETE=[ALLOW|NO|YES]) or operand in one of the following ways:
■
In the Default Options Table (XCOMDFLT)
■
In the destination member (XCOMCNTL)
■
As an XCOMJOB PARM parameter
■
As an XCOMXFER PARM parameter
■
Using the new DFLT operand CREDL in the MODIFY command
Chapter 4: Create with New Allocations 37
New Parameters and Operands
CREATEDELETE=[YES|NO]
CREATEDELETE=[YES|NO] is a SYSIN01 parameter.
It specifies whether an existing data set should be deleted and a new data set
allocated at the start of a FILEOPT=CREATE transfer.
YES
If FILEOPT=CREATE and the data set exists, then the data set is deleted and
a new data set is allocated at the start of the transfer.
NO
If FILEOPT=CREATE and the data set exists, then the transfer fail with a
catalog/file error.
Default: NO
Notes:
38 Release Notes
■
Specifying CREATEDELETE=YES causes the attributes of the existing data
set to be lost; the new data set is allocated with the attributes specified in the
transfer.
■
CREATEDELETE applies only if the target data set is a sequential data set or
an entire PDS/PDSE. CREATEDELETE is ignored for other types of data sets
(such as PDS members, PDSE members, VSAM, and USS files).
■
CREATEDELETE does not apply to relative GDGs unless the data set is
specified using the fully qualified GxxxxVxx name.
■
The use of CREATEDELETE=YES must be allowed by your site's CA XCOM
Data Transport administrator through the default table (XCOMDFLT) or
destination member (XCOMCNTL).
New Parameters and Operands
CREATEDELETE=[ALLOW|NO|YES]
CREATEDELETE=[ALLOW|NO|YES] is a destination member and a default table
parameter.
It specifies whether the CREATEDELETE transfer (SYSIN01) parameter should be
permitted.
Important! Review the CREATEDELETE transfer parameter before permitting
its use.
ALLOW
The use of CREATEDELETE is permitted
NO
The use of CREATEDELETE is not permitted; so the CREATEDELETE transfer
parameter is always set to NO.
YES
CREATEDELETE should always be attempted if possible; so the
CREATEDELETE transfer parameter is always set to YES.
Default:
NO
For the Default Options Table (XCOMDFLT)
As specified in the Default Options Table (XCOMDFLT)
For the destination member (XCOMCNTL), or for an XCOMJOB PARM
parameter or XCOMXFER PARM parameter
Note: The default of NO can be overridden for individual partners in the
destination member.
Chapter 4: Create with New Allocations 39
Updated Parameter
CREATEDELOVRD=[NO|YES]
CREATEDELOVRD=[NO|YES] is a default table parameter.
It specifies whether CA XCOM Data Transport should allow a CREATEDELETE to
occur if the target data set is protected with an expiration date (EXPDT) and the
data set has not yet expired.
YES
Allow the CREATEDELETE to proceed; the target data set is reallocated as
described by the CREATEDELETE option.
NO
Deny the CREATEDELETE; the transfer fails, because the data set expiration
date has not been reached.
Default: NO
F XCOM DFLT,CREDL,[ALLOW|NO|YES]
Specifies whether the CREATEDELETE transfer (SYSIN01) parameter should be
permitted.
ALLOW
Allow the SYSIN01 parameter CREATEDELETE.
NO
The use of CREATEDELETE is not permitted; so the CREATEDELETE transfer
parameter is always set to NO.
YES
CREATEDELETE should always be attempted if possible; so the
CREATEDELETE transfer parameter is always set to YES.
Default: NO
Important! Review the CREATEDELETE parameter before using the CREDL
operand.
Updated Parameter
The FILEOPT description has been updated for this enhancement.
40 Release Notes
Updated Parameter
FILEOPT
Indicates how the transferred file is managed by the receiving system.
REPLACE
Replaces the file on the receiving system. What is replaced depends on the
type of VSAM file, as follows:
KSDS cluster
Records with matching and non-matching keys are replaced.
ESDS cluster
Nothing is replaced. All records are added to the end of the data set,
because a non-reusable ESDS can only be replaced by deleting and
redefining the cluster. Use CREATE to replace reusable VSAM clusters.
RRDS cluster
Nothing is replaced. This is an invalid choice.
Note: If sending a new member to a pre-existing PDS, specify REPLACE.
ADD
Adds the records of the transferred file to the end of an existing sequential
file or inserts them into an indexed file if they do not already exist there. If
the records do already exist there, CA XCOM Data Transport aborts the
transfer.
Note: You cannot add to an existing PDS member.
CREATE
Creates the transferred file on the destination system as a sequential file.
This option should also be used when VSAM clusters with the REUSE option
are to be reused. If the transfer involves a PDS member, specify CREATE
only if the PDS itself is being created; otherwise, an error results.
Notes:
■
If CREATEDELETE=YES and the data set exists, then the data set is
deleted and a new data set is allocated at the start of the transfer.
■
If CREATEDELETE=NO and the data set exists, then the transfer fails
with a catalog/file error.
Notes:
■
This parameter is ignored for TYPE=EXECUTE transfers that specify
TYPE=RECEIVE in SYSIN01 if the local file is identified through the LCLDS01
DD statement, because in this case the disposition of the file is determined
by the DISP parameter on the DD statement.
■
You can use symbolic variables with this parameter in batch SYSIN01. For
more information, see Symbolic Parameters.
Chapter 4: Create with New Allocations 41
ISPF Update
Default: REPLACE
ISPF Update
The CREATEDELETE option can be specified in the CA XCOM Data Transport ISPF
Send File and Receive File panels, using the Create Delete Option field.
Specify Create Delete Option as follows:
■
Y for CREATEDELETE=YES
■
N for CREATEDELETE=NO
For specific details for the Create Delete Option field, see the new Create Delete
Option help panel.
New Messages
This section describes the new messages to support this enhancement.
0474E
DELETE FOR EXISTING DATA SET FAILED; FUNCTION=xxxxxxxxx,
R15=xxxxxxxx, R0=xxxxxxxx
Reason:
A transfer executing in a CA XCOM Data Transport region has requested the
CREATEDELETE option, but CA XCOM Data Transport encountered an error
attempting to delete the existing file. The system function that failed and the
contents of R15 and R0 returned by the system function are listed in the
message.
Action:
Review the meaning of R15 and R0 for the system function that failed. Correct
the problem and retry the transfer.
42 Release Notes
New Messages
0477E
CREATEDELETE FAILED, NON-EXPIRED DATA SET XXXXX
Reason:
The request to do a CREATEDELETE on data set XXXXX failed because the data
set has an expiration date that has not been reached and the XCOMDFLT (default
table) option CREATEDELOVRD is set to NO.
Action:
Wait until the data set has expired or change the XCOMDFLT (default table)
option CREATEDELOVRD to YES.
0667E
PARAMETER xxxxxxxx VALUE yyyyyyyy INVALID -- MUST BE zzzzzzzz
Reason:
The value yyyyyyyy is not valid for parameter xxxxxxxx. During assembly of the
XCOMDFLT Default Options Table, the keyword parameter xxxxxxxx can be set
only to one of the zzzzzzzz values.
Action:
For information about the keyword in error, see the chapter "Configuring and
Customizing Your Product" in the CA XCOM Data Transport for z/OS
Administration Guide. Then correct the error and rerun the job.
Chapter 4: Create with New Allocations 43
Chapter 5: PDS Compression
This enhancement introduces user-configurable parameters to control if and
when programmatic compression of a target PDS data set is performed by a CA
XCOM Data Transport region. These parameters are configurable through the
Default Options Table (#DFLTAB macro), in a DEST (XCOMCNTL) member, and
through SYSIN01 transfer request parameters (as input to the batch XCOMJOB
utility).
The following new parameters support PDS compression:
CMPRS_PDS_ALLOW
Governs whether programmatic PDS compression as part of a transfer is to
be allowed on the local server.
CMPRS_SYSOUT_CL
Controls whether and to which SYSOUT class IEBCOPY output is to be
written.
COMPRESS_PDS
Causes the actual PDS compression to happen.
The following sections describe these parameters.
This section contains the following topics:
CMPRS_PDS_ALLOW (see page 46)
CMPRS_SYSOUT_CL (see page 47)
COMPRESS_PDS (see page 48)
New and Changed Messages (see page 49)
Chapter 5: PDS Compression 45
CMPRS_PDS_ALLOW
CMPRS_PDS_ALLOW
To enable CA XCOM Data Transport to perform programmatic PDS compression
for a user, your site administrator must set the CMPRS_PDS_ALLOW parameter
to a value other than NO.
This server-level parameter can be specified in the following ways:
■
In the CA XCOM Data Transport Default Options Table, by using the
#DFLTAB macro
■
By using the EXEC PARM keyword.
Note: The EXEC PARM parameter values take precedence over the
corresponding values in the Default Options Table.
Valid values are as follows:
CMPRS_PDS_ALLOW=NO
Disables the compression function within the server(s) to which it applies.
CMPRS_PDS_ALLOW=YES
Allows users to request PDS compression on a transfer-by-transfer basis, or
by using a DEST member.
Note: This setting also implicitly provides automatic compression in
response to an out-of-space condition.
CMPRS_PDS_ALLOW=X37
Automatically invokes PDS compression if a z/OS system abend B37, D37, or
E37 occurs during a transfer into a PDS data set.
Default: NO
Note: Any retryable transfer that is a result of an automatic compression from
an out-of-space conditions (such as #XCOMM0221E DATASET OUT OF SPACE PDS DATASET WILL BE COMPRESSED) is terminated if the retry also results in an
out-of-space condition.
46 Release Notes
CMPRS_SYSOUT_CL
CMPRS_SYSOUT_CL
CMPRS_SYSOUT_CL controls whether and to which SYSOUT class IEBCOPY
output is to be written.
This server-level parameter can be specified in the following ways:
■
In the CA XCOM Data Transport Default Options Table, by using the
#DFLTAB macro
■
By using the EXEC PARM keyword.
Note: The EXEC PARM parameter values take precedence over the
corresponding values in the Default Options Table.
Valid values of CMPRS_SYSOUT_CL are as follows:
NONE
Prevents the output from the compress operation from being written to a
SYSOUT data set.
LOG
Allocates a SYSOUT data set with the same output class as specified for the
XCOMLOG SYSOUT data set.
<class>
Allocates a SYSOUT data set to hold the compress utility output with the
class on this parameter.
Range: A single character (A to Z or 0 to 9)
Default: LOG
Important! IBM documentation warns of potential damage to data sets if the
IEBCOPY utility terminates abnormally, particularly during the process of
compressing a PDS data set.
Chapter 5: PDS Compression 47
COMPRESS_PDS
COMPRESS_PDS
OMPRESS_PDS is the parameter that causes the actual PDS compression to
happen. If your CA XCOM Data Transport administrator has enabled the
programmatic PDS compression feature in a CA XCOM Data Transport region,
you can use the COMPRESS_PDS option to control if and when output PDS data
sets get compressed as part of the transfer.
Note: COMPRESS_PDS applies only to PDS data sets that will be, or have been,
opened for output as the target of a CA XCOM Data Transport transfer.
You can specify the COMPRESS_PDS parameter on a transfer-by-transfer basis,
in the following ways:
■
In the SYSIN01 input to the XCOMJOB batch utility
■
In a CA XCOM DEST member in the XCOMCNTL library
Note: If the COMPRESS_PDS option is present in the DEST member for a
particular transfer partner, and that DEST member is made available to the
XCOMJOB utility that is used to schedule a transfer to that partner, it becomes
the default value for all transfers initiated with that partner CA XCOM Data
Transport in that invocation of XCOMJOB.
Valid values are as follows:
NONE
Suppresses the compression of an output PDS data set as part of a CA XCOM
Data Transport transfer.
BEFORE
Causes an output PDS data set to be compressed before the transfer of user
data begins.
AFTER
Causes an output PDS data set to be compressed after the transfer of user
data has completed.
BOTH
Causes an output PDS data set to be compressed both before and after the
transfer of user data.
Default: NONE
Note: If your CA XCOM Data Transport administrator configures
CMPRS_PDS_ALLOW=YES or CMPRS_PDS_ALLOW=X37, the
COMPRESS_PDS=NONE option cannot suppress the compression of an output
PDS data set if a z/OS system abend B37, D37, or E37 occurs.
48 Release Notes
New and Changed Messages
Output
Output from the compression utility is handled in accordance with the setting of
the CMPRS_SYSOUT_CL server-level parameter. The spool data sets (if they are
allocated) will have the following prefixes:
■
XB for compressions performed before a transfer, as in the case with
COMPRESS_PDS=BEFORE or on a restarted transfer request
■
XA for transfers performed after a transfer
The decimal transfer request number is appended to the prefix to provide a
unique spool entry for each compression operation. This naming convention
allows for the correlation of compression utility output with a specific file transfer
if there is a need for problem determination research after the transfer.
Example:
For a request number 034271, the following spool entry names would apply:
■
The output from the utility used to compress the PDS data set before the
transfer would be named XB034271.
■
For a compression performed after the data transfer, the SYSOUT dataset
would be named XA034271.
New and Changed Messages
This section describes the new and changed messages to support this
enhancement.
Chapter 5: PDS Compression 49
New and Changed Messages
0221E
(#)DATASET OUT OF SPACE - PDS DATASET WILL BE COMPRESSED
Reason:
A transfer executing in a CA XCOM Data Transport region has encountered an
out-of-space condition while writing to an output PDS data set. The specific
circumstances of this condition allow for the compression of the output PDS data
set by CA XCOM Data Transport and the resumption of the transfer of data, if the
compress operation is successful.
If the message is not prefixed with the # character, compression and retry are
not possible.
Action:
If the message is prefixed with a # character, the CA XCOM Data Transport
region attempts to programmatically compress the output PDS data set.
Otherwise, you need to compress the PDS data set manually and resubmit the
transfer for processing.
0467I
XCOMM0467I
COMPRESS_PDS=xxxxxx REQUESTED, BUT THIS SERVER IS
CONFIGURED WITH ALLOW_PDS_CMPRS=xxx
Reason:
A request to compress an output PDS data set was made, but the server on
which the transfer is executing has been not been configured to allow the type of
compression requested.
Action:
Verify that the compression that has been requested is to be allowed in the
target CA XCOM Data Transport region. Also check that the correct option is
specified in the CA XCOM Data Transport configuration parameter
CMPRS_PDS_ALLOW. This setting can be changed by a CA XCOM Data Transport
administrator.
50 Release Notes
New and Changed Messages
0468I
PRE-TRANSFER COMPRESS OF PDS DATASET COMPLETED
-
FILE=
Reason:
A compress operation on an output PDS data set has completed. The
compression was scheduled to occur before the transfer of user data has begun.
The transfer of user data follows.
Action:
None
0469I
POST-TRANSFER COMPRESS OF PDS DATASET COMPLETED
-
FILE=
Reason:
A compress operation on an output PDS data set has completed. The
compression was scheduled to occur after the transfer of user data has
completed.
Action:
None
0470E
PRE-TRANSFER COMPRESS OF PDS DATASET FAILED RC=xxxx
FILE=
-
Reason:
A compress operation on an output PDS data set has been unsuccessful. The
compression was scheduled to occur before the transfer of user data began. CA
XCOM Data Transport will attempt to complete the transfer of data without the
compression having been done.
Action:
The return code in the message is the return code from the utility that provides
IEBCOPY functionality. For an explanation of the return code, see the appropriate
documentation for the utility that provides IEBCOPY functionality on the local
system.
Chapter 5: PDS Compression 51
New and Changed Messages
0471E
POST-TRANSFER COMPRESS OF PDS DATASET FAILED RC=xxxx
FILE=
-
Reason:
A compress operation on an output PDS data set has been unsuccessful. The
compression was scheduled to occur after the transfer of user data has
completed. CA XCOM Data Transport will attempt to complete the transfer of
data without the compression having been done.
Action:
The return code in the message is the return code from the utility that provides
IEBCOPY functionality. For an explanation of the return code, see the appropriate
documentation for the utility that provides IEBCOPY functionality on the local
system.
0472E
UNABLE TO ALLOCATE SYSOUT DATASET FOR PDS COMPRESSION,
RC=xxxxxxxx
Reason:
The dynamic allocation of the SYSOUT data set that was to receive the output
from the IEBCOPY utility has failed. CA XCOM Data Transport will continue with
the compression operation, but no SYSOUT output data will be created.
Action:
To interpret the return and reason codes present in the RC= portion of the
message, see the documentation for the IBM DYNALLOC (SVC99) processing.
This is most likely an environmental error.
52 Release Notes
New and Changed Messages
0473E
DEALLOCATION FAILED FOR PDS COMPRESSION SYSOUT DATASET,
RC=xxxxxxxx
Reason:
The dynamic deallocation of the SYSOUT data set that was used to receive the
output from the IEBCOPY utility has failed. CA XCOM Data Transport will attempt
to continue processing normally. The output from this particular compression
operation may not be available for use until the CA XCOM Data Transport server
is stopped.
Action:
To interpret the return and reason codes present in the RC= portion of the
message, see the documentation for the IBM DYNALLOC (SVC99) processing.
This is most likely an environmental error.
0475E
UNABLE TO ALLOCATE U3xxxxxx DATASET FOR PDS COMPRESSION,
RC=xxxxxxxx
Reason:
The dynamic allocation of the SYSUT3 equivalent data set that was to be used as
a spill data set by the IEBCOPY utility has failed. CA XCOM Data Transport will
continue with the compression operation, but no SYSUT3 data set will be
available to the utility.
Action:
To interpret the return and reason codes present in the RC= portion of the
message, see the documentation for the IBM DYNALLOC (SVC99) processing.
This is most likely an environmental error.
Chapter 5: PDS Compression 53
New and Changed Messages
0476E
DEALLOCATION FAILED FOR PDS COMPRESSION U3xxxxxx DATASET,
RC=xxxxxxxx
Reason:
The dynamic deallocation of the SYSUT3 data set that was used as a spill data set
by the IEBCOPY utility has failed. <com> will attempt to continue processing
normally.
Action:
To interpret the return and reason codes present in the RC= portion of the
message, see the documentation for the IBM DYNALLOC (SVC99) processing.
This is most likely an environmental error.
54 Release Notes
Index
A
allocations • 37
applsec • 26
I
B
Invoking Job field • 33
ISPF changes • 21, 42
ISPF panels • 33, 34, 42
bind plan • 17
J
C
JCL, modify for history records • 20
Jobname field • 34
case sensitive • 32
Case Sensitive? field • 34
CLIST changes • 21
CMPRS_PDS_ALLOW • 46
CMPRS_SYSOUT_CL • 47
COMPRESS_PDS • 48
compression • 45, 46, 47, 48
Create Delete Option field • 42
create with new allocations • 37
CREATEDELETE=[ALLOW|NO|YES] • 39
CREATEDELETE=[YES|NO] • 38
CREATEDELOVRD=[NO|YES] • 40
CREDL • 40
M
messages • 8, 27, 42
migrate VSAM database • 22
O
OFILE • 32
OFILECASE • 32
OJOB • 32
output • 49
overflow data set • 25
OVOL • 32
D
P
database availability • 25
database for history • 9, 10, 14
database migration • 22
database permissions • 16
database updates • 25
DB2 database • 10
DFLT modify command • 13, 40
PDS compression • 45, 46, 47, 48
permissions • 16
F
security • 26
Send File panel • 42
started task JCL • 20
STEPLIB changes • 21
SYSID • 11
SYSIN01 parameters • 31
SYSNAME • 11
F XCOM DFLT,CREDL,[ALLOW|NO|YES] • 40
File field • 34
File Transfer Display Select screen • 34
FILEOPT • 41
H
history database • 9, 10, 14, 22
history fields • 31
History Record Detail screen • 33
history search • 31
history table • 15
R
Receive File panel • 42
S
T
tablespace • 14
V
Vol field • 34
VSAM database migration • 22
Index 55
X
XCOMHIST • 11
XCOMHIST_OWNER • 12
XCOMHIST_PASSWORD • 12
XCOMHIST_USER • 13
XCOMHOVR data set • 25
XCOMODBI data set • 18
56 Release Notes