Release Notes

IBM Connect:Direct for z/OS Release Notes

The IBM® Connect:Direct® for z/OS® Release Notes document supplements IBM Connect:Direct for z/OS documentation. Release notes are updated with each release of the product and contain last-minute changes and product requirements. Read the document before installation.

Hardware and Software Requirements

Hardware and software requirements for IBM Connect:Direct for z/OS are in the Connect:Direct for z/OS Configuration Guide and the Connect:Direct for z/OS Program Directory. Connect:Direct Secure Plus requires the same hardware and software and the additional software listed in the following table.

Sterling Connect:Direct File Agent must be installed in the UNIX System Services component of z/OS and configured to communicate with the IBM Connect:Direct server. Use a PC for terminal emulation to create a configuration file. Additional Sterling Connect:Direct File Agent requirements include:

Component or Functionality Software
Connect:Direct for z/OS
  • One or more online zIIP processors to use the zIIP Exploitation Feature
  • One or more online zEDC accelerators to exploit the zEDC feature.
Connect:Direct Secure Plus for z/OS
  • TCP/IP connection to use the SSL or TLS protocol
  • IBM SystemSSL toolkit
  • IBM Language Environment
  • For Secure Plus, ICSF FMID HCR77A0 or higher is required unless cryptographic coprocessors are available. If coprocessors are available, any ICSF level supported by the Connect:Direct for z/OS release is accepted.

Connect:Direct File Agent
  • Hummingbird Exceed® PC X server for WIN32, version 7.0 or later for terminal emulation
  • Java 2 Platform, Standard Edition (J2SE). Download the J2SE from the IBM web site
  • 31-bit JVM (Java Virtual Machine)

POSIX Environment and System Libraries

Install and set up the UNIX System Services (or POSIX) environment before you install IBM Connect:Direct. The POSIX requirement and use of C/C++ and LE require that the following data sets be available to IBM Connect:Direct through the STEPLIB or LINKLST. In addition to C/C++ and LE, XPLINK is now required to support the File Accelerator and alters the data set list from previous releases.

  • CEE.SCEERUN (IBM Language Environment)
  • CEE.SCEERUN2 (XPLINK Requirement)
  • CBC.SCLBDLL (C/C++ Run-time)
  • SYS1.SIEALNKE (System SSL Environment)

If IBM Connect:Direct Resource Access Control Facility (RACF) program control is implemented, define these data sets and the IBM Connect:Direct SDGALINK to the program class.

MBCS Transfers

To perform MBCS transfers, verify that the Natural Language Resources component of Language Environment is installed on your operating system.

License Key File

To exploit the FASP feature through SSP you must obtain and store a HSAO license file inside the Connect:Direct for z/OS file system. This HSAO license file must be available to the IBM Connect:Direct during product initialization via the CDASPLIC DD statement.

New Product Name

The product formerly known as IBM Sterling Connect:Direct for z/OS now reflects the IBM Corporation brand and logo, and product is now referred to as IBM Connect:Direct.

What's New in This Release

In this release of IBM Connect:Direct for z/OS, and its related software, several features have been added to enhance functionality. The following sections describe these changes in more detail.

New features added to this release

  • Enhanced logic for MAXDELAY has been added to allow for closer monitoring of the Process and the ability to restart the API session when certain communication failures occur. See Using the MAXDELAY in the User Guide for more information.
  • An enhanced SESSION.HIGHWATER.SMF support to enhance monitoring and recording of Session Highwater mark by generating SMF data with additional data about the Connect:Direct environment and recording within the Connect:Direct Statistics facility.
  • zEDC hardware compression has been enhanced to set a precedence to favor zEDC over the zIIP feature. See ZEDC Global Initialization Parameters in the Administration Guide.
  • Enhanced zLIB compression support to allow for better buffering of data prior to compression to ensure more data is eligible for compression and eligible for zEDC compression.
  • Support of the FASP protocol through the Sterling Secure Proxy to exploit the FASP protocol between SSP and a Connect:Direct Server running on Windows or UNIX. Please reference “Planning for Aspera FASP for IBM Connect:Direct for z/OS” in the Configuration Guide.
  • Support to allow the Connect:Direct SDGALINK to be allocate via LIBDEF. Please reference the Configuration Guide for details.
  • Enhanced Secure Plus support to:
    • Exploit of a default certificate from the Key store
    • Support for easy cloning of SecurePlus parameter file entries
    • Generate a report of the SecurePlus configuration
    • Exploit the zERT feature of the zOS Communication Server

      Please reference the SeucrePlus Implementation Guide for details.

  • Enhanced ISPF IUI support that enables or disables UI functionality based on the authorization of the user.
  • Support of a global TCP SourceIP. Please reference Global TCP SourceIP in the Configuration Guide for details.
  • Support to allow for multiple Operator CLIST data set concatenation. Please reference the Facilities Guide for details.
  • Removal of the authorization bit mask from the DGASECUR macro allowing for easy customization of authorized functionality within the Stage2 Security exit. Please reference the Administration Guide for details
  • Stage2 Security Exit enhancement to force SPOE translation if performed it the remote Connect:Direct access is attempting using the special passwords of IUI, BATCH or STC. Please reference the Administration Guide for details.
  • Passing of the address of the UICB to the submit exit to allow the exit to set user text in the UICB fields UIERRM1 and UIERRM2.
  • Add 2 new Operator CLIST to perform the Certificate Expiration Check and Refresh S+ commands.
  • Enhanced modal logic to allow for check of the highest return code of all steps within a Process, checking of variable data passed to the process and checking of message id from a previous step.
  • Select Statistics Enhanced to allow for:
    • Selecting by SNODE, by PNODE, by FROM node, by TO node, by Local node, by Remote node and by Submitter node, and also allow selecting by any node - that is, if a node is any of the preceding.
    • Customized Select Statistics panel that consolidates the basic with extended selection criteria
    • Add addition information to several Stat record types
    • A new 'WHERE2' layout for the header portion of the CT, FI, MC/M2, PI/ZI, PS/SW, PT/ZT, RJ, and RT records
    • Information on the reasons for use or non-use of ZEDC and ZIIP, including ZIIP fallback
    • Connect:Direct Server version to the CT record
    • File DCB information to the CT record
    • Add Process Class to the CT, PT, SB, SE, RT and RJ records
    • Add a Session End (SE) record that should pair up with the Session Begin (SB) record
    • Added new Operator Clist (OP) record that reflects the CLIST and from which data set the CLIST was executed from
    • Added flags CTFXNODE, MCFXNODE and FIFXNODE (P/S node fields were corrected) to resolve inconsistency in the stats report for CT, MC and FI records when Connect:Direct for z/OS is acting as the SNODE. For sample code to handle the FX flag, refer to member DGAXSCPU in $CD.SDGASAMP.
  • Enhanced the V2.BUFSIZE parameter to support up to 2MB buffer sizes

  • Allow for setting the Default File Permission when creating new files in zFS file system
  • Enhanced the command processor to ensure that all commands issued produce a WTO that identified the Userid for which issued the command
  • Relaxed the authorization restrictions for the Stage1 Security exit.

Known Restrictions

Connect:Direct for z/OS and its related software for this release have the following known restrictions:

  • Data loss had been discovered to occur under the following conditions:
    • CKPT/Restart is specified
    • Restart has occurred
    • zEDC is specified on the receiving side
    • file size and buffer size combinations that are boundary conditions in the code
    To mitigate the problem until a complete solution can be developed, Connect:Direct will disable zEDC on the receiving side of the transfer if checkpointing is specified on the Process COPY step. If zIIP fall back is possible on the receiving side of the transfer, then zIIP will be utilized. Otherwise, software zLIB decompression will be used. zEDC compression can be utilized on the sending side of the transfer without any data integrity issues. zEDC decompression can be utilized on the receiving side of the transfer if the Process specifies the COPY statement keyword, CKPT=0K.
  • In previous versions of Connect:Direct for z/OS, the default behavior for TCP Source IP was to bind to the first IP address defined in the TCP.LISTEN initialization parameter. The V6R0 global initialization parameter, TCP.SOURCEIP, now defaults to HOSTNAME, obtained during initialization and each Process will bind to that address as the Source IP address for the PNODE. This is a new behavior from prior versions and may cause the SNODE to fail NETMAP checking of the Source IP. You can specify the new Source IP address in the SNODE’s adjacent node entry by specifying an alternate communication address or ALT.COM to define that new IP address if it differs from what was previously defined. An alternative method on the PNODE is the SOURCEIP NETMAP parameter to define a specific IP address for the SNODE or specify a more appropriate address for the TCP.SOURCEIP initialization parameters. For more information, see Global TCP SourceIP in the Configuration Guide.

Connect:Direct for z/OS Special Product Considerations

Review the following considerations before installing the product:

Installation Consideration

  • If the installation data sets have been loaded to a cataloged data set with an HLQ other than IBM.fmid, the SMP/E RECEIVE command must change the HLQ by specifying the RFPREFIX(hlq) parameter, for example, RECEIVE SELECT(HDGA510) RFPREFIX(hlq).

Exits Considerations

  • If you assemble and link-edit the sample exits, DGAXPALL and DGAXPNUM in the $CD.SDGASAMP library, the following assembly error will occur: ASMA140W END record missing. Ignore this error, caused by comment lines after the SCEND statement.
  • The IBM Connect:Direct startup JCL has a user-definable DD statement (USRINFO) for displaying user-defined information from User Exits. If the USRINFO DD is allocated, then IBM Connect:Direct opens it during product initialization and initializes it with the string SITA523I USRINFO INITIALIZED.

Initialization Parameters Considerations

  • In a IBM Connect:Direct/Plex environment, if you specify ANYADDR or ANYADDR6 for the TCP.LISTEN local initialization parameter associated with a IBM Connect:Direct Server but do not specify the CDPLEX.REDIRECT parameter, a default address is created as the IBM Connect:Direct/Plex redirection address. For the IPv6 protocol, the default is generated by adding a::FFFF: prefix to the IPv4 default. If you do not want this to be your default address, specify the value you do want using the CDPLEX.REDIRECT parameter.

    If you use the dynamic VIPA resources, you may need to specify the SOURCEIP parameter in the network map if the remote node cannot perform network map checking. The SOURCEIP address is used to bind the socket and by the remote node to perform netmap checking.

  • The following initialization parameters are obsolete and must be removed from the initialization parameter file:
Obsolete Parameters
ABNLIGNR ALLOC.OPTIONS ALLOC.STORAGE
APCTHRSH APDSN API.SYSTEMS
APPLID BUFND BUFSIZE
CD.KEY CD.NODE CDPLEX.TCPIP
CDPLEX.TCPNAME CONNECT.WAIT DUMP
ESTAE EXT.COMPRESS.DEFAULT LINES
LOG LOG.PRINTER LU1.ASYNC
LU1.NETMAP.CHECK LU1.SCRIPT.DSN LU2.WAIT
MAXRESTAR MAXWAIT MP
NDM.KEY NDM.NODE NETEX.MAX.OFFERS
NETEX.MAXRU NETEX.NRBTIME NETEX.OFFERTIM
NETEX.OLD.PREFERRED NETEX.SSNM NETEX.VER
NETEX.WINDOW OS390.TASKING PASSWORD
PASSWORD.REPLY PC.ENABLE.CHECK POA.APPL
POSIX PRTYINT RESIDENT.MOD
SECURITY.TYPE STIMEOUT STORAGE.PER.TASK
TAPE.DETACH TAPE.RETPD TCP.ADDR
TCP.API.PORTNUM TCP.BUFSIZE TCP.NAME
TCP.PORTNUM TCP.SNS.SUBSYS TCQDSN
TCXDSN TPAM XETEX
XETEX.MAX.OFFERS XETEX.MAXRU XETEX.NRBTIME
XETEX.OFFERTIME XETEX.SSNM XETEX.VER
XETEX.WINDOW XLU1.ASYNC XLU1.SCRIPT.DSN
ZEDC.EXCLUDE ZIIP.EXTCOMP.DATASIZE.THRESHOLD  

Process Retention Considerations

  • To enable Process Retention, increase the TCQ space before activating it. A Process is retained in the PR queue until manually deleted, space is required, or MAX.AGE value is reached. Increasing TCQ space reduces the likelihood that a Process in the PR Queue is automatically deleted when space is required. For information on enlarging the TCQ, see Planning the Installation.

Network Map Considerations

  • If IBM Connect:Direct FTP+ for z/OS communicates with an earlier version of Connect:Direct for z/OS, the CDFTP.TEMPFILE specification in the netmap must be an zFS file unless appropriate maintenance has been applied to that version of IBM Connect:Direct for z/OS.
  • Session Management of Adjacent Nodes - Use the SESS.SNODE.MAX network map parameter only with the TCP/IP and LU6.2 protocols.

Storage Considerations

  • To maximize available storage below the 16-MB line, define sufficient storage above the 16-MB line, and maximize concurrent processing, define a region size of 0 MB for IBM Connect:Direct.
    Note: Depending on your system-specific storage requirements, the MAXTHREADTASK and MAXASSIZE parameters in SYS1.PARMLIB member BPXPRMxx may also have to be altered to ensure maximum storage and concurrent processing within IBM Connect:Direct.

Other Product Considerations

Review the following other product considerations before installing the product:

  • UNIX System Service (BPX) calls are executed in the IBM Connect:Direct IUI under the TSO or Batch User ID. BPX calls require that a user ID has an OMVS segment defined to it within the external security product, such as IBM RACF, CA-ACF2 or CA-TOP SECRET. The BPX calls resolve the TCP/IP name or address for reporting purpose in Select Statistics. If a user ID does not have an OMVS segment defined to it, an SEC6 ABEND or Trace Resolver messages under the TSO or batch user can occur when requesting Select Statistics.

    Information about adding an OMVS segment to a user ID using an external security product, either individually or as a group assignment, is found in the external security product documentation.

  • Due to an issue with the security toolkit on the i5/OS hardware, an SSL/TLS cipher suite can be negotiated during the SSL/TLS handshake that is not defined in the cipher suite list. IBM PMR, 35692, has been opened to address the i5/OS toolkit issue. When the PTF becomes available for i5/OS, apply it to ensure cipher suite negotiation occurs as expected.

Transmission Control Queue Considerations

Review the following Transmission Control Queue considerations before installing the product:

  • Because of the changes in the Transmission Control Queue (TCQ) to support Processes containing up to 1 MB, review all SUBMIT exits. Modify any SUBMIT exit that:
    • Alters the size of the TCQE (change TQRECLN)
    • Uses TQCSPRD (pointer to first, that is, current step)
    • Uses TSHFTCQE (forward pointer to next step)
    • Uses TSHBTCQE (backward pointer to previous step)
    • Adds or changes PACCT or SACCT information

      The TQCSPRD, TSHFTCQE, and TSHBTCQE fields contain offsets relative to the start of the TCQE for Processes that do not exceed 64 KB. For larger Processes, these fields must be multiplied by 16 before being used as an offset. In the TCQE, a flag indicates whether or not this processing should take place (the flag byte is TQFLAGA and the bit equate is TQGT64K).

      SUBMIT exits are no longer allowed to change the size of the TCQE (modify TQRECLN). The sample SUBMIT exit DGAXACCT previously showed how to add the PACCT and SACCT fields to the end of the TCQE and extended the length. Because this is no longer allowed, fields have been reserved for the PACCT and SACCT information to allow the SUBMIT exit to add or modify accounting information as required. The sample SUBMIT exit DGAXACCT has been modified to show you how to manipulate this account information.

  • Using IGGCSI00 to access files requires READ access to the master catalog.
  • Only Version 2 Flows, which are used for the TCP/IP and SNA LU6.2 protocols, support the ability to checkpoint files larger than 4 GB. Version 1 Flows, which were used for VTAM SNA LU0, do not support this ability.
  • To honor the permission setting for HFS files using the PERMISS keyword, you must set the z/OS UNIX System Services UMASK to 000 either by default or by using the runtime environment variable, _EDC_UMASK_DFLT. To set the environment variable, define the _EDC_UMASK_DFLT=000 variable in a RECFM=VB type file and allocate the ENVIRON DD in the IBM Connect:Direct startup JCL.
  • Example: //ENVIRON DD DISP=SHR,DSN=$CD.ENVIRON(TZ)

Miscellaneous Considerations

Review the following miscellaneous considerations before installing the product:

  • Because the standby extended recovery job and the active IBM Connect:Direct node use the same VTAM APPLID, TCP/IP address, and port, the standby extended recovery job must run in the same z/OS image as the active IBM Connect:Direct node unless you use the Dynamic VIPA and Dynamic SNA information described in Preparing TCP/IP Configuration and Configuring Extended Recovery.
  • If you copy a file that is in IBM-proprietary compressed format to a new file that is not, IBM Connect:Direct may not allocate enough space for the new file. Such COPYs may experience allocation failures (Sx37 type ABENDs), which will require SPACE to be manually coded in the Process.
  • Scheduling or automated operations packages can result in attempts to process incomplete or empty files. Scheduling packages, such as CA-7, ZEKE, or CONTROL-M and certain automated operations packages, such as CONTROL-O, are often set to start jobs upon a file's closure and an SMF record being cut or based upon specific messages appearing on the system console. When using Connect:Direct for z/OS, this method of starting jobs can result in attempts to process incomplete or empty files. This situation can occur when an active transfer is interrupted and must be restarted. The receiving file will be closed, but upon Process restart it will be written to by Connect:Direct for z/OS.

    To prevent erroneous processing by such packages, set up Processes with conditional logic to verify that the copy successfully completes, and then use the scheduling or automation package's provided program (U7SVC, ZEKENDM, CTM@IF10) in a IBM Connect:Direct RUN TASK.

  • Checkpointing is ignored when transferring HFS files.
  • IBM C Program Containing MAIN() or Enclave - You cannot execute any IBM C program that contains a MAIN() section or enclave as a Run Task or Exit. FTP is an example of this type of program.
  • LU6.2 Does not Support Redirection of Processes in IBM Connect:Direct/Plex Environment -The LU6.2 connection protocol does not support the feature, which allows the IBM Connect:Direct Manager to redirect work to one of its servers. The remote node must address the server on which you want to run an LU6.2 Process. To do this, specify the node name and VTAM address of the IBM Connect:Direct Server on which the Process is to run in the remote server's network map. Use the same CDPLEX.SERVER.NODE and CDPLEX.VTAM specified for the local initialization parameters for the IBM Connect:Direct Server you are trying to address.

    Another stipulation related to the LU6.2 protocol involves a situation where one of the IBM Connect:Direct servers in a IBM Connect:Direct/Plex environment is communicating with a stand-alone IBM Connect:Direct DTF. In this case, all LU62 processes for this specific node must be directed to the same server and you can use a PLEXCLASS to accomplish this.

  • IBM Connect:Direct cannot transfer LBI files using LU0 connections.

UDT Special Considerations

Review the following UDT considerations before installing the product:

  • UDT requires three threads for each executing Process which may impact your storage and concurrent processing capabilities. If the number of available threads becomes critically low, you may need to increase the MAXTHREADS limit per PROCESS in the OMVS environment.
  • To use UDT for file transfers on high-speed networks with latency, refer to the following table which summarizes performance differences between TCP and UDT:
Bandwidth Latency Results
45 Mbps All latencies TCP is equal to UDT
155 Mbps Less than 20 ms

Greater than 20 ms

TCP outperforms UDT

UDT outperforms TCP

1 Gbps Less than 10 ms TCP outperforms UDT
  Greater than 10 ms UDT outperforms TCP

For information on UDT, see Configuring Firewall Navigation and Using the UDT Protocol in IBM Connect:Direct for z/OS Administration Guide.

Connect:Direct Secure Plus Considerations

Review the following Connect:Direct Secure Plus considerations before configuring the product:

  • Support for the TLS 1.1 and TLS 1.2 protocols require certain version and release levels, as well as PTF service to use those protocols. See the Program Directory for detailed information on these requirements.
  • The support for Security Policy SP800-131a and the Suite B profile requires that the Secure Plus and System SSL be in FIPS mode. See the information below and the System SSL Programing Guide regarding FIPS.
  • Connect:Direct Secure Plus uses services from ICSF that require the Connect:Direct ID for Secure Plus and the TSO user ID of the Secure Plus Administrator to have read access defined in the RACF CSFSERV facilities class.
  • The enhancements to Connect:Direct Secure Plus such as, new protocols added, support for new security policies, and removal of support for STS require a Secure Parmfile conversion. For more information see, DGASCONV – Secure Parameter File Conversion Utility.
  • IBM Connect:Direct administrators need access to z/OS UNIX System Services in order to update SSL and TLS parameters.
  • IBM Connect:Direct needs UNIX read permission to the key database. Use the UNIX CHMOD command to change permissions, if necessary.
  • A default certificate must exist for the SSL or TLS protocol to successfully communicate with a trading partner. Use the IBM GSKKYMAN utility (or IBM RACF if using key rings) to set a trading partner certificate as the default. For information about creating and managing certificates, refer to the IBM documentation. To locate documentation, go the IBM web site and perform a search on GSKSSL10.
  • Secure connections cannot be established using LU0 or PNODE=SNODE. Nonsecure connections operate normally using these protocols.
  • You can only use the Quick Start option the first time you create and populate the Connect:Direct Secure Plus parameter file from the network map, and if your IBM Connect:Direct TCP/IP netmap entries use standard IPV4 addresses.
  • While in FIPS mode, the following are important considerations for Connect:Direct Secure Plus:
    • The certificate store must be in FIPS mode and the certificate must meet size restrictions for encryption keys. The GSKKYMAN utility can be used to create a key database for FIPS mode. In addition, other requirements of RACF might be necessary. For more information, see z/OS V1R11.0 Cryptographic Services System Sockets Layer Programming SC24-5901-08
    • While in FIPS mode, IBM Connect:Direct Secure Plus can open a FIPS mode key database; however, initialization fails if the key database is not in FIPS mode. If the FIPS initialization parameter is specified as NO, IBM Connect:Direct Secure Plus can still open and use a FIPS-mode database.
    • When Connect:Direct FTP+ is in FIPS mode, the TLS protocol is the only supported protocol. If SSL is enabled in the secure parameter file, the connection to that remote node is rejected during the TLS handshake.
    • While in FIPS mode, only certain ciphers are supported. During the TLS handshake, any non-FIPS mode ciphers are ignored. The Secure Plus Admin tool provides the following textual representation of the ciphers available in FIPS mode:
      • SSL_RSA_AES_128_SHA
      • SSL_RSA_AES_256_SHA
      • SSL_RSA_WITH_3DES_EDE_CBC_SHA
    • The following errors cause Connect:Direct FTP+ to terminate with a U4079 abend. These are critical functions and indicate a severe problem requiring immediate attention:
      CMSERR_BAD_RNG_OUTPUT
      Failure during random number generation
      GSK_ERR_RNG
      Failure during random number generation
      CMSERR_FIPS_KEY_PAIR_CONSISTENCY
      Failure when generating either an RSA or DSA keypair
      CMSERR_KATPW_FAILED
      Failure was encountered by the gsk_perform_kat API when performing known answer test against the System SSL cryptographic algorithm

Connect:Direct File Agent Special Considerations

Connect:Direct File Agent has the following special considerations:

  • Detect when VSAM files are created, but not when they are updated.
  • When watching for a VSAM file, it triggers a Process three times because it detects the creation of the cluster, data, and index portions of the VSAM dataset. To prevent the Process from being triggered unnecessarily, append.DATA to the data set name. To see an example involving a VSAM data file, see the Connect:Direct File Agent help.
  • Connect:Direct File Agent ignores PDSE data sets in a watch directory.

  • Do not use the Search tab on the IBM Connect:Direct configuration GUI Help when running the GUI as a z/OS batch job. It may terminate the configuration GUI session.
  • To avoid a parsing error when a substitution for a variable would include an open or closing parenthesis, enclose the variable in double quotes.

    For example, if %FA_FILE_FOUND. is to be passed as the Process Argument &DSN, specify the variable as:

    &DSN=”%FA_FILE_FOUND.”

Note: Variable values enclosed in quotes must not be concatenated with other values. Any attempt to do this will cause a submit failure or subsequent Process failure.
  • Some Hummingbird Exceed releases do not allow you to close the Help windows.

Upgrading IBM Connect:Direct

Review the following items before upgrading your existing IBM Connect:Direct system.

  • You must re-assemble and re-link all user exits after you complete the installation procedure.
  • If previous modifications were made to the DGASECUR and DGA$MFLG, update the DGAXAUTH macro with those modifications.
  • After installation, reassemble and link-edit your security module that uses the DMGSECUR macro (new element name is DGASECUR) to ensure that all enhancements are implemented. For information, see Implementing Security.
  • After IBM Connect:Direct files have been migrated, using these files with a previous release of IBM Connect:Direct results in the inability to view user comment fields in the network map. If you update the network map using an older version, any information stored in the comment fields may be lost.
  • For archive JCL and Processes that use STAT archive files or STAT ESDS, update the LRECL to 2048 and update all archive jobs and procedures, which must change the logical record length. You can update the LRECLs in advance and use the LRECL updates with any release.
  • To ensure above-the-line storage, calculate the difference between the maximum storage values used for BSAM data transfers (as specified by the MAXSTGIO initialization parameter) and change the JOBSTEP region accordingly. For additional information, see Improving Performance.
  • Performing an upgrade is similar to performing an initial installation. You can retain some or all data files created by the initial installation or as a result of the last upgrade.

    To retain existing IBM Connect:Direct files when you migrate, use the information in the following table. These files are required to fall back to the previous version.

Data Set Migration Considerations
NETMAP file Unload, delete, reallocate, and reload the network map. For more information, see Migrating an Existing Network Map.
AUTH, CKPT, and TYPE files Use IDCAMS REPRO to migrate the data to the new files. For the AUTH file, use this DCB information:
DCB=(DSORG=PS,RECFM=VB,LRECL=2052,BLKSIZE=24624)
For the CKPT (Checkpoint) file, use this DBC information:
DCB=(DSORG=PS,RECFM=VB,LRECL=20004,BLKSIZE=27998)
For the TYPE file, use this DCB information:
DCB=(DSORG=PS,RECFM=VB,LRECL=1934,BLKSIZE=29010)
STATS files See, Migrating of Existing STATS files steps below.
MSG file Because new messages exist in the MSG file, use the updated message file. Any user-defined messages can be loaded using the DGAJMSGL JCL in the $CD.SDGAJCL installation data set.
IBM Connect:Direct initialization parameters file After migrating data from a previous release, specify the IBM Connect:Direct initialization parameters TCQ=WARM and STAT.INIT=WARM and attempt the initialization.
Note: Make sure that all obsolete initialization parameters are removed before you start up. See the list of initialization parameters that are obsolete.

Migrating an Existing Network Map

To use an existing network map when you migrate to this version of IBM Connect:Direct:

  1. Run the DGAJUNLD job stream to unload the network map file of your current release by having your UNLOAD DD statement point to your upgrade release CNTL library.
  2. Make changes to the initialization parameters and edit the network map source, if necessary. Then run DGAJJDEF to redefine your network map, and DGAJLOAD to reload it.
  3. If you change the name of your network map:

    Update your NETDSN initialization parameter, DGAJBATC member in the $CD.SDGAJCL data set, and ISPF main menu panel (usually ISR@PRIM).

    Change the network map name in the MCS.SIGNON initialization parameter.

Migrating existing STATS files

There are considerable indexing improvements in the Statistics facility for Version 6 to allowing for the extended search capabilities by NODE.

Due to this, it is recommend that when migrating to Version 6 that you preserve your previous stats files by performing an archive on the previous version of Connect:Direct. Then perform a Stats Cold start using STAT.INIT=COLD command with the new version of Connect:Direct.

The same recommendation applies when backing out or migrating back to the previous release, archive the data and then Cold start.

Migrate Stats data to Version 6

If Cold start is not possible and you must have the Stat data active then the following procedure MUST be performed when migrating to Version 6 with Stats data from a previous version.

  1. Edit, customize and submit the DGAJBKEY member in the HDGA600.SDGAJCL data set to rebuild each STAT.KSDS from every STAT.ESDS from the previous release that contains active data.
  2. Ensure that the STEPLIB uses the HDGA600.SDGALINK to execute the version 6 DGADBKEY. For example, if you have 2 Stat file pairs and both ESDS01 and ESDS02 contain active data then you would need to execute DGADBKEY for both ESDS01 and ESDS02 to rebuild both KSDS01 and KSDS02.

    Example

    If there are 2 STAT file pairs and both ESDS01 and ESDS02 contain active data then execute DGADBKEY for both ESDS01 and ESDS02 to rebuild both KSDS01 and KSDS02.

Backout or Migrate STATS data back to Previous Version

To rollback to the previous release, data collected by Version 6 may not be compatible with that previous release and the following procedure must be performed to rollback to the previous version:

  1. Edit, customize and submit the DGAJBKEY member in the old version HDGAnnn.SDGAJCL data set to rebuild each STAT.KSDS from the STAT.ESDS from version 6 that contains active data.
  2. Ensure that the STEPLIB uses the old version HDGAnnn.SDGALINK to execute the old version DGADBKEY.

Using the DGA#FXAL REXX Exec

After updating a target library type, you can use the DGA#FXAL REXX exec to check the target library to ensure the members are all present and all aliases are assigned correctly, and to report on any extra members or aliases that are not in the list for that type. The default setting simply checks the PDS members against the list and reports on what is found. In addition, DGA#FXAL can fix or delete broken aliases. This exec uses the TSO DELETE and RENAME commands, which require exclusive control of the PDS. Any errors that cannot be fixed automatically by DGA#FXAL must be fixed manually by restoring the PDS from a backup or distribution library. These errors include deleted members, non-alias members that are supposed to be aliases, and aliases that are supposed to be non-alias members.

Syntax and Parameters

The DGA#FXAL REXX exec has the following format:

DGA#FXAL    pds   [type | . ]   [detaillevel | . ]   [fixlevel  | . ]

The DGA#FXAL REXX exec has the following parameters. The pds parameter is required and must be first. All parameters after the pds parameter are optional and positional, and can take the default by specifying a "." placeholder.

Parameter Description
pds A fully qualified DSN with or without quotation marks. A partitioned IBM Connect:Direct dataset of one of the supported types. A value of '?' requests that the syntax be displayed. The syntax is also displayed if there are any parameter errors.
type The pds type. Either specify one of the target library types listed or do not specify. If not specified, the lowest level qualifier of the PDS must be one of the listed target library types. For each type, you can specify either the new or old value – they produce the same result.
detaillevel Controls detail reporting. The default is 1.

The following values are valid for this parameter:

  • 0 reports everything, error and non-error alike.
  • 1 reports only error level 1 and higher.
  • 2 reports only error level 2 and higher
fixlevel Controls what fixes are attempted. Only levels 2–8 errors can be fixed. Default is 0. Valid values are 0, 2–8, and combinations of 2–8. The default is 0.

The following values are valid for this parameter:

  • 0 does not fix anything
  • 2 fixes level 2 errors.
  • 3 fixes level 3 errors
  • ... fixes level 4–7 errors
  • 8 fixes level 8 errors

For each pair or solo member listed for the type, an error level is set. See Error Level Explanation. If the error level is specified in fixlevel and the fix action in the table is not None, the pair is added to a fix list. After all pairs have been checked, if the fix list is not empty, you are prompted to continue. If you reply "Y," the fixes are attempted. If the fix for any pair fails, the exec continues with the next pair. A report is generated and written to both the TSO screen and to a PS dataset. The detail listings of expected and unexpected members are controlled by detaillevel. All fix attempts are reported.

Examples

  1. In this example, IBM Connect:Direct uses list for type SDGAPROC (PROCESS), reports everything, and fixes all that can be fixed.
    %DGA#FXAL DGA.SDGAPROC  .  0  2345678   
  2. In this example, IBM Connect:Direct uses list for type SDGAOPLS (OPLIST); and as a result of using all defaults, reports only errors and fixes nothing.
    %DGA#FXAL ‘DGA.SDGAOPLS'
  3. In this example,Connect:Direct again uses list for type SDGAOPLS (OPLIST) and all defaults. But in this scenario, the pds dsn still has the legacy low-level qualifier.
    %DGA#FXAL SYS5.CD.OPLIST
  4. This example is the same as the previous two examples but the pds dsn has an unsupported low level qualifier. The following example shows three different ways of coding this scenario.
    %DGA#FXAL SYS5.CD.OPERLIST OPLIST
    or
    %DGA#FXAL SYS5.CD.OPERLIST SDGAOPLS
    or
    Exec ‘DGA.SDGAISPC(DGA#FXAL)' ‘ SYS5.CD.OPERLIST SDGAOPLS'
    

Sample Reports

In this section, the following two scenarios are demonstrated:
  • The first report shows an example of how DGA#FXAL REXX is used to show Connect:Direct errors without fixing anything.
  • The second report shows how DGA#FXAL REXX is used with Connect:Direct to report everything in SYS5.CD.SDGAMAP and to fix all errors that can be fixed automatically.

The reports are broken into chunks to make them easier to read, and explanations of the reports follow the report samples.

Example–Show Errors But Do Not Fix Anything

DGA#FXAL         : 5.1.1 PM47625 20 Oct 2011 14:21:06                                  
Command entered  : %DGA#FXAL SYS5.CD.SDGAMAP                                        
Rexx exec source : CDZ5100.STG1.ISPCLIB(DGA#FXAL) via System-level CLIST DDNAME=SYSPROC
Report dsn       : USERID.CDFXAL.D2011293.T142106.LIST                                 
                                                                                       
Pds              : SYS5.CD.SDGAMAP                                                  
Type             : MAPLIB                                                              
DetailLevel      : 1                                                                   
FixLevel         : 0                                                                   
                                                                                       
Solo members     : 7                                                                   
TrueNames        : 6                                                                   
Aliases          : 14                                                                  
Orphans          : 12                                                                  
                                                                                       
Detail Report - Expected Members                                                       
                                                                                       
| Error Fix | Expected  Actual  | Expected  Actual  |                                  
| Level Req |  Member   Status  |  Alias    Status  |                                  
| ----- --- | -------- -------- | -------- -------- |                                  
|   8       | DGAAAER  NotInPDS | CDAER    Solo     |                                  
|   7       | DGAACPTR NotInPDS | CDCPTR   Alias    |                                  
|   6       | DGAACTIV NotInPDS | ACTIVITY Orphan   |                                  
|   9       | DGAACTR  Alias    | CDCTR    TrueName |                                  
|  10       | DGAADPTR Alias    | CDDPTR   NotInPDS |                                  
|  11       | DGAADTR  Alias    | CDDTR    Solo     |                                  
|   1       | DGAAEXEC NotInPDS | EXCEPT   NotInPDS |                                  
|  12       | DGAAFMCR Alias    | CDFMCR   Alias    |                                  
|  13       | DGAAFPTR Alias    | CDFPTR   Alias    |                                  
|   2       | DGAANPDS TrueName | NPDSCOPY NotInPDS |                                  
|   3       | DGAAPDS  Solo     | PDSCOPY  Orphan   |                                  
|  14       | DGAAPPSR Alias    | CDPSSR   Orphan   |                                  
|  15       | DGAAPTR  Orphan   | CDPTR    NotInPDS |                                  
|  16       | DGAARJTR Orphan   | CDRJTR   Solo     |                                  
|  17       | DGAARTTR Orphan   | CDRTTR   Alias    |                                  
|   4       | DGAARUNJ Solo     | RUNJOB   Alias    |                                  
|   5       | DGAARUNT TrueName | RUNTASK  Solo     |                                  
|  18       | DGAASDCR Orphan   | CDSDCR   Orphan   |                                  
|  19       | DGAASEC  Orphan   | SECURITY Orphan   |                                  
|   1       | DGAASFR  NotInPDS | CDSFR    NotInPDS |                                  
|   1       | DGAASTDC NotInPDS | CDSTDCR  NotInPDS |                                  
|   1       | DGAASUB  NotInPDS | SUBMIT   NotInPDS |                                  
|   1       | DGAASUM  NotInPDS | SUMMARY  NotInPDS |                                  
                                                                                       
Requestable fixes: 7                                                                   
                                                                                       
Detail Report - Unexpected Members                                                     
                                                                                       
| Error Fix |  Member   Actual  |                                                      
| Level Req |  Name     Status  |                                                      
| ----- --- | -------- -------- |                                                      
|  22       | DGAAT7   Solo     |                                                      
|  23       | DGAAT1   TrueName |                                                      
|  23       | DGAAT2   TrueName |                                                      
|  24       | DGAAT8   Alias    |                                                      
|  24       | DGAAT1A  Alias    |                                                      
|  25       | DGAAT4A  Orphan   |                                                      
|  25       | DGAAT9   Orphan   |
Summary Report                                                                               
                                                                                             
| Error Fix       |                                                                         |
| Level Req Count | Description                                    Fix Action               |
| ----- --- ----- | ---------------------------------------------- ------------------------ |
|   0           1 | TRU and ALI or SOL are correct                 None                     |
|   1           5 | TRU and ALI or SOL are not in PDS              None                     |
|   2           1 | TRU is a TrueName or Solo; ALI is not in PDS   Assign ALI               |
|   3           1 | TRU is a TrueName or Solo; ALI is an orphan    Delete and re-assign ALI |
|   4           1 | TRU is a TrueName or Solo; ALI is alien alias  Delete and re-assign ALI |
|   5           1 | TRU and ALI are TrueNames or Solos             Delete and re-assign ALI |
|   6           1 | TRU is not in PDS; ALI is an orphan            Delete ALI               |
|   7           1 | TRU is not in PDS; ALI is an alias             Delete ALI               |
|   8           1 | TRU is not in PDS; ALI is a TrueName or Solo   Delete ALI               |
|   9           1 | TRU is an alias of TrueName ALI                None                     |
|  10           1 | TRU is an alias; ALI is not in PDS             None                     |
|  11           1 | TRU is an alias; ALI is a TrueName or Solo     None                     |
|  12           1 | TRU and ALI are aliases of the same TrueName   None                     |
|  13           1 | TRU and ALI are aliases of different TrueNames None                     |
|  14           1 | TRU is an alias; ALI is an orphan              None                     |
|  15           1 | TRU is an orphan; ALI is not in PDS            None                     |
|  16           1 | TRU is an orphan; ALI is a TrueName or Solo    None                     |
|  17           1 | TRU is an orphan; ALI is an alias              None                     |
|  18           1 | TRU and ALI are orphans of the same TrueName   None                     |
|  19           1 | TRU and ALI are orphans of different TrueNames None                     |
|  20             | TRU is an alias; ALI is not expected           None                     |
|  21             | TRU is an orphan; ALI is not expected          None                     |
|  22           1 | Unexpected member found - Solo                 None                     |
|  23           2 | Unexpected member found - TrueName             None                     |
|  24           2 | Unexpected member found - Alias                None                     |
|  25           2 | Unexpected member found - Orphan               None                     |
                                                                                             
DGA#FXAL ending normally                                                                     

Example–Report Everything and Fix All Fixable Errors

DGA#FXAL         : 5.1.1 PM47625 20 Oct 2011 14:50:26                                        
Command entered  : %DGA#FXAL SYS5.CD.SDGAMAP . 0 2345678                                  
Rexx exec source : CDZ5100.STG1.ISPCLIB(DGA#FXAL) via System-level CLIST DDNAME=SYSPROC      
Report dsn       : EPETE1.CDFXAL.D2011293.T145026.LIST                                       
                                                                                             
Pds              : SYS5.CD.SDGAMAP                                                        
Type             : MAPLIB                                                                    
DetailLevel      : 0                                                                         
FixLevel         : 2345678                                                                   
                                                                                             
Solo members     : 7                                                                         
TrueNames        : 6                                                                         
Aliases          : 14                                                                        
Orphans          : 12                                                                        
                                                                                             
Detail Report - Expected Members                                                             
                                                                                             
| Error Fix | Expected  Actual  | Expected  Actual  |                                        
| Level Req |  Member   Status  |  Alias    Status  |                                        
| ----- --- | -------- -------- | -------- -------- |                                        
|   8   Yes | DGAAAER  NotInPDS | CDAER    Solo     |                                        
|   7   Yes | DGAACPTR NotInPDS | CDCPTR   Alias    |                                        
|   6   Yes | DGAACTIV NotInPDS | ACTIVITY Orphan   |                                        
|   9       | DGAACTR  Alias    | CDCTR    TrueName |                                        
|  10       | DGAADPTR Alias    | CDDPTR   NotInPDS |                                        
|  11       | DGAADTR  Alias    | CDDTR    Solo     |                                        
|   1       | DGAAEXEC NotInPDS | EXCEPT   NotInPDS |                                        
|  12       | DGAAFMCR Alias    | CDFMCR   Alias    |                                        
|  13       | DGAAFPTR Alias    | CDFPTR   Alias    |                                        
|   2   Yes | DGAANPDS TrueName | NPDSCOPY NotInPDS |                                        
|   3   Yes | DGAAPDS  Solo     | PDSCOPY  Orphan   |                                        
|  14       | DGAAPPSR Alias    | CDPSSR   Orphan   |                                        
|  15       | DGAAPTR  Orphan   | CDPTR    NotInPDS |                                        
|  16       | DGAARJTR Orphan   | CDRJTR   Solo     |                                        
|  17       | DGAARTTR Orphan   | CDRTTR   Alias    |                                        
|   4   Yes | DGAARUNJ Solo     | RUNJOB   Alias    |                                        
|   5   Yes | DGAARUNT TrueName | RUNTASK  Solo     |                                        
|  18       | DGAASDCR Orphan   | CDSDCR   Orphan   |                                        
|  19       | DGAASEC  Orphan   | SECURITY Orphan   |                                        
|   1       | DGAASFR  NotInPDS | CDSFR    NotInPDS |                                        
|   1       | DGAASTDC NotInPDS | CDSTDCR  NotInPDS |                                        
|   1       | DGAASUB  NotInPDS | SUBMIT   NotInPDS |                                        
|   1       | DGAASUM  NotInPDS | SUMMARY  NotInPDS |                                        
|   0       | DGAAWTOS TrueName | CDFWTOST Alias    |                                        
                                                                                             
Requestable fixes: 7                                                                         
Detail Report - Unexpected Members                                                           
                                                                                             
| Error Fix |  Member   Actual  |                                                            
| Level Req |  Name     Status  |                                                            
| ----- --- | -------- -------- |                                                            
|  22       | DGAAT7   Solo     |                                                            
|  23       | DGAAT1   TrueName |                                                            
|  23       | DGAAT2   TrueName |                                                            
|  24       | DGAAT8   Alias    |                                                            
|  24       | DGAAT1A  Alias    |                                                            
|  25       | DGAAT4A  Orphan   |                                                            
|  25       | DGAAT9   Orphan   |                                                            
                                                                                             
Summary Report                                                                               
                                                                                             
| Error Fix       |                                                                         |
| Level Req Count | Description                                    Fix Action               |
| ----- --- ----- | ---------------------------------------------- ------------------------ |
|   0           1 | TRU and ALI or SOL are correct                 None                     |
|   1           5 | TRU and ALI or SOL are not in PDS              None                     |
|   2   Yes     1 | TRU is a TrueName or Solo; ALI is not in PDS   Assign ALI               |
|   3   Yes     1 | TRU is a TrueName or Solo; ALI is an orphan    Delete and re-assign ALI |
|   4   Yes     1 | TRU is a TrueName or Solo; ALI is alien alias  Delete and re-assign ALI |
|   5   Yes     1 | TRU and ALI are TrueNames or Solos             Delete and re-assign ALI |
|   6   Yes     1 | TRU is not in PDS; ALI is an orphan            Delete ALI               |
|   7   Yes     1 | TRU is not in PDS; ALI is an alias             Delete ALI               |
|   8   Yes     1 | TRU is not in PDS; ALI is a TrueName or Solo   Delete ALI               |
|   9           1 | TRU is an alias of TrueName ALI                None                     |
|  10           1 | TRU is an alias; ALI is not in PDS             None                     |
|  11           1 | TRU is an alias; ALI is a TrueName or Solo     None                     |
|  12           1 | TRU and ALI are aliases of the same TrueName   None                     |
|  13           1 | TRU and ALI are aliases of different TrueNames None                     |
|  14           1 | TRU is an alias; ALI is an orphan              None                     |
|  15           1 | TRU is an orphan; ALI is not in PDS            None                     |
|  16           1 | TRU is an orphan; ALI is a TrueName or Solo    None                     |
|  17           1 | TRU is an orphan; ALI is an alias              None                     |
|  18           1 | TRU and ALI are orphans of the same TrueName   None                     |
|  19           1 | TRU and ALI are orphans of different TrueNames None                     |
|  20             | TRU is an alias; ALI is not expected           None                     |
|  21             | TRU is an orphan; ALI is not expected          None                     |
|  22           1 | Unexpected member found - Solo                 None                     |
|  23           2 | Unexpected member found - TrueName             None                     |
|  24           2 | Unexpected member found - Alias                None                     |
|  25           2 | Unexpected member found - Orphan               None                     |
                                                                                             
Do you wish to attempt the above 7 fixes?                                                    
Enter YES to attempt, NO to skip:                                                            
Reply is Y                                                                                   
                                                                                             
Fix Report                                                                                   
                                                                                             
Requested   fixes: 7                                                                         
Successful  fixes: 7                                                                         
Failed      fixes: 0                                                                         
                                                                                             
| Error | Expected Expected | Del Ren                             |                          
| Level | TrueName  Alias   | RC  RC  Message                     |                          
| ----- | -------- -------- | --- --- --------------------------- |                          
|   8   | DGAAAER  CDAER    |  0      ALI deleted                 |                          
|   7   | DGAACPTR CDCPTR   |  0      ALI deleted                 |                          
|   6   | DGAACTIV ACTIVITY |  0      ALI deleted                 |                          
|   2   | DGAANPDS NPDSCOPY |      0  ALI assigned                |                          
|   3   | DGAAPDS  PDSCOPY  |  0   0  ALI deleted and re-assigned |                          
|   4   | DGAARUNJ RUNJOB   |  0   0  ALI deleted and re-assigned |                          
|   5   | DGAARUNT RUNTASK  |  0   0  ALI deleted and re-assigned |                          
                                                                                             
DGA#FXAL ending normally                                                                     

Report Explanation

The DGA#FXAL report contains the following information.

Line Number / Field / Report Section Description
Line 1 The release level and maintenance level of DGA#FXAL, as well as the current date and time.
Line 2 The TSO command the user entered to invoke DGA#FXAL.
Line 3 The REXX exec source dataset and the ALTLIB DISPLAY line for the DGA#FXAL invocation.
Line 4 The DSN of the report dataset.
Utility Parameter Options Taken either from the DGA#FXAL parameters or the defaults.
Total Counts per PDS Type The total counts for each of the four types of members in the PDS, where:
  • Solo is a member without an alias
  • TrueName is a member with an alias
  • Alias is an alias that points to a TrueName
  • Orphan is an alias that points to a pds member that has been deleted
Detail Report - Expected Members This report is generated if at least one entry passes detaillevel filtering. For each entry in the DGA#FXAL exec list for the pds type, the actual status of the one or two member names is determined, and an error level is set based on the results. The error level is compared to detaillevel, and if it is greater than or equal to it, the detail line is written.
For each detail line, the following information is provided:
  • Error Level–A numeric error level. For more information, see Error Level Explanation.
  • Fix Req–Yes means a fix was requested for this error level. Else empty.
  • Expected Member–The first or only member name in the list entry.
  • Actual Status–One of the four PDS member types or “NotInPds”
  • Expected Alias–The second member name in the list entry, or empty
  • Actual Status–One of the four PDS member types, or “NotInPds”, or empty.

The total number of Expected Member detail lines with Yes in the Fix Req column.

Detail Report - Unexpected Members This report is generated if at least one member exists in the pds that is not in the DGA#FXAL list for the pds type. An error level is set based on what kind of pds member it is.
For each detail line, the following information is provided:
  • Error Level–A numeric error level. For more information, see Error Level Explanation.
  • Fix Req–Always empty.
  • Member Name–The unexpected member name
  • Actual Status–One of the four PDS member types.
Summary Report This report is always generated.
For each possible error level, the following information is provided:
  • Error Level–A numeric error level. For more information, see Error Level Explanation.
  • Fix Req–Yes means a fix was requested for this error level
  • Count–The number of times this error occurred
  • Description–A short description of the error. See below
  • Fix Action–The action that will be taken to fix the error if Fix Req is Yes
Attempt to Fix section If there are any fixable errors, the attempt-to-fix prompt and the user's response are given.
Fix Report If the response was ‘Y', the Fix report is generated, starting with lines giving the number of fixes requested, successful, and failed, followed by one fix detail line for each fix attempted.

Each detail line provides the following information:

  • Error Level–A numeric error level. For more information, see Error Level Explanation.
  • Expected TrueName–The first member name in the list entry
  • Expected Alias–The second member name in the list entry
  • Del RC– The TSO DELETE command reason code, if it was attempted
  • Ren RC–The TSO RENAME command reason code, if it was attempted
  • Message–A description of the results of the attempted fix action
Utility execution status Indicates if the DGA#FXAL ended normally or provides an error message indicating where the utility had a problem in execution, for example, DGA#FXAL ending - cannot ALLOC &pds with DISP=OLD where the prefix '&' denotes a variable, which will be substituted in the actual message.

Error Level Explanation

For all error level descriptions, the following meanings are in effect:
  • SOL–The member name in a list entry that has only one member name
  • TRU–The 1st member name in a list entry that has two member names
  • ALI–The 2nd member name in a list entry that has two member names
  • Solo–A member in pds that has no alias
  • TrueName–A member in pds that has one or more aliases
  • Alias–A member in pds that is an alias of a TrueName
  • Orphan–A member in pds that once was an Alias, but its TrueName no longer exists
  • Not in PDS–The member was not found in PDS
Error Level Description
0 TRU and ALI or SOL are correct. For a list entry with TRU and ALI, TRU is a TrueName and ALI is its Alias in pds. For a list entry with SOL, SOL is a non-alias member of pds. No fix is needed.
1 TRU and ALI or SOL are not in PDS. For a list entry with TRU and ALI, neither one was found in pds. For a list entry with SOL, SOL was not found in pds. No automatic fix is possible.
2 TRU is a TrueName or Solo; ALI is not in PDS. For a list entry with TRU and ALI, TRU was found in pds, and it may have one or more aliases, but ALI is not in pds. The fix is to assign ALI as an alias of TRU.
3 TRU is a TrueName or Solo; ALI is an orphan. For a list entry with TRU and ALI, TRU and ALI were both found in pds, but though TRU may have one or more aliases, ALI is not one of them. ALI is an alias of a member that no longer exists. The fix is to delete ALI, then re-assign it as an alias of TRU.
4 TRU is a TrueName or Solo; ALI is alien alias. For a list entry with TRU and ALI, TRU and ALI were both found in pds, but though TRU may have one or more aliases, ALI is not one of them. ALI is an alias of another (i.e. an alien) TrueName. To find out what that alien TrueName is, invoke the TSO command “LISTDS pds MEM” and look for ALI in each alias list. The fix is to delete ALI, then re-assign it as an alias of TRU.
5 TRU and ALI are TrueNames or Solos. For a list entry with TRU and ALI, TRU and ALI were both found in pds. TRU may have one or more aliases, but ALI is not one of them. ALI is a Solo or TrueName member. The fix is to delete ALI, then re-assign it as an alias of TRU.
Note: if ALI has any aliases, they will be orphaned.
6 TRU is not in PDS; ALI is an orphan. For a list entry with TRU and ALI, TRU was not found in pds. ALI is an alias of a member that no longer exists. The fix action is to delete ALI, though that only cleans up the orphan alias. Automatic recovery of the member is not possible.
7 TRU is not in PDS; ALI is an alias. For a list entry with TRU and ALI, TRU was not found in pds. ALI is an alias of another TrueName. The fix action is to delete ALI, though that only cleans up the alias. Automatic recovery of the member is not possible.
8 TRU is not in PDS; ALI is a TrueName or Solo. For a list entry with TRU and ALI, TRU was not found in pds. ALI is a Solo or TrueName member. The fix is to delete ALI, though that only cleans up the incorrect Solo or TrueName member.
Note: if ALI has any aliases, they will be orphaned.
Automatic recovery of the member is not possible.
9 TRU is an alias of TrueName ALI. For a list entry with TRU and ALI, TRU and ALI were both found in pds. ALI should be the alias and TRU should be the TrueName but, instead, their relationship is reversed. No automatic fix is supported.
10 TRU is an alias; ALI is not in PDS. For a list entry with TRU and ALI, TRU is an alias instead of a TrueName, and ALI was not found. No automatic fix is supported.
11 TRU is an alias; ALI is a TrueName or Solo. For a list entry with TRU and ALI, TRU is an alias instead of a TrueName, and ALI is a TrueName or Solo, instead of an alias of TRU. TRU is not an alias of ALI. No automatic fix is supported.
12 TRU and ALI are aliases of the same TrueName. For a list entry with TRU and ALI, TRU is an alias instead of a TrueName, and ALI is an alias of the same TrueName as TRU. No automatic fix is supported.
13 TRU and ALI are aliases of different TrueNames. For a list entry with TRU and ALI, TRU is an alias instead of a TrueName, and ALI is an alias of a different TrueName. No automatic fix is supported.
14 TRU is an alias; ALI is an orphan. For a list entry with TRU and ALI, TRU is an alias instead of a TrueName, and ALI is an alias of a member that no longer exists. No automatic fix is supported.
15 TRU is an orphan; ALI is not in PDS. For a list entry with TRU and ALI, TRU is an alias of a member that no longer exists instead of a TrueName, and ALI was not found in pds. No automatic fix is supported.
16 TRU is an orphan; ALI is a TrueName or Solo. For a list entry with TRU and ALI, TRU is an alias of a member that no longer exists instead of a TrueName, and ALI is a member with zero or more aliases instead of an alias of TRU. No automatic fix is supported.
17 TRU is an orphan; ALI is an alias. For a list entry with TRU and ALI, TRU is an alias of a member that no longer exists instead of a TrueName, and ALI is an alias of another TrueName instead of an alias of TRU. No automatic fix is supported.
18 TRU and ALI are orphans of the same TrueName. For a list entry with TRU and ALI, TRU and ALI are aliases of a single member that no longer exists instead of a TrueName. No automatic fix is possible.
19 TRU and ALI are orphans of different TrueNames. For a list entry with TRU and ALI, TRU is an alias of a member that no longer exists and ALI is an alias of a different member that no longer exists. No automatic fix is supported.
20 TRU is an alias; ALI is not expected. For a list entry with TRU only, TRU is an alias instead of a TrueName. No automatic fix is supported.
21 TRU is an orphan; ALI is not expected. For a list entry with TRU only, TRU is an alias of a member that no longer exists instead of a TrueName. No automatic fix is supported.
22 Unexpected member found - Solo. A Solo member was found in pds that does not appear in any list entry. No automatic fix is supported. This may or may not be an error.
23 Unexpected member found - TrueName. A TrueName member was found in pds that does not appear in any list entry. No automatic fix is supported. This may or may not be an error.
24 Unexpected member found - Alias. An alias was found in pds that does not appear in any list entry. No automatic fix is supported. This may or may not be an error.
25 Unexpected member found - Orphan. An alias of a member that no longer exists was found in pds that does not appear in any list entry. No automatic fix is supported.

Migrating CICS from Prior Releases

CICS uses different program names, map names, and transaction IDs. Refer to Activate the CICS Component in IBM Connect:Direct for z/OS CICS Administration and User Guide before continuing.

To use the current CONFIG file contents:

  1. Shut down the IBM Connect:Direct interface in the CICS region.
  2. To close the CONFIG file so that the buffers are committed and written, issue CICS commands, for example, CEMT SET FILE(CONFIG) CLOSE.
  3. Using IDCAMS, perform a REPRO of the CONFIG file to a new CONFIG file.
  4. To reactive CICS, restart the API interface.
  5. In a different CICS system, once the RDO updates have been applied and the Connect:Direct for z/OS Version 5.1 CICS modules loaded, run the Administrator transaction (DGAA) and go to the Configuration screen.

    Go to the Control Record screen to set the Transaction codes to reflect the changes made to the RDO source $CD.SDGACNTL(DGACCSD).

    Enter the CDA transaction and start the interface.

  6. Complete the CICS panels following the instructions in the procedure Build the CICS Configuration File through ISPF in IBM Connect:Direct for z/OS CICS Administration and User Guide.

Upgrading Connect:Direct File Agent

To take advantage of the command line in this version of Connect:Direct File Agent, modify the Java command line parameters after you install it.

If you are upgrading from an existing version:

Note: Files recorded in the checkpoint file are treated as if the new command line parameters had been active when the files were first discovered. You do not have to delete the checkpoint file.
  1. Install Connect:Direct File Agent into an empty directory.
  2. Copy the .ser and .ckpt files from the old to the new installation directory.
  3. Rename the old installation directory to an archive name.
  4. Rename the new installation directory to the primary name.