Professional Documents
Culture Documents
User Guide
r11
J02562-1E
This documentation and related computer software program (hereinafter referred to as the Documentation) is for the end users informational purposes only and is subject to change or withdrawal by Computer Associates International, Inc. (CA) at any time. This documentation may not be copied, transferred, reproduced, disclosed or duplicated, in whole or in part, without the prior written consent of CA. This documentation is proprietary information of CA and protected by the copyright laws of the United States and international treaties. Notwithstanding the foregoing, licensed users may print a reasonable number of copies of this documentation for their own internal use, provided that all CA copyright notices and legends are affixed to each reproduced copy. Only authorized employees, consultants, or agents of the user who are bound by the confidentiality provisions of the license for the software are permitted to have access to such copies. This right to print copies is limited to the period during which the license for the product remains in full force and effect. Should the license terminate for any reason, it shall be the users responsibility to return to CA the reproduced copies or to certify to CA that same have been 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 the end user or any third party for any loss or damage, direct or indirect, from the use of this documentation, including without limitation, lost profits, business interruption, goodwill, or lost data, even if CA is expressly advised of such loss or damage. The use of any product referenced in this documentation and this documentation is governed by the end users applicable license agreement. The manufacturer of this documentation is Computer Associates International, Inc. Provided with Restricted Rights as set forth in 48 C.F.R. Section 12.212, 48 C.F.R. Sections 52.227-19(c)(1) and (2) or DFARS Section 252.227-7013(c)(1)(ii) or applicable successor provisions.
Contents
Chapter 1: Introduction
Unicenter CA-XCOM Data Transport Flexibility ................................................. 1-1 Multiple User Interfaces ................................................................... 1-2 Unified Solution .......................................................................... 1-2 Unicenter CA-XCOM Data Transport Applications............................................... 1-2 File Transfer .............................................................................. 1-2 Type 2.1 Support .......................................................................... 1-3 TCP/IP Support .......................................................................... 1-3 Report Distribution ....................................................................... 1-4 RJE/NJE Replacement ..................................................................... 1-4 Unicenter CA-XCOM Data Transport Features................................................... 1-5 Modular Support of Most Systems .......................................................... 1-5 Data Link Types .......................................................................... 1-6 Standard Features ......................................................................... 1-6 Standard Functions ....................................................................... 1-6 High Capacity and Performance ............................................................ 1-7 Security .................................................................................. 1-8 Management ............................................................................. 1-8 Types of Transfers ............................................................................ 1-9 Answering Remote Requests ............................................................... 1-9 Invoking Unicenter CA-XCOM Data Transport ................................................. 1-10 Menu Interface .......................................................................... 1-10 Batch/Command Line Interface ........................................................... 1-10 Programming Interface ................................................................... 1-10 Unicenter CA-XCOM Data Transport Connectivity ............................................. 1-11 Network Levels in the SNA Model ............................................................ 1-12 The End User Level ...................................................................... 1-12 The Logical Level ........................................................................ 1-13 The Physical Level ....................................................................... 1-13
Contents
iii
Network Level Diagram................................................................... 1-14 Benefits of LU 6.2 (APPC) ................................................................. 1-14 Unicenter CA-XCOM Data Transport in the TCP/IP Network .................................... 1-16 TCP/IP Protocol Stack .................................................................... 1-16 Unicenter CA-XCOM Data Transport Nodes in the TCP/IP Network .......................... 1-18 Successful Send File Transfer Scenario .......................................................... 1-19 Send File Flowchart ....................................................................... 1-20 Conventions ................................................................................. 1-21 Commands .............................................................................. 1-21 Special Function Keys ..................................................................... 1-21 File and Program Names .................................................................. 1-21 Screen Output ............................................................................ 1-21
iv
User Guide
Modifying Post Processing Parameters ......................................................... Using xcompp ........................................................................... Modifying the Post Transfer Script ............................................................ Using xcomend .......................................................................... Modifying Printing Processes ................................................................. Using xcomlp ............................................................................ Customizing the Notification Process .......................................................... Using xcomntfy .......................................................................... xcom.trusted ................................................................................ Using xcom.trusted ...................................................................... Sample File .............................................................................. Reports Containing Machine Code Characters ..................................................
2-26 2-26 2-28 2-28 2-31 2-31 2-32 2-32 2-34 2-34 2-36 2-36
Contents
Creating a File on an IBM Mainframe .......................................................... 3-25 Parameters ............................................................................... 3-25 Tape Parameters for an IBM Mainframe .................................................... 3-31 Using the Send Report Command .............................................................. 3-35 Parameters ............................................................................... 3-35 Support for IBM Machine Code Characters.................................................. 3-39 Using the Send Job Command ................................................................. 3-40 Parameters ............................................................................... 3-41 Tracing Problems ............................................................................ 3-41 Return Codes ............................................................................ 3-42 Parameters ............................................................................... 3-43 Setting Up Log Files .......................................................................... 3-43 Parameters ............................................................................... 3-44 Setting File Type Conversion .................................................................. 3-44 Parameters ............................................................................... 3-45 Creating Custom Character Sets for File Conversion ............................................. 3-47 When to Use Character Conversion ........................................................ 3-47 Hexadecimal Numbers in Conversion Tables ................................................ 3-48 Customizing Default Character Sets ........................................................ 3-49 Specifying a Custom Character Set ......................................................... 3-50 Using Store and Forward ..................................................................... 3-51 When to Use ............................................................................. 3-51 Parameters ............................................................................... 3-52 Setting Password and User ID Security ......................................................... 3-52 Parameters ............................................................................... 3-53 Encrypting Parameter Values in Existing Configuration Files ..................................... 3-54 Syntax ................................................................................... 3-54 Options .................................................................................. 3-54 Procedure................................................................................ 3-55 Changing an Encrypted Value ............................................................. 3-55 Queuing Locally Initiated Transfers ............................................................ 3-56 Parameters ............................................................................... 3-57 Notifying of Transfer Completion .............................................................. 3-58 Example 1 ............................................................................... 3-58 Example 2 ............................................................................... 3-59 Parameters ............................................................................... 3-59 Checkpointing and Restarting Transfers ........................................................ 3-62 Parameters ............................................................................... 3-63
vi
User Guide
Contents
vii
OS/2 ........................................................................................ 5-10 Naming Conventions ..................................................................... 5-10 Restrictions .............................................................................. 5-11 Stratus ...................................................................................... 5-12 Naming Conventions ..................................................................... 5-12 Types of Files Supported .................................................................. 5-13 Tandem ..................................................................................... 5-14 Naming Conventions ..................................................................... 5-14 Example ................................................................................. 5-14 Types of Files Supported .................................................................. 5-15 File Type Specification .................................................................... 5-15 Remotely Initiated Send Requests .......................................................... 5-16 UNIX/Linux ................................................................................. 5-16 Naming Conventions ..................................................................... 5-16 Types of Files Supported .................................................................. 5-17 VM ......................................................................................... 5-17 Naming Conventions ..................................................................... 5-17 Types of Files Supported .................................................................. 5-18 DCB Information ......................................................................... 5-18 Restriction ............................................................................... 5-18 VSE ......................................................................................... 5-19 VSAM Naming Conventions .............................................................. 5-19 SAM Naming Conventions ................................................................ 5-20 TAPE Naming Conventions ............................................................... 5-22 DTF Information ......................................................................... 5-23 Types of Files Supported .................................................................. 5-24 Restrictions .............................................................................. 5-24 Windows 3.1, 95, and 98 ...................................................................... 5-25 Naming Conventions ..................................................................... 5-25 Restrictions .............................................................................. 5-26 Windows NT (2000, 2003, and XP) ............................................................. 5-27 Naming Conventions ..................................................................... 5-27 Types of Files Supported .................................................................. 5-28 Additional Features ....................................................................... 5-29 Destination Printer Information ............................................................ 5-30 Restrictions .............................................................................. 5-31
viii
User Guide
Appendix A: Parameters
Using Unicenter CA-XCOM Data Transport Parameters .......................................... A-1 Parameter Format ......................................................................... A-2 Syntax ................................................................................... A-2 Guidelines ............................................................................... A-2 List of Parameters............................................................................. A-3 AGE_TIME ............................................................................... A-3 ALLOCATION_TYPE ..................................................................... A-4 ATOE_FILENAME ........................................................................ A-4 BLKSIZE ................................................................................. A-4 CARRIAGE_CONTROL_CHARACTERS.................................................... A-5 CARRIAGE_FLAG ........................................................................ A-5 CHECKPOINT_COUNT ................................................................... A-6 CLASS ................................................................................... A-6 CODE_FLAG ............................................................................. A-6 CODETABL .............................................................................. A-7 COMPRESS .............................................................................. A-7 CONTROL ............................................................................... A-8 CONVERT_CLASSES ..................................................................... A-8 COPIES .................................................................................. A-8 CREATE_DIR ............................................................................ A-9 DATACLAS .............................................................................. A-9 DEBUG_FLAG ........................................................................... A-9 DEN .................................................................................... A-10 DESTINATION .......................................................................... A-10 DESTINATION_TYPE .................................................................... A-10 DISPLAY_PASSWORD_IN_TRACE ....................................................... A-10 DISPOSITION ........................................................................... A-11 DOMAIN ............................................................................... A-11 DSNTYPE ............................................................................... A-11
Contents
ix
EOL_CLASSES .......................................................................... ETOA_FILENAME ...................................................................... EXPDT ................................................................................. EXPIRATION_TIME ..................................................................... FCB .................................................................................... FILE_OPTION .......................................................................... FILE_OPTION_RF ....................................................................... FORM .................................................................................. HOLDFLAG ............................................................................ INTERNAL_CONVERSION_TABLES ..................................................... LABEL ................................................................................. LABELNUM ............................................................................ LCLNTFYL ............................................................................. LOCAL_FILE ........................................................................... LOCAL_FILE_RF ........................................................................ LOCAL_FILE_SJ ........................................................................ LOCAL_FILE_SR ........................................................................ LOCAL_NOTIFY ........................................................................ LRECL ................................................................................. MAX_QUEUE_ENTRIES ................................................................. MAX_REMOTE_TCP .................................................................... MAX_SESSIONS_ENTRIES .............................................................. MAXRECLEN ........................................................................... METACODE_CLASSES .................................................................. MGMTCLAS ............................................................................ NOTIFY_NAME ........................................................................ NOTIFYL ............................................................................... NOTIFYR ............................................................................... NOTIFY_TERM ......................................................................... NUMBER_OF_RETRIES ................................................................. NUM_OF_DIR_BLOCKS ................................................................. PASSWORD ............................................................................ PORT .................................................................................. PRIMARY_ALLOC ...................................................................... PRIORITY .............................................................................. PROTOCOL ............................................................................ QUEUE................................................................................. QUEUE_PATH .......................................................................... RMTNTFYL............................................................................. RECORD_FORMAT ..................................................................... REMOTE_FILE ..........................................................................
A-12 A-12 A-12 A-13 A-13 A-13 A-14 A-15 A-15 A-15 A-16 A-16 A-17 A-17 A-18 A-18 A-18 A-19 A-19 A-19 A-20 A-20 A-20 A-20 A-21 A-21 A-21 A-22 A-22 A-22 A-23 A-23 A-23 A-23 A-24 A-24 A-24 A-25 A-25 A-26 A-27
User Guide
REMOTE_FILE_RF ....................................................................... A-28 REMOTE_SYSTEM....................................................................... A-28 REMOTE_SYSTEM_RF ................................................................... A-29 REMOTE_SYSTEM_SJ .................................................................... A-29 REMOTE_SYSTEM_SR ................................................................... A-29 REMOVE_TRAIL_BLANKS ............................................................... A-30 REPORT_TITLE ......................................................................... A-30 RESTART_SUPPORTED .................................................................. A-31 RETPD .................................................................................. A-31 RETRY_TIME............................................................................ A-31 SAVE_PASSWORD_IN_CNF ............................................................. A-31 SECONDARY_ALLOC ................................................................... A-32 SECURE_SOCKET ....................................................................... A-32 SESSIONS_FILE ......................................................................... A-32 SHELL_CMD ............................................................................ A-33 SOCK_DELAY ........................................................................... A-33 SOCK_RCV_BUF_SIZE ................................................................... A-33 SOCK_SEND_BUF_SIZE ................................................................. A-34 SPOOL_FLAG ........................................................................... A-34 START_DATE ........................................................................... A-34 START_TIME ............................................................................ A-34 STAT_FREQUENCY ..................................................................... A-35 STORCLAS .............................................................................. A-35 SYSTEM_USER_DATA ................................................................... A-35 TAPE ................................................................................... A-35 TCP_CMD .............................................................................. A-36 TEMPDIR ............................................................................... A-36 TP_CMD ................................................................................ A-36 TRACE_PATH........................................................................... A-36 TRANSFER_NAME ...................................................................... A-37 TRANSFER_TYPE ....................................................................... A-37 TRANSFER_USER_DATA ................................................................ A-38 TRUNCATION .......................................................................... A-38 TRUSTED ............................................................................... A-38 TRUSTED_PATH ........................................................................ A-38 TXPI_BUF_SIZE ......................................................................... A-39 TXPI_RECEIVE_TIMEOUT ............................................................... A-39 TXPI_SEND_CHECK_FREQ .............................................................. A-39 TXPI_TERM_TIMEOUT .................................................................. A-39 UMASK ................................................................................. A-40 UNIT ................................................................................... A-40
Contents
xi
UNITCT ................................................................................ UNIT_RF ............................................................................... USE_TP_SECURITY ..................................................................... USERID ................................................................................ VERSION ............................................................................... VOLCT ................................................................................. VOLUME ............................................................................... VOLUME_RF ........................................................................... VOLSQ ................................................................................. XCOM_CONFIG_SSL .................................................................... XCOM_PASSWORD ..................................................................... XCOM_SHOW_CIPHER ................................................................. XCOM_TRUSTED_OVR ................................................................. XCOM_USERID ......................................................................... XCOMPRE_LOCAL ..................................................................... XENDCMD ............................................................................. XIDEST ................................................................................. XLOGFILE .............................................................................. XLPCMD ............................................................................... XLUNAME ............................................................................. XMODE ................................................................................ XNODESPEC ........................................................................... XNOTIFYCMD .......................................................................... XPPCMD ............................................................................... XPRECMD .............................................................................. XTRACE ................................................................................
A-40 A-40 A-40 A-41 A-41 A-41 A-41 A-41 A-42 A-42 A-42 A-42 A-43 A-43 A-43 A-43 A-44 A-44 A-44 A-45 A-45 A-45 A-45 A-46 A-46 A-46
Appendix B: Messages
Error Messages................................................................................ B-1 Message ID Content ....................................................................... B-1 List of Messages ............................................................................... B-3
xii
User Guide
Logical Unit Types ............................................................................ C-3 Independent Logical Units ..................................................................... C-4 Systems Supporting ILUs .................................................................. C-4 Software Version Support for ILUs ......................................................... C-4 LU 6.2 Independent Implementations ....................................................... C-5 Direct Sessions with Dependent Logical Unit ................................................ C-5 PU Type ................................................................................. C-5
Contents
xiii
Notifying of Transfer Completion ............................................................. Procedure............................................................................... Pull-Down Menus ....................................................................... Fields .................................................................................. Pushbuttons ............................................................................ Using the Conversion Dialog ................................................................. Procedure............................................................................... Using the Miscellaneous Window ............................................................. Procedure............................................................................... Pull-down Menu ........................................................................ Fields .................................................................................. Pushbuttons ............................................................................ Using the Secure Socket Window ............................................................. Accessing the Secure Socket Window ...................................................... Procedure............................................................................... Pushbuttons ............................................................................ Viewing Transfer Status...................................................................... Procedure............................................................................... Fields .................................................................................. Pushbuttons ............................................................................ Viewing Transfer Status After Completion ..................................................... Procedure............................................................................... Fields .................................................................................. Pushbutton ............................................................................. Viewing Log Information .................................................................... Procedure............................................................................... Pushbuttons ............................................................................
D-29 D-29 D-30 D-30 D-31 D-31 D-31 D-33 D-34 D-35 D-35 D-36 D-36 D-36 D-37 D-37 D-37 D-38 D-38 D-39 D-39 D-40 D-40 D-40 D-41 D-41 D-41
xiv
User Guide
Environmental Information Inventory ...................................................... E-8 Documentation ........................................................................... E-9 Contacting Customer Support................................................................. E-12 Product Releases and Maintenance ............................................................ E-12
Index
Contents
xv
Chapter
Introduction
Unicenter CA-XCOM Data Transport for UNIX and Linux supports high-speed transfers of files between all supported systems. Users can send files from the local system to remote systems across an SNA or TCP/IP network and actively retrieve files from those systems. The remote system can initiate the same range of transfer capabilities as the local system. This chapter is a general introduction to the features and functions of Unicenter CA-XCOM Data Transport across all of its platforms. This guide is for users of Unicenter CA-XCOM Data Transport on UNIX and Linux platforms, including System Administrators and Applications Programmers. To install this product, you need the following:
Knowledge of UNIX or Linux administration and communication concepts Superuser (root) privilege
For more information on prerequisites, see the Unicenter CA-XCOM Data Transport Getting Started for the appropriate version of UNIX or Linux.
Sharing data Automating data and report distribution Providing unattended back-up to dissimilar computers Controlling and auditing network activities Maintaining network security
The applications listed above are only a few examples. Under most conditions, Unicenter CA-XCOM Data Transport will allow file sharing between any two computers or workstations within your company.
Introduction
11
Unified Solution
Unicenter CA-XCOM Data Transport is a unified solution. It supports communications over more hardware environments than any other software product on the market today. Unicenter CA-XCOM Data Transport also has a solid technology base. By using LU 6.2 or TCP/IP communications protocols, Unicenter CA-XCOM Data Transport uses state-of-the-art technology, protecting your companys investment for years to come.
When these functions are combined, a wide variety of applications are possible.
File Transfer
Unicenter CA-XCOM Data Transport supports high-speed file transfers between all supported processors. In some environments, you can start thousands of transfers with a single operation. Parallel sessions are possible in varying degrees throughout the product line. You can totally automate Unicenter CA-XCOM Data Transport transfers. On a PC, you can be actively engaged in the use of other applications (for example, word processing) while receiving or transmitting files in the background. Comprehensive management tools allow for effective central-site control of Unicenter CA-XCOM Data Transport activity, including advanced problem determination features.
12
User Guide
Unicenter CA-XCOM Data Transport will support transfers between any two processors in an SNA network or a TCP/IP network with one of the following methods:
By using the z/OS, VM, or VSE mainframes for store-and-forward Through Independent Logical Unit (ILU) support over the SNA (Systems Network Architecture) backbone Through use of the TCP/IP network
TCP/IP Support
Unicenter CA-XCOM Data Transport provides support for performing transfers using TCP/IP between platforms that support TCP/IP and that are running Advantage CA-XCOM Data Transport 3.0 or 3.1 or Unicenter CA-XCOM Data Transport r11. TCP/IP support is provided between the following platforms:
AS/400 Linux S/390 Linux x86 Netware Open VMS Alpha OS/2 Tandem Windows NT family (2000, 2003, and XP) z/OS Most common UNIX platforms
Introduction
13
You can use the Secure Socket Layer (SSL) to perform secure TCP/IP transfers between platforms running Unicenter CA-XCOM Data Transport r11 and above that support secure (SSL) TCP/IP. A secure (SSL) TCP/IP transfer allows for the encryption of the transmitted data. It also adds a digital signature to the encryption of the transmitted data. Unicenter CA-XCOM Data Transport uses OpenSSL to implement a secure (SSL) TCP/IP transfer. Secure (SSL) TCP/IP support is provided between the following platforms:
Linux S/390 Linux x86 Windows NT family (2000, 2003, and XP) z/OS Most common UNIX platforms
Report Distribution
Unicenter CA-XCOM Data Transport allows z/OS, VM, VSE, AS/400 and VAX users to take print output from any supported system and automatically transfer it to another system for printing. The application programs producing the reports do not require any modification to support Unicenter CA-XCOM Data Transport report distribution, and no operator intervention is required at either end.
RJE/NJE Replacement
Current Remote Job Entry (RJE) systems contain inherent limitations. Remote computers can submit work to the host for processing and receive print data, but the host cannot distribute processing tasks to idle processors residing on the network. A further concern for data processing managers is the requirement that users have an understanding of Job Entry Subsystem (JES) commands to operate the system. Unicenter CA-XCOM Data Transport avoids these limitations by taking advantage of the LU 6.2 and TCP/IP protocols, providing a peer-to-peer relationship between all supported systems. Any Unicenter CA-XCOM Data Transport system is able to send and receive batch jobs and print data from any other Unicenter CA-XCOM Data Transport system without formatting constraints. For example, an AS/400 user can do the following:
Automatically retrieve files from a number of attached PCs. Process the data. Generate a report.
14
User Guide
Send one copy of the report back to the source PC for printing. Send another to the z/OS mainframe for printing on a high-speed printer.
You can easily implement Unicenter CA-XCOM Data Transport without any changes to your existing applications programs. Data is transferred with greater integrity and higher efficiency.
DG/UX AViiON Digital Unix HP 9000 IBM AS/400 IBM z/OS IBM RS/6000 IBM VM IBM VSE Linux Intel Linux S/390 NCR 3000 (AT&T) NetWare OpenVMS Alpha OS/2 PC or MS-DOS SCO UNIX Sequent
Introduction
15
SINIX for Transit Stratus Sun OS Sun Solaris Tandem VAX VMS Windows NT family (2000, 2003, and XP)
SDLC Local Area Network (such as Token Ring and Ethernet) All SNA data links, including channel-based links TCP/IP
Standard Features
The following features are standard to Unicenter CA-XCOM Data Transport:
Simple installationYou can install Unicenter CA-XCOM Data Transport without hardware changes to your system. Initiation by either computer (any-to-any)Either computer can send and retrieve data files. Low maintenanceThere are no hooks or patches into the operating system. Choice of interfacesYou can choose from batch/command line, programming (on supported platforms), and menu interfaces.
Standard Functions
The following functions are offered over most of the Unicenter CA-XCOM Data Transport platforms:
CompressionUnicenter CA-XCOM Data Transport compresses repeating characters prior to transmission. In certain cases, throughput is significantly higher than the actual line speed. ASCII/EBCDIC translationUnicenter CA-XCOM Data Transport can translate data between ASCII and EBCDIC formats as needed. Translations occur on the ASCII-based platform.
16
User Guide
Checkpoint/RestartAll components of Unicenter CA-XCOM Data Transport running Version 2 or higher support checkpoint/restart. Transfers that are stopped or fail prior to completion automatically resume, continuing from the last checkpoint. Store-and-forwardUsers communicating through a common z/OS, VM, or VSE hub can perform data transfers even if the remote (target) machine is not communicating or turned on at the time of the initial transfer. Unicenter CA-XCOM Data Transport ensures that the data is sent as soon as the device is available. Remote spoolingUnicenter CA-XCOM Data Transport allows VM, z/OS, VSE, AS/400 and VAX users the following reporting options:
Introduction
17
Security
Unicenter CA-XCOM Data Transport interfaces with the native security facility on all supported systems. When security is invoked, you are required to provide a valid user ID and password for the remote system. For example, in the z/OS environment, an interface is also provided to IBM RACF, eTrust CA-ACF2, and eTrust CA-Top Secret. On PC and OS/2 versions of Unicenter CA-XCOM Data Transport (where no native security exists), you are given the option to create an ID/password table to prevent unauthorized use of Unicenter CA-XCOM Data Transport. Unlike most other communication facilities, Unicenter CA-XCOM Data Transport encrypts passwords. This ensures that communications line tapping will not breach security. Unicenter CA-XCOM Data Transport also has special security capabilities that can help data centers handle their individual needs. For example, the security features allow installer specification of what can or cannot run under the privileges of someone other than the person requesting the transmission. These security features can also force user IDs from both remote computers to be the same or different. For otherwise unsatisfied security needs, Unicenter CA-XCOM Data Transport supplies a variety of user exits that enable user-written security packages to be fully integrated.
Management
An important feature for any enterprise-wide information product is the ability to effectively control and manage the distribution of files and work throughout the network. Unicenter CA-XCOM Data Transport systems maintain a comprehensive log of all transfer activity. Utilities are provided to allow the system administrator to view the log on-line and modify the status of pending or currently active transfers. Details of any transfer errors are also maintained in the log, allowing rapid problem determination and resolution. In addition, messages signaling the completion of any Unicenter CA-XCOM Data Transport event can be directed to a user in the network.
18
User Guide
Types of Transfers
Types of Transfers
Unicenter CA-XCOM Data Transport will perform the following transfers:
Sending filesWith Unicenter CA-XCOM Data Transport, a computer can send a data file to be stored on the remote system in a specified remote file. Sending reportsUnicenter CA-XCOM Data Transport can send a report to be printed on a remote system. Sending batch jobs for executionUnicenter CA-XCOM Data Transport can send a job to be executed on a remote system. Retrieving filesWhen a computer starts the transmission request, it can also retrieve a file from a remote computer and store it in a specified local remote file.
FilesThe remote system can send or retrieve files. When a remote system requests Unicenter CA-XCOM Data Transport to send it a file, Unicenter CAXCOM Data Transport tries to allocate and open the file. Unicenter CAXCOM Data Transport then reads the data records and transfers them to the remote system. JobsThe remote system can use Unicenter CA-XCOM Data Transport to submit jobs to the local system. ReportsThe remote system can send the local system a report. Unicenter CA-XCOM Data Transport writes the report to an output spool file. Each supported system has unique spooling capabilities and Unicenter CA-XCOM Data Transport has been designed to provide a high degree of print redirection and manipulation.
Introduction
19
Menu Interface
The menu interface provides a simple, fill-in-the-blanks approach to file transfer. You are prompted for required information and can use the extensive on-line help facilities provided with each product. Unicenter CA-XCOM Data Transport menus always have the look and feel appropriate to the system on which they are running. For example, the micro-computer platforms use a graphical user interface with menus, tool bars, pop-up windows, and so on, while z/OS is written for the popular ISPF Dialog Manager.
Programming Interface
Any programming language supporting callable subroutines can call Unicenter CA-XCOM Data Transport. Examples of calling programs from common programming languages are given in each user manual, for supported platforms. UNIX and Linux versions of Unicenter CA-XCOM Data Transport allow direct API calls to specific Unicenter CA-XCOM Data Transport functions in addition to allowing you to run Unicenter CA-XCOM Data Transport as a subprogram. Unicenter CA-XCOM Data Transport also provides exits on many systems, allowing you to control or be informed about certain Unicenter CA-XCOM Data Transport events involving security and completed transfers.
110
User Guide
Note: For information about the platforms for which TCP/IP support is provided, see TCP/IP Support in this chapter.
Introduction
111
Type of transfer (send report, file, or job, or receive file) Name of the local file Name of the remote file to create, append, or replace
The request is then processed by the Unicenter CA-XCOM Data Transport transaction program on the local system which sends an allocate verb and header record to the remote system to establish an LU 6.2 session. When a session is established and all of the parameters are confirmed by the remote system, Unicenter CA-XCOM Data Transport on the local system will send the file, broken into data records, across the physical connection. The remote Unicenter CA-XCOM Data Transport transaction program is then invoked by the allocate verb sent by the local system (some systems cannot be automatically invoked and must already be active to receive the allocate verb). The remote transaction program then creates or opens the requested file, receives the data records, and places them in the file. When all the records have been received, Unicenter CA-XCOM Data Transport on the remote system will send a trailer record to the local system stating the number of records transmitted.
112
User Guide
Introduction
113
Local User
Remote User
CA-XCOM
CA-XCOM
LU 6.2
LU 6.2
LOGICAL LEVEL
PHYSICAL LEVEL
Physical Connection
114
User Guide
Improved Throughput When Unicenter CA-XCOM Data Transport uses the LU 6.2 protocol, it does not place hardware restrictions on the size of the data that it sends. RJE-based data transfer packages (LU Type 1) limit the size of a data frame (RU) to 80 characters, while 3270-based transfer packages (LU Type 2) often limit the size to 1,920 characters, the size of one screen. LU 6.2 allows RU sizes of up to 65,536 characters. Each transmitted string of data is wrapped in a protocol envelope. Larger RU sizes, such as those allowed with Unicenter CA-XCOM Data Transport, mean less protocol overhead and a higher percentage of actual data traveling across your communication links. P = Protocol Overhead
Data
Introduction
115
Network layer (the lowest protocol layer) Internetwork layer Transport layer Application layer (the highest protocol layer)
Each layer in the TCP/IP protocol stack provides services to the layer above it and uses the services below it. The table below lists the protocols and functions that form the content of each layer of the TCP/IP protocol stack. (The table shows only partial contents for the top and bottom layer.) TCP/IP Protocol Layer Network layer Protocols and Functions Token Ring Ethernet X.25 and so on Internet Protocol (IP) Control Message Protocol (ICMP) Address Resolution Protocol (ARP) Transmission Control Protocol (TCP) User Datagram Protocol (UDP) Telnet File Transfer Protocol (FTP) Simple Mail Transfer Protocol (SMTP) Domain Name System (DNS) Sockets and so on
Internetwork layer
116
User Guide
A summary of the services that each layer of the protocol stack performs in the TCP/IP network A description of the protocols that are particularly important for the functioning of Unicenter CA-XCOM Data Transport as a TCP/IP network node
Network Layer The Network layer provides a set of protocols, Token Ring, Ethernet, and so on, which define how data are transported over different physical networks. Internetwork Layer The protocols of the Internetwork layer provide connection services for TCP/IP. The protocols in this layer connect physical networks and transport protocols. The Internet Protocol (IP) of this layer integrates different physical networks into a unified logical network known as the internet and provides for the universal addressing of computers (hosts) in a TCP/IP (internet) network. IP uses a 32-bit number (IP address) that identifies both a physical network and a specific computer within that network. The IP address is the basic transport mechanism for routing data from a source computer to a destination computer. However, IP does not ensure a reliable communication, because it does not require that the computers participating in a data exchange acknowledge the reception of the transmitted data. The reliability of communication is implemented at the next higher protocol layer. Transport Layer The protocols of the Transport layer allow communication between application programs. The Transmission Control Protocol (TCP) of this layer establishes a connection between the sender and receiver and provides a continuous communication service with reliability of transmissions. TCP divides the data to be transmitted into smaller units (packets, datagrams), sends them individually using IP, and reassembles them at the destination node, comparing the received data with the data that were sent. TCP is capable of determining if the two are the same. If they are not (that is, data were lost or damaged during transmission), TCP resends the missing data.
Introduction
117
Application Layer The Application layer, which is built on the services of the Transport layer, provides a number of applications that allow users to use network services (terminal-to-terminal communication, data transfer, electronic mail, and so on). The Application layer provides an application programming interface known as Sockets for communications applications. Unicenter CA-XCOM Data Transport uses this component of the Application layer to transfer files to machines in a TCP/IP network.
118
User Guide
4.
5.
Introduction
119
120
User Guide
Conventions
Conventions
This guide contains information about the operation and usage of Unicenter CA-XCOM Data Transport for UNIX and Linux. The following conventions are used throughout this guide.
Commands
User input is in the following font and placed on separate lines:
xcom62 -c1 -f filename.cnf
Items that you must replace with specific values when you issue the commands are in italics. For example, replace filename.cnf with the name of your configuration file. Type commands exactly as they appear, paying attention to upper and lower case. Command options appear set off by brackets [ ]. Do not type the brackets in a command. Grouped commands of more than six lines are set off in a simulated screen display. All of the commands for Unicenter CA-XCOM Data Transport for UNIX and Linux follow the conventional rules and grammar of the UNIX and Linux command languages.
Screen Output
Computer output is in the following font and placed on separate lines:
XCOMU0082I xcomd: stop request accepted.
Introduction
121
Chapter
Operating Environment
The components used for scheduling transfers, handling files, and managing Unicenter CA-XCOM Data Transport resources are the xcomd command and the daemon process, the global parameters, the session control parameters, the queue, and the use of post processing scripts. A substantial portion of a users ability to control Unicenter CA-XCOM Data Transport comes from the use of files to set variables that govern the system's behavior. These files are xcom.glb and xcom.cnf.
Before executing a file transfer request, be sure that you have properly set up your directories and path variables. The Unicenter CA-XCOM Data Transport daemon, xcomd, is installed in the /etc directory, except for the following: For HP-UX systems, xcomd is installed in the /opt/xcom/bin directory. For OSF Digital UNIX and Linux, xcomd is installed in the /usr/sbin directory.
Be sure that your PATH variable is set so that your shell can find xcom62 or xcomtcp, or both. The /usr/spool/xcom directory is the default repository that Unicenter CA-XCOM Data Transport uses for logging and for configuration information. For further information about PATH and directory defaults, see the appendix Parameters.
Operating Environment
21
Transfer Protocols
Unicenter CA-XCOM Data Transport supports transfer protocols, such as Ethernet, SDLC, Token Ring, and TCP/IP. SNA/APPC Protocols For SNA/APPC protocols, support is based on the capabilities provided by the particular APPC vendor. For SNA/APPC, Unicenter CA-XCOM Data Transport requires an active LU 6.2 session to transfer files. When an LU 6.2 session is established, local users can begin using Unicenter CA-XCOM Data Transport to initiate transfers. TCP/IP Protocols The TCP/IP component of Unicenter CA-XCOM Data Transport supports TCP/IP protocols for performing transfers between Advantage CA-XCOM Data Transport Version 3.x or Unicenter CA-XCOM Data Transport r11 platforms using TCP/IP.
Parameter Values
Parameter values can be defined to Unicenter CA-XCOM Data Transport as indicated in the table below. The values take precedence depending on where they are specified. The order in which parameter values take precedence is as follows: Order of Precedence 1 Parameter Value Explanation Specified in Command Line If the user specifies a value for a parameter on the command line, this overrides every other specification in the files or the program. If the value is specified in the xcom.cnf file, or in a user-customized configuration file, filename.cnf, it overrides the value in the xcom.glb file for locally initiated transfers.
xcom.cnf or filename.cnf
22
User Guide
Order of Precedence 3
Parameter Value Explanation Specified in xcom.glb If the value is specified in the xcom.glb file, it overrides the value in the program. The values specified in xcom.glb are generally used by the system administrator to start Unicenter CA-XCOM Data Transport and for remotely initiated transfers. If a value is not specified anywhere, the program has its own defaults.
Program Defaults
Parameter Format
The Unicenter CA-XCOM Data Transport parameters consist of assignment statements. The format for assignment statements is as follows:
PARAMETER_NAME (Always all uppercase, with underscore character (_) when indicated.) An equal sign (=) A character string terminated by a newline
Example In the following example, the parameter EXPIRATION_TIME is set to a value of 6000 seconds.
EXPIRATION_TIME=6000
This controls the maximum time in seconds that a transaction is held in the transfer queue.
Operating Environment
23
Guidelines
The following guidelines apply when using Unicenter CA-XCOM Data Transport parameters:
When you type trailing spaces and tabs from the command line as part of a parameter value, they are stripped by the command line processor (the shell). When you type trailing spaces and tabs into a file or script with an editor, such as vi, they are treated as part of a parameter value. These trailing spaces and tabs should be removed. If they are not removed they can cause confusion and unpredictable or undesirable results. Empty lines and lines beginning with a pound sign (#) are discarded.
Examples In the following examples, the spacespacespace represents trailing spaces. If you type the following at the command line, the trailing spaces are ignored:
xcom62 -c1 LOCAL_FILE=xyzspacespacespace
If you type the following into any configuration file using an editor, the spacespacespace would be treated as part of the name of the LOCAL_FILE.
LOCAL_FILE=xyzspacespacespace
Schedules and synchronizes transfer requests. Controls shared memory for transfers. Establishes the default parameter values by reading the parameter file, xcom.glb and then running in the background. Controls the automatic restart of locally initiated transfers. Writes queue information out to disk periodically. Deletes aged entries from the queue.
24
User Guide
Notifies a local user by executing the xcomntfy script when LOCAL_NOTIFY is required. Communicates with active or pending transfers to terminate a transfer.
Options
The following table explains the options for xcomd:
Option
-c[y]
Explanation Kill the daemon process and free shared memory. This option will stop the daemon while transfers are running. Note: Use this option as a last resort because it brings the scheduler down immediately, whether or not there are running or scheduled transfers. If you use the -c option without the y, the system prompts you to confirm this action by typing y for yes. WARNING! This option can cause corruption of the CA-XCOM queue. It can shut down Unicenter CA-XCOM Data Transport while it is updating the queue. To prevent problems, delete the queue by deleting all files in /usr/spool/xcom/Q after issuing this command.
Operating Environment
25
Option
-dtracelevel
Explanation Set the trace level of the daemon process to tracelevel. Higher numbers (up to 10) give more trace information. The trace goes to stderr. For more information, see the topic, Tracing Problems, in the chapter "The Command Line Interface." Report the release level of xcomd and exit. Stop the Unicenter CA-XCOM Data Transport daemon by sending a request to the scheduler. Note: This option does not stop the daemon immediately if there is an active transfer going on.
-r -s
Starting xcomd
To start xcomd, enter the following command at the system prompt:
/etc/xcomd
Note: The full path name specification for xcomd is /etc/xcomd, except for the following:
For HP-UX systems, use /opt/xcom/bin/xcomd. For OSF Digital UNIX and Linux systems, use /usr/sbin/xcomd.
26
User Guide
For a full list of Unicenter CA-XCOM Data Transport parameters, see the appendix Parameters. For an explanation of parameters and defaults see Using Unicenter CA-XCOM Data Transport Parameters in this chapter. This section contains information about using the global parameters contained in the xcom.glb file.
Parameters
The parameters for xcom.glb are shown below. AGE_TIME The number of seconds before waiting queue entries are removed from queue. If the value is 0, the waiting queue entries never age and are never removed from the queue. Range: 0 to 86313600 (999 days) Default: 432000 (5 days) ATOE_FILENAME The name of the file containing the ASCII-to-EBCDIC character conversion table. This is a custom file used only for specifying custom translation tables from ASCII to EBCDIC, if needed. Range: 0 to 256 characters Default: /usr/spool/xcom/convtab/atoe.tab, except for the following:
CONVERT_CLASSES A character string containing print classes for EBCDIC-to-ASCII conversions to be performed. For incoming report transfers only. Range: 1 to 64 characters Default: None
Operating Environment
27
DISPLAY_PASSWORD_IN_TRACE Determines if Unicenter CA-XCOM Data Transport displays password information in the trace files. Range: The range of values is listed in the following table: Value YES ENCRYPT NO
Default: NO
Description Encrypted and plain text passwords are displayed in the trace files. Encrypted passwords are displayed in the trace files. Encrypted passwords are displayed in the trace files
EOL_CLASSES A character string containing print classes for an ASCII newline that is appended to each record. For incoming report transfers only. Range: 1 to 64 characters Default: None ETOA_FILENAME The name of the file containing the EBCDIC-to-ASCII character conversion table. This is a custom file used only for creating custom translation tables from EBCDIC to ASCII, if needed. Range: 1 to 256 characters Default: /usr/spool/xcom/convtab/etoa.tab, except for the following:
28
User Guide
EXPIRATION_TIME The maximum time, in seconds, that a transaction is held in the transfer queue after completion. When the maximum time is reached, all references to the transaction are removed from the queue, including trace files and temporary files. Note: If EXPIRATION_TIME is set to no value in xcom.glb, the program default of 6000 is used. Range: 0 to 32767 Default: 6000 INTERNAL_CONVERSION_TABLES Indicates whether internal or external conversion tables should be used for ASCII-to-EBCDIC conversion and EBCDIC-to-ASCII conversion. The external conversion files may be customized to meet your needs. For the appropriate directory and file name, see ATOE_FILENAME and ETOA_FILENAME. Range: The range of values is listed in the following table: Value YES NO Default: YES MAX_QUEUE_ENTRIES The maximum number of entries allowed in the transfer queue. Once the maximum number of queue entries is reached, subsequent transfer attempts are rejected by Unicenter CA-XCOM Data Transport. Note: This value depends on the memory available when Unicenter CA-XCOM Data Transport is started. Range: 0 to 32767 The value cannot be set larger than the maximum allowed shared memory segment divided by 512. Default: 50 Description Use internal conversion tables. Use the external tables contained in ATOE_FILENAME and ETOA_FILENAME.
Operating Environment
29
MAX_REMOTE_TCP The maximum number of simultaneous remote TCP/IP transfers accepted by Unicenter CA-XCOM Data Transport. Transfers received after this limit has been reached are rejected. Note: Setting this parameter to 0 prohibits any remote transfers from taking place. Range: 0 to 999
Default: 32
MAX_SESSIONS_ENTRIES The maximum number of partners that can be described in the XCOM.SES file. Range: 1 to 999 Default: 15 METACODE_CLASSES Classes of print jobs saved in metacode format, a variable length record format. For incoming report transfers only. Range: 0 to 64 characters Default: None PROTOCOL The type of communication protocols to use. Range: The range of values is listed in the following table: Value SNA TCPIP Default: SNA Note: If only the TCP/IP Component is installed with the base components of Unicenter CA-XCOM Data Transport, the default value is TCPIP. Description For transfers using SNA/APPC communication protocols For transfers using TCP/IP communication protocols
210
User Guide
REMOVE_TRAIL_BLANKS Indicates whether or not to remove the blanks at the end of each record when a remote partner is sending a file. Range: Yes or No Default: No QUEUE_PATH Directory containing the transfer queue data files. Range: 0 to 256 characters Default: /usr/spool/xcom/Q, except for the following:
For HP-UX systems: /var/spool/xcom/Q For OSF Digital UNIX systems: /var/opt/xcom/Q
SAVE_PASSWORD_IN_CNF Determines if the xcomtool GUI saves the password in the .CNF file. Range: The range of values is listed in the following table: Value YES NO Default: NO SESSIONS_FILE The path name of the xcom.ses file, which tells Unicenter CA-XCOM Data Transport how many sessions can be used by a single LU. Range: 0 to 256 characters Default: /usr/spool/xcom/config/xcom.ses, except for the following:
Description The xcomtool GUI saves the password in the .CNF file in encrypted format. The xcomtool GUI does not save the password in the .CNF file and blanks the password field out after each operation.
For HP-UX systems: /var/spool/xcom/config/xcom.ses For OSF Digital UNIX systems: /var/opt/xcom/config/xcom.ses
Operating Environment
211
SHELL_CMD Name of the command that runs jobs, reports, notification scripts, and post processing scripts on the local system. Range: 1 to 256 characters Default: /bin/ksh SOCK_DELAY TCP/IP socket option TCP_NODELAY. Refers to the Nagle algorithm for send coalescing. By default, small sends may be delayed. Should have no impact for normal Unicenter CA-XCOM Data Transport record sizes. Used for TCP/IP transfers only. Note: Socket options affect the way Unicenter CA-XCOM Data Transport uses the TCP/IP stack implementation. Range: The range of values is listed in the following table: Value YES NO
Default: YES
Description Small sends may be delayed. (Does not disable the Nagle algorithm.) All sends are immediate. (Disables the Nagle algorithm.)
SOCK_RCV_BUF_SIZE TCP/IP Socket option SO_RCVBUF. The buffer size for receives. Use zero for the default size provided by the socket implementation. The value for SOCK_RCV_BUF_SIZE can be smaller than the value for TXPI_BUF_SIZE. Used for TCP/IP transfers only. Note: Socket options affect the way Unicenter CA-XCOM Data Transport uses the TCP/IP stack implementation. Range: 0 to 65536 Default: 0
212
User Guide
SOCK_SEND_BUF_SIZE TCP/IP Socket option SO_SNDBUF. The buffer size for sends. Use zero for the default size provided by the socket implementation. The value for SOCK_SEND_BUF_SIZE can be smaller than the value for TXPI_BUF_SIZE. Used for TCP/IP transfers only. Note: Socket options affect the way Unicenter CA-XCOM Data Transport uses the TCP/IP stack implementation. Range: 0 to 65536 Default: 0 STAT_FREQUENCY Indicates the frequency with which transfer statistics are made available to xcomqm. Intended for tuning high-speed links. Longer values help performance, but byte/record counts in xcomqm -D may be slightly behind the actual counts. Range: 1 to 9999 records Default: 10 TCP_CMD Path and name of the Unicenter CA-XCOM Data Transport program started by the XCOMD service that is used for queued locally initiated transfers, and for all remotely initiated transfers for TCP/IP protocols. Range: 0 to 256 Default: /usr/lib/xcom/xcomtcp, except for the following:
For HP-UX systems: /opt/xcom/lib/xcomtcp For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcomtcp
TEMPDIR Indicates the directory in which temporary files for jobs and reports can be created. Range: 1 to 256 characters Default: /tmp
Operating Environment
213
TP_CMD Command to start a transaction program using SNA protocols. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcomtp For HP-UX systems: /opt/xcom/lib/xcomtp For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcomtp
TRACE_PATH The directory containing the trace data files. Range: 0 to 256 characters Default: /usr/spool/xcom/trace, except for the following:
For HP-UX systems: /var/spool/xcom/trace For OSF Digital UNIX systems: /var/opt/xcom/trace
TRUSTED_PATH The directory containing the trusted files. Default: /user/spool/xcom/trusted TXPI_BUF_SIZ For TCP/IP transfers, the internal buffer size for sends and receives. The default size allows multiple Unicenter CA-XCOM Data Transport records to be received in a single socket call. With this default, if your Unicenter CA-XCOM Data Transport record size is less than 32K, Unicenter CA-XCOM Data Transport will attempt to receive multiple records in a single socket call. Used for TCP/IP transfers only. Range: 0 to 65536 Default: 32768
214
User Guide
TXPI_SEND_CHECK_FREQ Indicates the frequency that Unicenter CA-XCOM Data Transport checks to see if incoming error information is available when sending data. For example, if the value is 5, a check is made every fifth time that data is sent, to determine if data is available for receiving. Larger values give better performance. Smaller values minimize the sending of data after the partner reports an error. Used for TCP/IP transfers only. Range: 0 to 9999 Default: 10 TXPI_TERM_TIMEOUT Maximum wait time, in seconds, for partner to terminate TCP/IP communications. If a transfer terminates normally, both sides of the conversation coordinate the termination, and there should be no need to wait. This timeout will occur only during an error in the termination of the connection. Used for TCP/IP transfers only. Range: 0 to 999 seconds Default: 20 seconds UMASK Used to set the permissions assigned to a file when the file is being created and received on the system for the first time. The value is expressed as an octal number (base 8). The octal number has the same meaning as in the standard umask command. Range: 000 to 777 Default: 022 XCOM_PASSWORD This parameter specifies the default password for remotely initiated transfers. Range: 0 to 31 characters Default: None
Operating Environment
215
XCOM_TRUSTED_OVR Specifies if the user is permitted to override the user ID by using the USERID parameter for locally initiated trusted transfers. If XCOM_TRUSTED_OVR is set to YES, the user is permitted to override the user ID by using the USERID parameter. If it is set to NO, the user ID of the process that initiated the transfer is used. Range: YES, NO, Y, N Default: NO XCOM_USERID This is the default user ID for remotely initiated transfers. Range: 0 to 12 characters Default: xcom XCOMPRE_LOCAL Indicates whether the xcompre script file for a locally initiated transfer should be run. Range: YES, NO Default: NO XENDCMD The name of the post processing command optionally invoked by the Unicenter CA-XCOM Data Transport transfer program after any type of transfer is finished, whether successful or not. Invoked after partner communications have ended. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcomend For HP-UX systems: /opt/xcom/lib/xcomend For OSF Digital UNIX system: /usr/opt/xcom/lib/xcomend
216
User Guide
XLPCMD Name of the post-processing command used to send print jobs to the spooler. For incoming reports only. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcomlp For HP-UX systems: /opt/xcom/lib/xcomlp For OSF Digital UNIX system: /usr/opt/xcom/lib/xcomlp
XNOTIFYCMD Path name of the command that Unicenter CA-XCOM Data Transport will use to notify users on the local system of the completion of a transfer. This is normally a shell script that composes a message and invokes mail or write as appropriate. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcomntfy For HP-UX systems: /opt/xcom/lib/xcomntfy For OSF Digital UNIX system: /usr/opt/xcom/lib/xcomntfy
XPPCMD Path name of the command used for user-defined post processing, for file transfers only. Only used when the local system is receiving the file. Range: 0 to 64 characters Default:
Operating Environment
217
XPRECMD Path name of the command used for user-defined pre-allocation processing for locally and remotely initiated transfers. Specify this parameter in xcom.glb to invoke the pre-allocation exit xcompre. Range: 0 to 64 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcompre For HP-UX systems: /opt/xcom/lib/xcompre For OSF Digital UNIX system: /usr/opt/xcom/lib/xcompre
XTRACE Indicates the level of desired execution for incoming transfers. Range: The range of values is listed in the following table: Value 0 1 to 8 9 10 Default: 0 Description No tracing. Levels of tracing from 1 (lowest) to 8 (highest). Show the contents of the data buffers. Includes levels 1-9 with additional detailed technical information.
218
User Guide
You limit the number of sessions available for Unicenter CA-XCOM Data Transport transfers by setting a parameter in the xcom.ses file for each connection to the remote Unicenter CA-XCOM Data Transport partner. If a session is not available for immediate use, the transfer is queued for subsequent execution. To specify a remote system, as indicated in the example in this section, replace connection_profile with the destination address or name specified by the user in the remote system parameter. (REMOTE_SYSTEM, REMOTE_SYSTEM_RF, REMOTE_SYSTEM_SJ, or REMOTE_SYSTEM_SR.) Note: Unicenter CA-XCOM Data Transport reserves memory for information about the number of sessions for each destination based upon the connection_profile entries in this file. Transfers Using SNA For transfers using SNA, the parameter name connection_profile represents the remote system name or partner LU name to which the session limit is applied. Transfers Using TCP/IP For transfers using TCP/IP, specify the format of the remote system that is consistent with your sites use of the remote system parameters. If the IP address is used, specify connection_profile in the form of 123.123.78.91. If host names or domain names are used in the remote system parameter, specify connection_profile in the appropriate form of the name. You may specify a connection_profile for each form of address or name that is used. Note that if the XCOM.SES file does not have an entry for the host name or domain name, the value of the connection_profile will default to one. Example In the following example, a sample xcom.ses file of session control parameters for Unicenter CA-XCOM Data Transport partners is shown. It indicates that a maximum of 8 sessions can be used at any one time for locally initiated transfers to a remote system identified as XCOMQA3 and a maximum of 4 sessions can be used at any one time for locally initiated transfers to a remote system identified as XCOMQA4. It indicates that a maximum of 4 simultaneous transfers can go to 123.123.78.91.
# connection_profile=number_of_sessions_allowed # XCOMQA3=8 XCOMQA4=4 123.123.78.91=4
Operating Environment
219
You can use more than one option on a command line. You can also use the same option more than once. Each option must be separated by a space. These options can be listed in any order, but note that when the shell encounters options such as the -r option, it performs the command and exits xcomqm without reading the rest of the command line.
Options
The following table explains the options for xcomqm: Option
-r -Aentryname -Centryname -Dentryname -Hentryname
Function Display the release level of xcomqm and exit. Release a held transfer. Get a trace of a transfer. Display details about a queue entry. Hold a scheduled transfer.
220
User Guide
Option
-L[a]
Function List your queued transfers. Use -La for all queued transfers. Remove a queue entry. Force the entry to be removed from the queue. Use this command when you want to remove a transfer that is still active. Remove all completed or scheduled entries from the queue. If you use this option on an active transfer, it will interrupt the transfer.
-Rentryname -Rfentryname
-R*
-Tentryname -T[f]entryname
Terminate an active transfer. Force termination of the transfer. Use this command when you want to remove a transfer that is still active. Note: Please be aware that when using SNA/APPC protocols, the TP will ABEND and it may be necessary to restart the underlying SNA software. When using TCP/IP, xcomtcp will ABEND.
-Sentryname -Eentryname -d
Suspend a transfer. Resume a suspended transfer. Display debugging information. Display the help menu. Display logging text for transfer.
no option -z
Note: entryname represents the Transaction ID, which is the six-digit name of the transfer entry in the queue.
Operating Environment
221
Description Entries in the log longer than the number of days specified are purged. The name of the log file to clean (optional). The default is the XCOM.LOG in the current directory. If not specified, the log file name defaults to /var/spool/xcom/xcom.log.
Example
CLEANLOG 5
This command removes entries in XCOM.LOG that are older than 5 days.
222
User Guide
Using xcompre
An xcompre shell script is provided with Unicenter CA-XCOM Data Transport as a sample script, and is available online. It is an option to run an exit on the local system before the transfer starts. It can be tailored to meet individual user requirements. The xcompre exit collects and passes transfer ID information (tid) to xcomqm, along with the parameter values specified by the available options, g and -p. Note: The -g and -p options, for use with xcomqm, as shown in the sample script are intended only for use with this exit. The pre-allocation exit is invoked after Unicenter CA-XCOM Data Transport receives the Unicenter CA-XCOM Data Transport header from the remote partner, but before the transfer commences. For information about shells and script changes, see Shells and Script Changes in this chapter. For remotely initiated transfers, the pre-allocation exit is invoked after Unicenter CA-XCOM Data Transport receives the Unicenter CA-XCOM Data Transport header from the remote partner, but before the transfer commences. For locally initiated transfers, the pre-allocation exit is invoked based on the value specified by the global parameter XCOM_LOCAL. If XCOMPRE_LOCAL is set, the preallocation exit is invoked before sending the Unicenter CA-XCOM Data Transport header to a remote partner.
Operating Environment
223
xcompre Options
The available options for xcompre and their associated parameters are listed below: Option
-g
Function Passes transfer ID to xcomqm, and retrieves the values for the following parameters from the local database and passes them to standard output: FILE_OPTION FILE_TYPE LOCAL_FILE REMOTE_FILE REMOTE_LU TRANSFER_TYPE USERID
-p
Changes the values for the following parameters based upon the specified transfer ID (tid) and applies them to the transfer: FILE_OPTION LOCAL_FILE REMOTE_FILE
224
User Guide
'egrep' 'payroll|finance' /tmp/$tid.userlog if [ $? -ne 0 ] then exit 100 else xcomqm -p$tid LOCAL_FILE=/u/jc/test/000040.local REMOTE_FILE=abcdefg \ FILE_OPTION=CREATE \ 2>&1 > /tmp/$tid.errlog exit 0 fi
Example In the above sample script, the only file transfers permitted are ones that have payroll or finance in the USERID. If the USERID does not meet one of these criteria, the transfer is rejected. If the transfer is permitted, then the -p option is used to specify the values to use for LOCAL_FILE, REMOTE_FILE and FILE_OPTION.
Operating Environment
225
Process Summary
To modify a post processing script, follow these steps: 1. 2. 3. Invoke an editor, such as vi, and open the script you want to modify. Go to the bottom of the script. Add the desired commands to the end of the script. Note: If the script ends with an exit statement, enter your commands above exit. 4. Save the file and exit the editor.
Troubleshooting
For script problems, uncomment the debugging statements included in the sample script and rerun the script. The debugging section is clearly marked. Debugging information is written to the file specified in the first statement.
Using xcompp
The xcompp script is a shell script that contains parameters for post processing of a file. After a successful file transfer is received, xcompp is always turned on (available) and will get invoked automatically. It is only invoked for incoming files. It does not work for jobs or reports. You can reference the parameters in xcompp by putting commands at the end of the script. xcompp does not take any visible actions if no modifications are made to the script.
226
User Guide
This procedure is invoked by the Unicenter CA-XCOM Data Transport transaction program after the transfer is finished before the conversation is terminated. Not every argument will be populated; the values contained in the arguments depend on those provided by the remote system.
###### START OF DEBUG SECTION ###### ###### ###### UNCOMMENT THE LINES BELOW TO DEBUG THIS SCRIPT ###### #exec >> /tmp/xcompp.out #exec 2>&1 #set -vx #PS4='[$0: $LINENO]+ ' #export PS4 ###### END OF DEBUG SECTION ###### compression=$1 # Compression flag shift notify_flag=$1 # Notify flag shift notify_name=$1 # Notify Name shift remoteuser=$1 # Notify User shift filetype=$1 # File type (Whether it's file, job or report) shift fileaction=$1 # File action (Create, replace or append) shift datasettype=$1 # Dataset type shift carriage_flag=$1 # Carriage return flag shift code_flag=$1 # Code flag shift recfm=$1 # Record format shift lrecl=$1 # Logical record length shift remote_reqno=$1 # Remote request Number shift local_reqno=$1 # Local Request number shift group=$1 # Group name shift sysdata=$1 # System Dependent User Data shift xferdata=$1 # Transfer Dependent User Data shift ident=$1 # Ident shift truncation_flag=$1 # Truncation flag shift tmp_file=$1 # Local temporary file name shift file=$1 # Local file name shift remote_file=$1 # Remote file name
Operating Environment
227
Example The example below shows how you change the permissions on a received file by adding the following to the end of the xcompp script:
chmod 777 $tmp_file
This will change the permissions on tmp_file to read, write, and execute. Note: You must type a $ sign before the variable to reference the variable in the xcompp script.
Using xcomend
The xcomend script is a script that is invoked by a Unicenter CA-XCOM Data Transport transfer program. This script can be used as provided, or it can be used by system administrators to modify printing commands and parameters to provide additional information about all types of transfers (remote and local; send and receive; successful or failed). Different arguments are passed depending on whether the transfer is a file, job, or report. This script can be used to define the context of the transfer, such as indicating that a remotely initiated send transfer failed with a particular message. Sample Script The following is the sample xcomend script:
#!/bin/sh # @(#)xcomend.sh 1.0 # # # # # 8/1/96 12:23:04
This procedure is invoked by the Unicenter CA-XCOM Data Transport transfer program after the transfer is finished (whether successful or not). Not every argument will be populated; the values contained in the arguments depend on those provided by the remote system.
###### START OF DEBUG SECTION ###### ###### ###### UNCOMMENT THE LINES BELOW TO DEBUG THIS SCRIPT ###### #exec > /tmp/xcomend.$1.out
228
User Guide
#exec 2>&1 #set -vx #PS4='[$0: $LINENO]+ ' #export PS4 ###### END OF DEBUG SECTION ###### # # The first parameters are supplied for any type of transfer.
local_reqno=$1 # local request number/tid (000000 if unassigned) shift initiator=$1 # LOCAL or REMOTE shift transfer_type=$1 # FILE or JOB or REPORT shift direction=$1 # SEND or RECEIVE shift restarting=$1 # RESTARTING or FIRST_TRY shift start_time=$1 # Start time of transfer shift end_time=$1 # End time of transfer shift remote_system=$1 # Remote system name shift status=$1 # Status of transfer shift error=$1 # XCOM file transfer numeric error code shift msg=$1 # error code translated to message text shift status_msg=$1 # status message from partner when error on remote sys shift remoteuser=$1 shift # Remote user
remote_reqno=$1 # Remote request Number shift group=$1 # Group name shift sysdata=$1 # System Dependent User Data shift xferdata=$1 # Transfer Dependent User Data shift transfer_name=$1 # Transfer Name shift tmp_file=$1 shift file=$1 shift remote_file=$1 shift # Local temporary file name # Local file name # Remote file name
carriage_flag=$1 # Carriage return flag shift code_flag=$1 # Code flag shift compression=$1 shift file_recs=$1 shift file_bytes=$1 # Compression flag # No. of records read/written # No. of bytes read/written
Operating Environment
229
sent/received
sent/received
if [ $transfer_type = "FILE" ] then fileaction=$1 # File action (C, R, or A for create, replace, or append) shift datasettype=$1 # Dataset type shift recfm=$1 # Record format shift lrecl=$1 # Logical record length shift truncation_flag=$1 # Truncation flag shift # # The next group of parameters are supplied for report transfers only
elif [ $transfer_type = "REPORT" ] then jobname=$1 # Job name field from JES shift jobnumber=$1 # Job number field from JES shift class=$1 # print class shift copies=$1 # Number of copies to print shift form=$1 # Type of form to print this job on. shift recfm=$1 # Record format of incoming print job. shift lrecl=$1 # Logical record length of incoming report. shift blksize=$1 # Block size of incoming report. shift ucs_name=$1 # Name of UCS to be used for this print job. shift fcb=$1 # Name of FCB (form control block) for this report. shift room_number=$1 # Room number field from JES. shift programmer_name=$1 # Programmer name field from JES. shift tso_notify=$1 # TSO notify field from JES. shift destination=$1 # Destination printer specification. shift carriagecontrol=$1 # Type of carriage control characters being used. shift # # There are no extra parameters for remote jobs fi #
230
User Guide
exit 0
Using xcomlp
The xcomlp script is a shell script that is invoked by the Unicenter CA-XCOM Data Transport transaction program (XCOMSEND). The contents of the parameters passed to xcomlp depend on what is supplied on the initiating side of the transfer. The only field that can be absolutely relied on is the file name. The sample procedure also assumes that the COPIES= field is valid, in addition to assigning each incoming argument to an appropriately named variable. For information regarding the processing machine code characters, see the section, Reports Containing Machine Code Characters, later in this chapter. Sample Script The following is the sample xcomlp script:
#!/bin/sh # @(#)xcomlp.sh 1.1 # # # # # # # 3/27/92 20:19:33
This procedure is invoked by the Unicenter CA-XCOM Data Transport transaction program after an incoming print request is received. Not every argument will be populated; the values contained in the arguments depend on those provided by the remote system. The most general case is that of a host partner that uses the user exit EXIT02 to extract and transmit the JES parameters for the print job. In all cases, the file and copies parameters will be valid.
###### START OF DEBUG SECTION ###### ###### ###### UNCOMMENT THE LINES BELOW TO DEBUG THIS SCRIPT ###### #exec > /tmp/xcomlp.out #exec 2>&1 #set -vx #PS4='[$0: $LINENO]+ ' #export PS4 ###### END OF DEBUG SECTION ###### rluname=$1 shift jobname=$1 # Remote lu name # Job name field from JES
Operating Environment
231
shift jobnumber=$1 # Job number field from JES shift class=$1 # print class shift copies=$1 # Number of copies to print shift form=$1 # Type of form to print this job on. shift recfm=$1 # Record format of incoming print job. shift lrecl=$1 # Logical record length of incoming report. shift blksize=$1 # Block size of incoming report. shift ucs_name=$1 # Name of UCS to be used for this print job. shift fcb=$1 # Name of FCB (form control block) for this report. shift room_number=$1 # Room number field from JES. shift programmer_name=$1 # Programmer name field from JES. shift tso_notify=$1 # TSO notify field from JES. shift file=$1 # Name of temporary file into which XCOM 6.2 has placed report shift destination=$1 # Destination printer specification. shift nodespec=$1 # connection profile name shift carriagecontrol=$1 # Type of carriage control characters being used. lp ${copies:+-n$copies} < $file
Using xcomntfy
The supplied script uses mailx(1) to notify the named user logins. Sample Script The following is the xcomntfy script:
#!/bin/sh # @(#)xcomntfy.sh 1.2 3/28/92 08:42:41 # This procedure (xcomntfy) is called by Unicenter CA-XCOM Data Transport # transaction program when the NOTIFY parameter is set to YES. #
232
User Guide
# # # # # # # # # # # # # # # # # # # # # # # #
The arguments passed to the xcomntfy procedure are: -q q_entryname -h how The following $how will be treated as 'M' (mail to user) by default: T - TSO; R - ROSCOE; C - CICS; L - another LU; M - mail to user. The following $how will be treated as 'W' (write to user) by default: W - write to user. The following $how will be treated as 'A' (write to all users) by deflt: A - all; -u login Note: 1.Other information about the transfer can be extracted from the output of xcomqm -D$q_entryname command for postprocessing 2.If specified in $how method fails, the mail message will be sent to $LOGNAME or root.
#uncomment following to diagnose problems with script # set -xv if [ `uname` = 'SunOS' ] then MAIL=Mail else MAIL=mailx fi # required for HPUX-10 if [ `uname` = 'HP-UX' ] then PATH=/opt/xcom/bin:$PATH fi while test $# -gt 0 do case "$1" in -h) how="$2" shift;; -q) q_entryname="$2" shift;; -u) login="$2" shift;; esac shift done case "$how" in [TRCLMV]* ) xcomqm -D$q_entryname| $MAIL -s "xfer $q_entryname" ${login:-${LOGNAME:-root}} >/dev/null 2>&1 ;; [W]* ) xcomqm -D$q_entryname| if [ "$login" != "" ] then (write $login || $MAIL -s "xfer $q_entryname" ${login:-${LOGNAME:-root}}) >/dev/null 2>&1 fi
Operating Environment
233
xcom.trusted
;; [A]* ) xcomqm -D$q_entryname| (wall || $MAIL -s "xfer $q_entryname" ${login:-${LOGNAME:-root}}) >/dev/null 2>&1 ;; * ) ;; esac # put user defined notification # script here exit 0
xcom.trusted
The xcom.trusted file contains a list of user names and, optionally, group user IDs that are considered to be valid initiators of trusted transfers. Unicenter CA-XCOM Data Transport for UNIX and Linux can initiate a transfer with itself and other platforms and respond to trusted transfers. An xcom.trusted file must be defined for each trusted transfer expected from a remote system. The xcom.trusted file allows a transfer to be sent without specifying a user ID and password, as long as the UNIX or Linux system it is being transferred to has a system-defined xcom.trusted file, with the same user ID as the sending system. The user ID specified on the initiating system must match the user ID of the person logged on to the initiating system. In this case, even if no user ID or password is provided, the transfer is allowed to proceed. Entries in the file identify users on the remote system and optional group user ID. If the optional group user ID is not present, the first user ID will be used to perform the transfer.
Using xcom.trusted
When Unicenter CA-XCOM for UNIX and Linux detects a trusted transfer, it searches for and reads the appropriate file into memory and constructs a simple search index. To improve the speed of this operation, the xcom.trusted file is broken into many files: one per remote system. The file in the example below is xcom.trusted.127.0.0.1; it will be used to authenticate trusted transfers from the system whose IP address is 127.0.0.1.
234
User Guide
xcom.trusted
The xcom.trusted file for each installation of Unicenter CA-XCOM for UNIX or Linux is in one of the following locations, depending on the conventions of the particular platform:
You can have just one trusted file if desired. For example, you can create a file in the new format called xcom.trusted.all. Then, for each remote partner, the following command creates a symbolic link to that file.
ln s xcom.trusted.all xcom.trusted.127.0.0.1 ln s xcom.trusted.all xcom.trusted.127.0.0.2 ln s xcom.trusted.all xcom.trusted.127.0.0.3 ln s xcom.trusted.all xcom.trusted.TSO36
This is particularly useful for testing and for small environments where the size of the trusted file does not impact performance. Use your preferred text editor to maintain the file. For UNIX or Linux initiated transfers you must specify the TRUSTED parameter to indicate to the receiving NT, UNIX, or Linux partner that the transfer is to be considered a trusted transfer. If XCOM_TRUSTED_OVR has been set to Y in the xcom.glb, the USERID parameter may also be specified to set the user ID that will be used by the receiving NT, UNIX, or Linux partner. The following versions of CA-XCOM Data Transport can send and receive trusted transfers to and from each other:
Advantage CA-XCOM Data Transport for Windows NT Server/Professional Version 3.1 Unicenter CA-XCOM Data Transport for Windows NT Server/Professional r11 Any Advantage CA-XCOM Data Transport for UNIX Version 3.1 platform Any Unicenter CA-XCOM Data Transport for UNIX and Linux r11 platform
Note: Versions 3.0 and 3.1 of Advantage CA-XCOM Data Transport for z/OS support only locally initiated trusted transfers to other trusted enabled platforms, including Advantage CA-XCOM Data Transport for UNIX Version 3.0.
Operating Environment
235
Sample File
# # # # # # xcom.trusted In order to improve the speed of this operation, the xcom.trusted file will be broken into many files: one per remote system. The file in the example below is xcom.trusted.127.0.0.1; it will be used to authenticate trusted transfers from the system whose IP address is 127.0.0.1.
# There will be other instances of the xcom.trusted file with different name # suffixes to allow trusted transfers to be initiated from many remote systems. # # The xcom.trusted file has one line per user. The first user id is the # one sent by the initiating system. The optional second user id is the # one that will be used by Unicenter CA-XCOM Data Transport when performing the transfer on the # responding system. If the second user id is not present, the first user id # will be used by the responding system instead. # Changes to the xcom.trusted file will take effect without having to recycle xcomd. # # For MVS remotely initiated transfers # The userid of the person submitting the JCL must match a userid in the list # of userids. # # Lines that begin with '#' are treated as comments. # A comment "#" must be followed by a space or a character. # # See the examples below for coding practices. # comment volke01 strmi03 dunla01 xcomuser rudto02 rudtr01 skoje02 xcomuser dexel01 payroll oakda01 payroll #
CODE=MACHINE is specified for FILETYPE=REPORT. The report is sent from a machine code type data set, such as FBM.
For each line that begins with a supported printer channel command code, Unicenter CA-XCOM Data Transport inserts the appropriate number of form feed and line feed characters. Unicenter CA-XCOM Data Transport supports the following machine code characters:
SKIP SKIP SKIP SKIP ONE LINE TWO LINES THREE LINES TO CHANNEL1-12
236
User Guide
NO SPACE ONE SPACE TWO SPACES THREE SPACES & SKIP TO CHANEL1-12
All channel commands (that is, Skip to Channel, Write and Skip to Channel) are translated to a form feed (0C) followed by n-1 line feeds (0A). The Skip to Channel or Write and Skip to Channel number is represented by n. Example Skip to Channel 1 is translated to a form feed (0C) followed by 0 line feeds. Skip to Channel 2 is translated to a form feed (0C) followed by 1 line feed (0A), and so on.
Operating Environment
237
Chapter
The Unicenter CA-XCOM Data Transport program defaults. Parameters defined in xcom.glb at the time the Unicenter CA-XCOM Data Transport daemon was started. Parameters defined in the specified .cnf file. If a copy of the configuration file is not found in the current directory, then the file /usr/spool/xcom/config/xcom.cnf is used. If a .cnf file is specified, the parameters are not picked up from the xcom.cnf. Parameters defined in the command line following the -f option.
31
Note: Use a text editor to modify the values in xcom.cnf. All modifications go into effect the next time a transfer is initiated. For a description of how parameter values take precedence, see Using Unicenter CA-XCOM Parameters in the chapter Operating Environment. For a complete list of Unicenter CA-XCOM Data Transport parameters see the appendix Parameters.
The file xcom.cnf is renamed to configfilename.cnf and resides in your local directory Note: The file name configfilename.cnf is used only as an example here. 2. 3. From your local directory, load configfilename.cnf into vi or another editor. The configfilename.cnf file is loaded in the editor. Modify the parameters in the new file to your specific needs. It is not necessary to list all available parameters in a configuration file, because any unspecified parameters will use the defaults that are set in xcom.glb or the Unicenter CA-XCOM Data Transport daemon. If you specify a configuration file, then xcom.cnf is not used. If you do not specify a configuration file, then Unicenter CA-XCOM Data Transport looks in xcom.cnf for parameter values. 4. Example 1 In the following example, Unicenter CA-XCOM Data Transport is invoked from the command line and a configuration file is specified.
xcom62 [ -cnumber] [ -f [configfilename] [PARAMETER_NAME=value ...] ]
Replace number, configfilename and PARAMETER_NAME=value with the desired transfer value, configuration file name and/or parameter name and values. For the complete syntax and options for using xcom62 or xcomtcp, see Transferring Files in this chapter.
32
User Guide
Transferring Files
Example 2 In the following example, a regional office transfers its accounting records daily to the mainframe headquarters. For this transfer, create a configuration file named account.cnf that contains the following parameter values:
FILEOPTION=REPLACE LOCAL_FILE=/usr/bills/july REMOTE_FILE=BILLS.JULY
Then specify this configuration file to use for the transfer as follows:
xcom62 -c1 -f account.cnf
Transferring Files
This section contains information about performing file transfers from the command line using xcom62 or xcomtcp. It describes the syntax and options for these commands, and also contains information about multiple transfers, using semicolons, and wildcard characters.
Use xcom62 or xcomtcp to initiate file transfers from the command line. Use xcom62 for transfers that use SNA/APPC protocols. Use xcomtcp for transfers that use TCP/IP protocols.
Specifying Protocols
When using the xcom62 or xcomtcp commands, the choice of protocol to use is indicated by the PROTOCOL parameter. This can be specified at the command line, in a configuration file, or in the xcom.glb file, depending upon your installations needs. If the protocol is not specified at the command line, the defaults specified in the configuration file or in xcom.glb are used.
Queuing Transfers
Transfers may be queued or not queued. When queued, failed transfers are retried automatically, depending on the parameters set in the xcom.glb. Multiple transfers may be sent to a partner simultaneously using SNA or TCP/IP. When not queued, transfers execute immediately, single-threaded and are not retried if they fail.
33
Transferring Files
Using xcom62 For performing transfers using SNA/APPC protocols, xcom62 allows you to initiate the transfer of a file, a job or a report from the command line, and to specify the parameters to be used for that transfer. Using xcomtcp For performing transfers using TCP/IP, xcomtcp allows you to initiate the transfer of a file, a job or a report from the command prompt, and to specify the parameters to be used for that transfer.
Multiple Transfers
You may initiate multiple transfers in two ways. You can use the NEWXFER option of the CONTROL parameter or you can use separate commands from the command line by placing a semicolon in between each transfer request. For information on the CONTROL parameter, see the appendix Parameters.
Using Semicolons
You can do several transfers from the command line by using the semicolon (;), the general shell command separator. Example In the following example, two files are sent to the remote system, using semicolons to separate the transfers. The file test1 is sent into file testA and file test2 is sent into file testB.
xcom62 -c1 -f LOCAL_FILE=test1 REMOTE_FILE=testA; xcom62 -c1 -f LOCAL_FILE=test2 REMOTE_FILE=testB
Wildcard Characters
Unicenter CA-XCOM Data Transport for UNIX and Linux supports the use of wildcards for local files and remote files.
Syntax
The syntax for using xcom62 and xcomtcp is identical, except for the choice of command. The syntax for each is shown below.
34
User Guide
Transferring Files
Options
The following table explains the options available for xcom62 and xcomtcp: Note: When the shell encounters an option that performs an action and exits xcom62 or xcomtcp, it will perform the command and exit xcom62 or xcomtcp without reading the rest of the command line. Option
-cnumber
Explanation The type of transfer to be attempted. Valid values for number are: Value 1 2 3 4 Description Send file to remote system (default). Send report to be printed on remote system. Send job to be executed on remote system. Receive file from remote system.
-h
Unicenter CA-XCOM Data Transport displays help. The usage message is displayed and exits xcom62 or xcomtcp. Note: All other options are ignored.
-r
Unicenter CA-XCOM Data Transport displays the release level. The release level of the software is displayed and exits xcom62 or xcomtcp. Unicenter CA-XCOM Data Transport queues the transfer. This option works like the QUEUE=YES parameter in xcom.cnf.
-q
35
Transferring Files
Option
-s
Explanation Unicenter CA-XCOM Data Transport sets silent mode, which turns off all output to stderr. Unicenter CA-XCOM Data Transport sends trace output to stderr. Unicenter CA-XCOM Data Transport ignores configuration errors. Unicenter CA-XCOM Data Transport reads configfilename to set the parameters necessary for the transfer. The syntax for setting parameters within the configuration file is as follows: PARAMETER1=value PARAMETER2=value Note: While you can have Unicenter CA-XCOM Data Transport read parameters from a file as well as from the command line, the parameters on the command line take precedence and must come after the file name. If you specify -f, you must specify configfilename or PARAMETERNAME=value, or you can specify both.
-t
-i
-f configfilename
PARAMETERNAME= value...
Instead of setting parameters in a file, you can set them on the command line. The syntax is as follows: PARAMETER1=value PARAMETER2=value The value of the parameters must be in uppercase where appropriate, but the parameter names themselves, with an underscore character where indicated, are not required to be in uppercase. Note: Parameters entered on the command line take precedence over those in the parameter file.
no options
If you invoke Unicenter CA-XCOM Data Transport without options, the defaults that are in xcom.cnf are used for the transfer. Sets the transfer version type. Valid values are 1 or 2. Sets the trace level. Valid values are 0 to 10.
-v -x
36
User Guide
37
Example 2 In the following example, the xcom62 command is used to send a file directly, without sending it to the queue, using SNA/APPC protocols. The configuration file is myconfig.cnf, the local file is named testa.aaa, and the remote file is named testb.bbb. The remote system is indicated by the value XCOMDEVT2 in the REMOTE_SYSTEM parameter. QUEUE is set to NO, so the transfer starts immediately after you press Enter. The choice of protocols is indicated by the value SNA in the PROTOCOL parameter. If the default value in the configuration file or the xcom.glb file is SNA, you do not need to specify this value here.
xcom62 -c1 -f myconfig.cnf LOCAL_FILE=testa.aaa REMOTE_FILE=testb.bbb REMOTE_SYSTEM=XCOMDEVT2 QUEUE=NO PROTOCOL=SNA
38
User Guide
The formats of the IP address, host name, and domain name are described in the following table: Value IP address Description A unique number for a particular computer, used to identify the computer on the TCP/IP network. IP addresses are in the dotted decimal notation format. Example: 123.123.78.91 Host Name The host name of a particular computer. Example: goodsys Domain Name The Domain Name Service (DNS) name. Identifies the computers group in the DNS hierarchy. The host name and the domain name make up the fully qualified domain name of the computer. Example: goodsys.goodsite.com goodsys is the name of the computer, and it is in the goodsite.com domain.
By IP address:
REMOTE_SYSTEM=123.123.78.91
Using the IP address is the most efficient method to use when specifying a remote system location.
39
Note: The examples above use the REMOTE_SYSTEM parameter, but the usage applies to REMOTE_SYSTEM_RF, REMOTE_SYSTEM_SJ, and REMOTE_SYSTEM_SR also.
310
User Guide
Example 1 In the following example, the xcomtcp command is used to queue a file for a send file transfer, using TCP/IP. The configuration file is myconfig.cnf, the local file is named testa.aaa, and the remote file is named testb.bbb. The remote system is indicated by the host name goodsys in the REMOTE_SYSTEM parameter. QUEUE is set to YES, so the transfer is queued. TCP/IP is indicated by the valueTCPIP in the PROTOCOL parameter. The port is determined by the value of the PORT parameter in the xcom.glb file.
xcomtcp -c1 -f myconfig.cnf LOCAL_FILE=testa.aaa REMOTE_FILE=testb.bbb REMOTE_SYSTEM=goodsys QUEUE=YES PROTOCOL=TCPIP
Example 2 In the following example, the xcomtcp command is used to submit a transfer directly, without sending it to the queue, using TCP/IP. The configuration file is myconfig.cnf, the local file is named testa.aaa, and the remote file is named testb.bbb. The remote system is indicated by the fully qualified domain name goodsys.goodsite.com in the REMOTE_SYSTEM parameter. QUEUE is set to NO, so the transfer starts immediately after you press Enter. TCP/IP is indicated by the value TCPIP in the PROTOCOL parameter. (If the default value in the configuration file or the xcom.glb file is TCPIP, you do not need to specify this value here.) The port is indicated by the value 8044 in the PORT parameter. Note: The default value of PORT should be valid for most hosts, and you should only specify a value for this parameter when needed.
xcomtcp -c1 -f myconfig.cnf LOCAL_FILE=testa.aaa REMOTE_FILE=testb.bbb REMOTE_SYSTEM=goodsys.goodsite.com QUEUE=NO PROTOCOL=TCPIP PORT=8044
PROTOCOL
The types of communication protocols to use are described following. Range: The range of values is listed in the following table: Value SNA TCPIP Default: SNA Description For transfers using SNA/APPC communication protocols For transfers using TCP/IP communication protocols
311
List of Parameters
The communications and data transfer configuration parameters are shown below. CODETABL Specifies the prefix to the file names, atoe.tab and etoa.tab, that contain the external ASCII-to-EBCDIC and EBCDIC-to-ASCII custom character conversion tables. These custom character conversion tables determine which external translation tables will be used by the transfer. Note: This parameter is valid only if INTERNAL_CONVERSION_TABLES=NO. Range: 0 to 12 characters Default: None
312
User Guide
COMPRESS Indicates the compression type. When communicating with an IBM mainframe, if the data file contains any empty lines, COMPRESS can only be set to YES, LZSMALL, LZMEDIUM, or LZLARGE. Note: All compression types are not supported on all platforms. See the partner platform documentation for supported compression types. Range: The range of values is listed in the following table: Note: The LZ values enable LZ (Lempel-Ziv) compression to replace sequences of data bytes that occur more than once in a data stream with a code value. Value COMPACT LCOMPACT LZLARGE LZMEDIUM LZRW3 LZSMALL NO RLE YES ZLIBn Description RJE compaction algorithm optimized for uppercase English text. RJE compaction algorithm optimized for lowercase English text. Activates LZ compression to search back 32K in the datastream for a matching string. Activates LZ compression to search back 16K in the datastream for a matching string. General-purpose algorithm that runs fast and gives reasonable compression. Activates LZ compression to search back 4K in the datastream for a matching string. Indicates no compression. Run length encoding. Indicates run length encoding of binary zeros and blanks only. Greater compression than LZRW3 but less than LZSMALL, LZMEDIUM, and LZLARGE. The n value can be 1 through 9.
Default: YES
313
DESTINATION_TYPE The type of target system. Range: HOST, MIDRANGE, or OTHER Default: OTHER DOMAIN The Windows domain name for use in authenticating the user ID and password when accessing a Windows based machine that has sharable disks and drives that belong to that domain. This allows users to access these sharable drives without having to have a local user ID or password defined to the machine. Range: 1 to 15 characters. Default: None MAXRECLEN For Windows NT, UNIX, and Linux systems, the locally initiating Unicenter CA-XCOM Data Transport system determines the values for MAXRECLEN, TRUNCATION, and LRECL, for send and receive operations. When the local Unicenter CA-XCOM Data Transport system initiates a transfer of a text file, this parameter designates the length, in bytes, of the largest record that can be transferred. If a record length is longer than this value, Unicenter CA-XCOM Data Transport uses the value in the TRUNCATION parameter on the initiating side to determine whether to terminate the transfer or to truncate the record and continue the transfer. When Unicenter CA-XCOM Data Transport transfers binary files, this value indicates the length of the records that are transferred. On a receive operation, MAXRECLEN is set to whatever the LRECL value is on the initiating side. Range: 1 to 32767 Default: 1024
314
User Guide
MAX_REMOTE_TCP The maximum number of remote TCP/IP transfers accepted by Unicenter CA-XCOM Data Transport. Transfers received after this limit has been reached are rejected. Note: Setting this parameter to 0 prohibits any remote transfers from taking place. Range: 0 to 999
Default: 32
REMOTE_SYSTEM The name of the remote system that receives a file, job, or report. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None REMOTE_SYSTEM_RF The name of the remote system that sends a file on a receive file operation. If no value is specified here, the value in REMOTE_SYSTEM is used. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None
315
REMOTE_SYSTEM_SJ The name of the remote system to which a job is sent. If no value is specified here, the value in REMOTE_SYSTEM is used. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None REMOTE_SYSTEM_SR The name of the remote system to which a report is sent. If no value is specified here, the value in REMOTE_SYSTEM is used. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None TEMPDIR Indicates the directory in which temporary files for jobs and reports can be created. Range: 1 to 256 characters Default: /tmp
316
User Guide
TRUNCATION Indicates whether Unicenter CA-XCOM Data Transport truncates excess characters in the source file if the record exceeds the maximum record length as indicated by the MAXRECLEN parameter. If NO is selected, and the maximum record length is exceeded, Unicenter CA-XCOM Data Transport aborts the transfer. This parameter is ignored if CARRIAGE_FLAG=NO. Note: Truncation is not valid for BINARY data or for non-text data received on the UNIX or Linux platform. Range: YES or NO Default: NO VERSION Indicates the version of the Unicenter CA-XCOM Data Transport protocol to be used for this transfer. For TCP/IP, only a value of 2 is valid. Range: 1 or 2 Default: 2 Note: This is a Version 2 parameter. XLUNAME Indicates the name of the local LU. This name must match the remote LU name on the remote system. Range: 1 to 17 characters Default: None Note: Not used in Unicenter CA-XCOM Data Transport for RS/6000 SNA Services or RS/6000 SNA Server. XMODE Indicates the mode name associated with the SNA/APPC configuration for the XLUNAME-Remote LU name pair. This name must match the mode name defined on the remote system. Range: 1 to 8 characters Default: XCOMMODE
317
XNODESPEC Required for Brixton and SunLink APPCs. Indicates the name of the node that specifies the gateway to use for the transfer. Does not apply to other APPCs. Range: 1 to 64 characters Default: None
Example 2 In the following example, the xcomtcp command is used. The configuration file is /myconfig.cnf, the local file is named /testa.aaa, the remote file is named /testb.bbb, and the transferred file replaces a file on the remote system that already exists. The PROTOCOL parameter specifies the protocol as TCP/IP.
xcomtcp -c1 -f /myconfig.cnf LOCAL_FILE=/testa.aaa REMOTE_FILE=/testb.bbb FILE_OPTION=REPLACE PROTOCOL=TCPIP
318
User Guide
Parameters
The Send File parameters are shown below. CREATE_DIR Indicates whether to create the specified directory if it does not exist. Value YES NO Default: YES FILE_OPTION Indicates how the transferred data is to be processed by the receiving system. For file transfers only. Range: The range of values is listed in the following table: Value CREATE APPEND REPLACE Description Create a new file on the receiving system. Append the transferred data to an existing file on the receiving system. Replace an existing file on the receiving system. Description Create the directory if it does not exist. Do not create the directory if it does not exist.
For wildcard transfers: Value CREATE APPEND REPLACE Description Create the PDS/Directory and add the transferred members. If the PDS/Directory already exists, the transfer fails with an error. Add transferred members/files. If the PDS/Directory does not exist or the member/file already exists, the transfer fails with an error. Add or replace transferred members/files. If the PDS/Directory does not exist, the transfer fails with error XCOMN0403E Cannot open output file-No such file or directory.
319
Note: When creating a file on an IBM mainframe system, some additional information may be necessary. Fore more information, see the explanations for RECORD_FORMAT, BLKSIZE, VOLUME, and UNIT parameters. Default: CREATE LOCAL_FILE The name of the file on the local system that is being transferred. At the command prompt or in a script, if this variable is null or unset, standard input is read. In this manner, Unicenter CA-XCOM Data Transport commands can be used in a pipeline or with redirection. All UNIX or Linux file naming conventions apply. For wildcard transfers, use an asterisk (*) as a file name to indicate that all files within the specified directory are to be transferred. For example, the statement LOCAL_FILE=/NAMES/* indicates that all files under the NAMES directory are to be transferred. When a prefix is followed by an asterisk, all members beginning with a specific prefix are to be transferred. For example, LOCAL_FILE=/NAMES/AL* requests that files AL, ALEX, and ALICE are all to be transferred. The same rules apply if an asterisk is followed by a suffix. The actual file name range (not including its path) for wildcard transfers can be between 0 and 71 characters. This also includes the file extension where applicable. File names over 71 characters are truncated. However, when sending files to a mainframe PDS, any file name over 8 characters in length is truncated. These systems do not recognize file extensions. For example, a file called longfilename.txt will be truncated to longfile and a file called file.txt will be truncated to file. Note: If QUEUE=YES, the full path name must be specified. Range: 0 to 256 characters Default: None REMOTE_FILE Indicates the file on the remote computer to which the transferred data is being written. If you are creating the file (FILE_OPTION=CREATE), the file name must be consistent with the file naming conventions of the remote system. The local Unicenter CA-XCOM Data Transport system does not validate this name. The remote I/O system determines whether the file name is valid.
320
User Guide
For wildcard transfers, use an asterisk (*) as a file name to indicate and to inform the receiving partner that multiple files will be sent. For example, REMOTE_FILE=/PAYROLL/*. If multiple files are sent and the user specifies a file name, all files received by the partner are written to that specified file as one single file. An asterisk used to send files to an IBM mainframe system shows that all files are to be transferred to a partitioned data set (PDS). For platforms that support it, you can specify a common file extension to append to each file name. For example, REMOTE_FILE=/PAYROLL/*.TXT. Note: For send file transfers only. Range: 1 to 256 characters Default: None
Example 2 In the following example, the xcomtcp command is used. The remote file customer is retrieved into the local file /accounts. All other necessary parameters are read from the default configuration file, xcom.cnf.
xcomtcp -c4 -f REMOTE_FILE_RF=customer LOCAL_FILE_RF=/accounts
321
Parameters
The Retrieve File parameters are shown below. FILE_OPTION_RF Indicates how the transferred data is to be processed by the receiving system (that is, the local system). Used when the transfer type is Retrieve File. If a value is not specified, then the value of FILE_OPTION is used. If no default is specified in FILE_OPTION or FILE_OPTION_RF, then the value defaults to CREATE. Range: The range of values is listed in the following table: Value CREATE APPEND REPLACE Description Create a new file on the receiving system. Append the transferred data to an existing file on the receiving system. Replace an existing file on the receiving system.
For wildcard transfers: Value CREATE APPEND REPLACE Description Create the PDS/Directory and add the transferred members. If the PDS/Directory already exists, the transfer fails with an error. Add transferred members/files. If the PDS/Directory does not exist or the member/file already exists, the transfer fails with an error. Add or replace transferred members/files. If the PDS/Directory does not exist, The transfer fails with error XCOMN0403E Cannot open output file-No such file or directory.
Default: CREATE LOCAL_FILE_RF The file name that is created, appended, or replaced on the local system when it receives a file. At the command prompt or in a script, if this value is null or unset, then Unicenter CA-XCOM Data Transport writes to the stdout. All UNIX or Linux file naming conventions apply. For wildcard transfers, use an asterisk (*) as a file name to indicate that multiple files will be received. For example, LOCAL_FILE_RF=/PAYROLL/*.
322
User Guide
If multiple files are received and the user specifies a file name, all files received by the partner are written to that specified file as one single file. For platforms that support it, you can specify a common file extension to be appended to each file name. For example, LOCAL_FILE_RF=/PAYROLL/*.TXT. Note: If QUEUE=YES, the full path name must be specified. Range: 0 to 256 characters Default: None REMOTE_FILE_RF Indicates the name of the file to be retrieved from the remote system. For wildcard transfers, use an asterisk (*) as a file name to indicate that all files within the specified PDS/Directory should be transferred. For example, the statement REMOTE_FILE_RF=/NAMES/* indicates that all files under the NAMES directory should be transferred. When a prefix is followed by an asterisk, all members beginning with a specific prefix are transferred. For example, REMOTE_FILE_RF=/NAMES/AL* requests that files AL, ALEX, and ALICE should be transferred. The same rules apply if an asterisk is followed by a suffix. The actual file name range (not including its path) for wildcard transfers can be between 0 - 71 characters. This also includes the file extension where applicable. File names over 71 characters are truncated. Note: For retrieve file transfers only. Range: 1 to 256 characters Default: None
323
REMOTE_SYSTEM_RF The name of the remote system that sends a file on a receive file operation. If no value is specified here, the value in REMOTE_SYSTEM is used. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None UNIT_RF Specifies the unit from which a data set is to be retrieved from an IBM mainframe. Range: 0 to 6 characters Default: None VOLUME_RF Specifies the volume from which a data set is to be retrieved from an IBM mainframe. Range: 0 to 6 characters Default: None
324
User Guide
Parameters
The following parameters are used when FILE_OPTION=CREATE when creating a file on an IBM mainframe from a local system. ALLOCATION_TYPE Indicates the unit of storage allocation for a data set created on an IBM mainframe. Range: The range of values is listed in the following table: Value CYL TRK BLK Default: CYL Note: This is a Version 2 parameter. Description Cylinders Tracks Blocks
325
BLKSIZE Specifies the block size of a data set created on an IBM mainframe. Note: Used when FILE_OPTION=CREATE Range: 0 to 32767 If the format is Fixed or fixed block record Variable record Undefined record Default: 800 DATACLAS Specifies the name of the data class to use when allocating a new SMS-managed data set. Note: This parameter applies only to mainframe SMS data sets. Range: 1 to 8 characters Default: None DSNTYPE Specifies the data set definition. Note: This parameter applies only to mainframe SMS data sets. Value LIBRARY PDS Description Defines a PDSE Defines a partitioned data set Then the block size must be A multiple of the record length 4 bytes larger than the record length Larger than the largest record length
Note: These values are IBM standards for SMS processing. Range: 1 to 8 characters Default: None
326
User Guide
LRECL Specifies the actual or maximum length, in bytes, of a logical record. Corresponds to the JCL LRECL subparameter. Range: 0 to 32767 If the format is Variable blocked record Fixed or fixed block record Default: 160 MGMTCLAS Specifies the name of the management class to use when allocating a new SMSmanaged data set. Note: This parameter applies only to mainframe SMS data sets. Range: 1 to 8 characters Default: None NUM_OF_DIR_BLOCKS Specifies the number of directory blocks to allocate for a data set created on an IBM mainframe. Range: 0 to 32767 Default: 0 Note: Version 2 parameter PRIMARY_ALLOC Identifies primary storage allocation for a data set created on an IBM mainframe. Range: 0 to 99999 Default: 1 Note: Version 2 parameter Then the maximum length of a logical record must be equal to the Maximum record length plus 4 Constant record length
327
RECORD_FORMAT Specifies the record format of a data set created on an IBM mainframe. This corresponds to the JCL RECFM subparameter. Range: The range of values is listed in the following table: Value F FA Description Fixed unblocked Fixed unblocked ANSI Fixed blocked Record Length The same length as the data set The same length as the Contains data set ISO/ANSI/FIPS control characters Fixed Fixed record length with multiple records per block Multiple records per block where these records contain ISO/ANSI/FIPS control characters Multiple records per block written as standard blocks Comment
FB
FBA
Fixed
FBS
Fixed
FM FS
The same length as the Contains machine code data set control characters The same length as the Written as standard data set blocks where these records do not contain any truncated blocks or unfilled tracks Undefined Variable Variable Contains ISO/ANSI/FIPS control characters Multiple records per block
U V VA
VB
Variable
328
User Guide
Value VBA
Comment Multiple records per block where these records contain ISO/ANSI/FIPS control characters Multiple records per block where these records contain machine code control characters May have multiple records per block where these records can span more than one block Contains machine code control characters A record can span more than one block
VBM
Variable
VBS
Variable
VM
Variable
VS
Variable
Default: VB SECONDARY_ALLOC Identifies secondary storage allocation for a data set created on an IBM mainframe. Range: 0 to 99999 Default: 0 Note: This is a Version 2 parameter.
329
SECURE_SOCKET Specifies whether to use an OpenSSL socket or Non OpenSSL socket for transfers. Value YES Description Performs secure transfer. The transfer uses an OpenSSL socket and must to connect to a SSL listener on the remote partner. NO Performs non secure transfer. The transfer uses a Non Open SSL socket. Default: NO STORCLAS Specifies the name of the storage class for a new SMS-managed data set. Note: This parameter applies only to mainframe SMS data sets. Range: 1 to 8 characters Default: None UNIT Specifies the unit on which a data set is to be created on an IBM mainframe. Note: Used when FILE_OPTION=CREATE. Range: 0 to 6 characters Default: None VOLUME Specifies the volume on which a data set is to be created on an IBM mainframe. Range: 0 to 6 characters Default: None
330
User Guide
XCOM_CONFIG_SSL Specifies the configssl.cnf file path and file name. Range: 1 to 256 characters Default: /usr/locl/ssl/configssl.cnf XCOM_SHOW_CIPHER Specifies whether to display encryption algorithms in the Unicenter CA-XCOM Data Transport queue detailed information, which is used for transfers. Value NO YES Default: NO Description Do not display encryption algorithms in the queue detail information. Display encryption algorithms in the queue detail information.
331
EXPDT Specifies an expiration date for the tape data set in terms of a two-digit designation for the year and a three-digit designation for the day of the year. For example, in the expiration date 02021, 02 is the year (namely, 2002) and 021 is the 21st day of that year when the tape data set expires. For example, if 02021 is an expiration date, 2002 is the year and 021 is the 21st day of the year. Format: yyddd Default: None Note: EXPDT and RETPD are mutually exclusive; specify one or the other. LABEL Indicates the type of label associated with a tape data set. The following table lists the valid values for this parameter. Value Processing type: AL, AUL, BLP, LTM, NL, NSL, SL, SUL Description Represent the types of processing to be applied to data sets on tape.
Note: Unicenter CA-XCOM Data Transport for z/OS supports only standard label tapes. Example: LABEL=BLP The type of processing to be applied to this data set is BLP. Default: AL
332
User Guide
LABELNUM Indicates the sequence number of the data set on the tape. The following table lists the valid values for this parameter. Value Sequence number (0001-9999) Description This value identifies the sequence number of a data set on tape.
Example: LABELNUM=2 This specification refers to the second data set on the tape. Default: 0001 RETPD Specifies the number of days (1 to 9999) that the tape data set being created is to be retained. Range: 1 to 9999 Default: None Note: RETPD and EXPDT are mutually exclusive; specify one or the other. TAPE Indicates to the remote system whether the volume is a tape volume or a disk file. Yes indicates a tape volume and that mounts are allowed when performing dynamic allocation. No indicates that the transfer is to a disk file. Range: YES or NO Default: NO
333
TAPEDISP Specifies the disposition value for MVS tape data sets. Range: The range of values is listed in the following table: Value 1 2 3 Default: 1 UNITCT Specifies the number of units to be allocated on the remote system. Range: 1 to 20 Default: None VOLCT Specifies the maximum number of volumes to be used in processing a multivolume output tape data set on the remote system. Range: 1 to 255 Default: None VOLSQ Specifies the sequence number of the first volume of a multi-volume remote data set to be used. Range: 1 to 255 Default: None Description New Old Mod
334
User Guide
Example 2 In the following example, the xcomtcp command is used. The configuration file is /myconfig.cnf, the local report file sent is named/tmp/myfile.rpt, and it is placed on HOLD status on the remote system until released by the remote system.
xcomtcp -c2 -f /myconfig.cnf LOCAL_FILE_SR=/tmp/myfile.rpt HOLDFLAG=YES
Parameters
The Send Report parameters are shown below. CARRIAGE_CONTROL_CHARACTERS Indicates the type of printer carriage-control codes, if any, that are included in the report file. Note: For report transfers only. Range: The range of values is listed in the following table: Value ASA IBM Description ASA control codes in column 1. IBM Machine Characters (valid only for IBM mainframes).
335
Description If data is already in ASA format, bypass conversion. No carriage-control codes are used.
The print class assigned to a report transferred to a remote system. If the remote system is an IBM mainframe, this field designates the JES SYSOUT class. Note: For report transfers only. Example: Enter B to print the report through SYSOUT=B. Range: 1 character Default: None COPIES The number of copies that are to be sent. If this parameter is not specified, the remote system queues one copy of the report to the systems default printer. For report transfers only. Range: 1 to 999 Default: 1 DESTINATION Identifies the printer or other device on the remote system where the report is to be sent. If this parameter is not specified, the remote system sends the report to the system's default printer. For report transfers only. Range: The range of values is listed in the following table: Value 0 to 16 characters 0 to 21 characters Default: None Description For indirect transfers and for Version 1. For transfers that are not indirect and for Version 2.
336
User Guide
DISPOSITION Indicates what the remote system does with the report file after the report has been printed. For report transfers only. Note: This field is not used when the remote system is an IBM mainframe. Range: The range of values is listed in the following table: If the value Is DELETE KEEP HOLD Default: DELETE FCB Identifies the FCB JCL parameter when sending the report file to an IBM mainframe, defining print density, lines per page, and so on. For report transfers only. Range: 0 to 4 characters Default: None FORM The type of form that should be used to print the report. Since Unicenter CA-XCOM Data Transport places the print job in the remote system's print queue, the print control functions depend on the remote system. The user must verify beforehand that the requested form is available at the remote site. For report transfers only. Range: 0 to 10 characters Default: None HOLDFLAG Indicates whether a transferred report file is to be placed on HOLD on the remote system or is to be printed immediately. For report transfers only. Range: YES or NO Default: NO Then after printing the report is Deleted Kept Held
337
LOCAL_FILE_SR Local file name to be sent as a report to the remote system. If this value is null or unset, then Unicenter CA-XCOM Data Transport reads the standard input file. For report transfers only. Note: If QUEUE=YES, user must specify full path name. Range: 0 to 256 characters Default: None REMOTE_SYSTEM_SR The name of the remote system to which a report is sent. If no value is specified here, the value in REMOTE_SYSTEM is used. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None REPORT_TITLE This field contains the report title and job number that will be printed on the report. The field has the following format: 8 characters Job Name 2 characters Blanks 8 characters Job Number
The Job ID is optional and can be skipped. The Job Name can also be skipped, but if you skip the Job name and want to use the job number, you must pad the number with 10 blanks. Note: For report transfers only.
Examples
REPORT_TITLE=Salary94 REPORT_TITLE= Job12345 Job23456
Non-example
REPORT_TITLE=
Job34567
338
User Guide
This is not a valid REPORT_TITLE because the Job Number spans both subfields. This parameter is used by Unicenter CA-XCOM Data Transport on remote systems in the following ways: System z/OS Uses the REPORT_TITLE To interpret a non-blank value in this field as specifying the generation of a separator (banner) page for this value. To print with the report. To allow Unicenter CA-XCOM Data Transport to pass this field to the LP spooler as a title field. As a descriptive comment only and does not print it as part of the report.
Range: 0 to 21 alphanumeric or blank characters Default: None SPOOL_FLAG Indicates whether the report is to spooled to disk or printed immediately. For report transfers only. Note: If the remote system is an IBM mainframe, this parameter has no effect on the transfer. Range: YES or NO Default: Yes
339
All other necessary parameters are read from the default configuration file xcom.cnf. Example 2 In the following example, the xcomtcp command is used. The job sent for execution on the remote system is in the file /tmp/myfile.
xcomtcp -c3 -f LOCAL_FILE_SJ=/tmp/myfile
All other necessary parameters are read from the default configuration file xcom.cnf.
340
User Guide
Tracing Problems
Parameters
The Send Job parameters are shown below. LOCAL_FILE_SJ Indicates the name of the file on the local system to be sent as a job. All the UNIX or Linux file naming conventions apply. If this value is null or unset, then Unicenter CA-XCOM Data Transport reads the standard input file. Note: If QUEUE=YES, user must specify full path name. Range: 0 to 256 characters Default: None REMOTE_SYSTEM_SJ The name of the remote system to which a job is sent. If no value is specified here, the value in REMOTE_SYSTEM is used. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None
Tracing Problems
The tracing parameters are used to collect information at the request of Unicenter CA-XCOM Data Transport Customer Support in order to diagnose a problem. The trace output is primarily intended to provide information to Customer Support, and they usually request a level of tracing for you to use. The -t option of the xcom62 or xcomtcp command will direct trace output to stderr, the standard error output. This trace facility collects information about a transfer from the point where a transfer is queued or submitted and a connection is established. The resulting trace data is stored in a file named tidnumber.tra, where tidnumber = the transfer ID.
341
Tracing Problems
Example 1 In the following example, the xcom62 command is used. The configuration file is /myconfig, the XTRACE parameter is used to set the trace level to 10 to provide full tracing information and the trace information is written to a trace file.
xcom62 -f /myconfig XTRACE=10
This section contains information about collecting information to diagnose problems when requested by Unicenter CA-XCOM Data Transport Customer Support. Example 2 In the following example, the xcomtcp command is used. The configuration file is /myconfig, the XTRACE parameter is used to set the trace level to 10 to provide full tracing information and the trace information is written to a trace file. The protocol is specified by the PROTOCOL parameter.
xcomtcp -f /myconfig XTRACE=10 PROTOCOL=TCPIP
Return Codes
For queued transfers, the return code indicates success or failure in queuing the transfer. For non-queued transfers the return codes from XCOMTCP and XCOM62 are as follows:
The XCOM return code is the same as the error message number, which is usually a three-digit number. In order to pass back the error message number, XCOM must make sure the error code is 256 or less, because of system restrictions. To do this, XCOM subtracts 256 from the error message number if it is greater than 256. In other words, the return code is modulo 256. Example Message XCOMU0298E would give 42 as the return code (298-256= 42). Refer to /usr/include/xcom/xcomerr.h. These return codes are not modulo 256.
342
User Guide
Parameters
The tracing parameter is shown below. XTRACE Indicates the level of desired execution tracing. Range: The range of values is listed in the following table: Value 0 1 to 8 9 10 Default: 0 Note: Turning on the trace can seriously degrade performance. Description No tracing. Levels of tracing from 1 (lowest) to 8 (highest). Show the contents of the data buffers. Includes levels 1 to 9 plus some additional detailed technical information.
343
Example 2 In the following example, the xcomtcp command is used. The configuration file is /tmp/myconfig and the log file is /home/phil/xcom/mylog.
xcomtcp -f /tmp/myconfig XLOGFILE=/home/phil/xcom/mylog
Parameters
The logging parameter is shown below. XLOGFILE The name of the file where Unicenter CA-XCOM Data Transport logs activity. If you do not specify this parameter, the systemwide log file/usr/spool/xcom/xcom.log is used. If you specify this parameter with a different file name, the logging information is only sent to the specified file. Note: Specify the full pathname if QUEUE=YES. Range: 0 to 256 characters Default: /usr/spool/xcom/xcom.log, except for the following:
344
User Guide
Note: For HP-UX systems these files are in the directory /var/spool/xcom. For conversions, when transferring text files for transfers initiated on a UNIX or Linux system, CARRIAGE_FLAG must be set to YES and CODE_FLAG must be set to EBCDIC. Example 1 In the following example, the xcom62 command is used. An EBCDIC text file is being transferred:
xcom62 -f CARRIAGE_FLAG=YES CODE_FLAG=EBCDIC
All other necessary parameters are read from the default configuration file, xcom.cnf. Example 2 In the following example, the xcomtcp command is used. An EBCDIC text file is being transferred:
xcomtcp -f CARRIAGE_FLAG=YES CODE_FLAG=EBCDIC
All other necessary parameters are read from the default configuration file, xcom.cnf.
Parameters
Use the parameters shown below to specify the characteristics of the file and the data involved in the transfer. For information on using custom character conversion sets rather than the Unicenter CA-XCOM Data Transport defaults, see the topic, Creating Custom Character Sets for File Conversion, later in this chapter. The file type parameters are listed next.
345
CARRIAGE_FLAG Specifies the type of file being transferred and some special characteristics of the conversion done during the transfer. Range: The range of values is listed in the following table: Value YES Description Indicates that the transferred file is a text file and a newline character should be added to the end of incoming records. Also, newline characters are removed from the ends of lines before an outgoing record is sent. Indicates no special processing. Indicates a text file with record packing. Uses 2K pack buffer. Indicates a binary file of variable-length records with a field of 4 bytes preceding each record. Applies to local initiated transfers only. Indicates a binary file of variable-length records with a field of 8 bytes preceding each record. Applies to local initiated transfers only. Used for certain applications that require a z/OS-style BDW and RDW preceding each record. Indicates a text file with record packing. Uses 31K pack buffer.
NO MPACK VLR
VLR2
XPACK
Note: MPACK does not support a MAXRECLEN (actual record length) over 2K. XPACK does not support a MAXRECLEN (actual record length) over 31K. Default: YES CODE_FLAG Used to identify the type of data being transferred. Range: The range of values is listed in the following table: Value ASCII Description An ASCII file is being transferred. This indicates that the incoming file is assumed to be ASCII format, and is not translated. Therefore the file on the remote system should be in ASCII format before it is transferred. A binary file, such as an executable file, is being transferred. This indicates to a remote system that it is not to translate the data it is exchanging with your system.
BINARY
346
User Guide
Value EBCDIC
Description An EBCDIC file is being transferred. The transferred data is translated from EBCDIC to ASCII format when the local system receives the data, and from ASCII to EBCDIC format when the local system sends the data.
Default: ASCII
When a non-USA character set is being used. When the transferred file is to be converted to all uppercase or lowercase characters. When Unicenter CA-XCOM Data Transports default character conversion sets would not be appropriate.
For information on using Unicenter CA-XCOM Data Transports default character conversion sets, see the topic, Setting File Type Conversion, earlier in this chapter. Procedure To create a custom character translation table, follow these steps: 1. 2. From the command line, use vi or another editor to create and open a file. Define each character on a separate line.
347
Unicenter CA-XCOM Data Transport for UNIX or Linux performs the EBCDIC to ASCII translation as follows:
When an EBCDIC code 0 is received, CA-XCOM substitutes the ASCII value from the first line (line 1) of the table. For EBCDIC code 1, CA-XCOM takes the value from the second line (line 2), and so on.
Because the first line is for code 0, it is necessary to add 1 to the line number when determining which line of the table to modify. Example 1 A question mark (?) must be sent to the mainframe in EBCDIC. Set up the translation table to translate it from ASCII to EBCDIC. The ASCII code for ? is 63 (decimal). The EBCDIC code for ? is 111 (decimal). Take the ASCII code and add 1. This is 64. Go to line 64 of the ATOE table and type the value 111. Example 2 An A is received from the mainframe in EBCDIC. Set up the translation table to translate it to ASCII. The EBCDIC code for A is 193 (decimal). The ASCII code for A is 65. Take the EBCDIC code for A and add 1. This is 194. Go to line 194 of the ETOA table and type the value 65.
348
User Guide
/usr/spool/xcom/convtab/atoe.tab /usr/spool/xcom/convtab/etoa.tab
For HP/UX systems, the following files are supplied on your distribution media and contain tables used to map ASCII-to-EBCDIC and EBCDIC-to-ASCII translations:
/var/spool/xcom/convtab/atoe.tab /var/spool/xcom/convtab/etoa.tab
For OSF Digital UNIX, the following files are supplied on your distribution media and contain tables used to map ASCII-to-EBCDIC and EBCDIC-to-ASCII translations:
/var/opt/xcom/convtab/atoe.tab /var/opt/xcom/convtab/etoa.tab
349
Procedure To translate all lower case ASCII characters to upper case EBCDIC characters, follow these steps: 1. From the command line, type
cp /usr/spool/xcom/convtab/atoe.tab conversionfilename
Note: conversionfilename can be any name you choose. /usr/spool/xcom/convtab/atoe.tab is copied to a new file and named conversionfilename. Note: For HP-UX systems the atoe.tab and etoa.tab files are in the directory /var/spool/xcom/convtab. 2. Use vi or another editor to open the file and copy the values from lines 66 to 91 to lines 98 to 123. Note: The decimal ASCII code for a is 98 and the decimal ASCII code for z is 123. The values in lines 98-123 are changed to represent uppercase EBCDIC characters. 3. Save the file and exit the editor.
The xcom.glb file is opened for editing. 2. 3. 4. Set INTERNAL_CONVERSION_TABLES= NO. Change the values for ETOA_FILENAME and ATOE_FILENAME to the file names containing the customized files you created. Save xcom.glb and exit the editor.
350
User Guide
There must be a destination member created and enabled for the remote system in the z/OS Dynamic Control Library in order for Unicenter CA-XCOM Data Transport to forward the transfer successfully. Example 2 In the following example, the xcomtcp command is used. The file mytest.tst is sent to the intermediate z/OS node XCOMMVS2, which forwards the transfer to the remote PC system endest and into the file named MYTEST.TST.
xcomtcp -c1 -f XIDEST=XCOMMVS2 REMOTE_SYSTEM=endest LOCAL_FILE=mytest.tst REMOTE_FILE=MYTEST.TST
There must be a destination member created and enabled for the remote system in the z/OS Dynamic Control Library in order for Unicenter CA-XCOM Data Transport to forward the transfer successfully.
When to Use
Use the parameter below with the REMOTE_SYSTEM parameter for store and forward transfers through an IBM mainframe system. Use store and forward to send an indirect transfer or to transfer files between two PU 2.0 devices.
351
Parameters
The store and forward parameter is shown below. XIDEST Specifies the name of the remote system on the intermediate destination that is designated for store and forward transfers. If this variable is null or unset, then a direct connection to a remote system is attempted. Note: For store and forward transfers only. Range: 0 to 14 characters Default: None
All other parameters are read from the default configuration file, xcom.cnf. Example 2 In the following example, the xcomtcp command is used. myname is the USERID and mypassword is the PASSWORD.
xcomtcp -f USERID=myname PASSWORD=mypassword
All other parameters are read from the default configuration file, xcom.cnf.
352
User Guide
Parameters
The security parameters are shown below. DOMAIN The Windows domain name for use in authenticating the user ID and password when accessing a Windows based machine that has sharable disks and drives that belong to that domain. This allows users to access these sharable drives without having to have a local user ID or password defined to the machine. Range: 1 to 15 characters. Default: None PASSWORD The password associated with the user ID on a remote system. Range: 0 to 31 characters Default: None TRUSTED Allows the user to request a trusted transfer and the partners Unicenter CA-XCOM Data Transport TRUSTED database to be searched to verify the users credentials. This eliminates the need for the user to specify a USERID and PASSWORD. If XCOM_TRUSTED_OVR is set to NO or no USERID is specified, the USERID of the process that initiated the transfer is used. Note: TRUSTED=YES cannot be specified with indirect transfers, because this is not supported. Range: YES, NO, Y, N Default: NO USERID The user ID which the security system on the remote system checks before granting access for the file transfer. Range: 0 to 12 characters Default: None
353
to
PARAMETER.ENCRYPTED=ENCRYPTEDVALUE
Example
Before encryption:
PASSWORD=ENIGMA
After encryption:
PASSWORD.ENCRYPTED=12 0F 36 79 65 AB D0 37 ...
Syntax
The syntax for using XCOMENCR is as follows:
xcomencr input_file output_file
Options
The following table explains the options for XCOMENCR: Option (minus sign) + (plus sign) no options Explanation Send output to stdout. Example: xcomencr input_file Replace input_file. Example: xcomencr input_file + Displays help text.
354
User Guide
Procedure
To encrypt a parameter value using XCOMENCR, follow these steps: 1. Using a text editor, open the configuration file you want to modify, go to the parameter you want to encrypt, create a blank line above it, and enter the following:
#!ENCRYPT
Repeat as necessary for each parameter you want to encrypt. Note: Because # denotes a comment line in the .cnf file, any line beginning with #!ENCRYPT is ignored by Unicenter CA-XCOM Data Transport and is used only by XCOMENCR. 2. 3. Save the configuration file as an ASCII text file. At the command prompt, enter the following:
xcomencr input_file output_file
where input_file is the name of the configuration file from Step 1. The parameter value in the first non-comment line after each occurrence of the #!ENCRYPT statement is changed to the encrypted parameter value format. Note: If you open an encrypted configuration file with a text editor, you would not be able to see the values of the encrypted parameters. In the GUI, when you open an encrypted configuration file, you can see the encrypted values, except for the user ID and password security parameters.
Then type in an equal sign and the new parameter value, (in an unencrypted form) replacing NEWVALUE with your desired value, as follows:
PASSWORD=NEWVALUE
Then save the file as ASCII text and encrypt it as in the encryption procedure above.
355
All other necessary parameters are read from the default configuration file, xcom.cnf. Example 2 In the following example, the xcomtcp command is used. The transfer request goes into the queue to execute on July 28, 1999 at one minute after noon.
xcomtcp -f QUEUE=YES START_DATE=07/28/99 START_TIME=12:01:00
All other necessary parameters are read from the default configuration file, xcom.cnf.
356
User Guide
Parameters
The queue management parameters are shown below. PRIORITY Indicates the priority that Unicenter CA-XCOM Data Transport uses for scheduling a transfer. If two transfers are scheduled for the same time, the one with the high priority is processed before one with a normal or low priority. Range: The range of values is listed in the following table: Value HIGH NORMAL LOW Description Set high priority. Set medium priority. Set low priority.
Default: NORMAL QUEUE Indicates whether to execute the transmission request immediately or to allow the request to be queued. If the user does not specify a .cnf file, and has not changed a .cnf file, the default value is YES. Note: If NO is specified and the remote system is unavailable, the request aborts. If YES is specified, START_TIME and START_DATE are read. Range: The range of values is listed in the following table: Value YES Description The transfer request goes into a queue and executes depending on the traffic in the queue and START_DATE and START_TIME. The transfer starts immediately.
NO Default: YES
357
START_DATE Indicates the date on which the transfer becomes eligible for execution. The format is mm/dd/yy. If this field is blank, the current date is used. Example: A value of 02/28/02 indicates February 28, 2002 as the start date. Format: mm/dd/yy Default: None START_TIME Indicates the time when the transfer becomes eligible for execution. The military format of hh:mm:ss is used. If this field is blank, then the current time is used. Example: A value of 14:00:00 indicates 2 p.m. as the start time. Format: hh:mm:ss Default: None
Example 1
The following example uses the xcom62 command. When the transfer completes, local user user1 is notified with a mail message, and remote user USER2 is notified with a TSO message if the transfer receives an error.
xcom62 -f LOCAL_NOTIFY=user1 NOTIFYL=MAIL NOTIFY_NAME=USER2 NOTIFYR=TSO RMTNTFYL=E LCLNTFYL=A
All other necessary parameters are read from the default configuration file, xcom.cnf.
358
User Guide
Example 2
The following example uses the xcomtcp command. When the transfer completes, local user user1 is notified with a mail message, and remote user USER2 is notified with a TSO message if the transfer receives an error.
xcomtcp -f LOCAL_NOTIFY=user1 NOTIFYL=MAIL NOTIFY_NAME=USER2 NOTIFYR=TSO RMTNTFYL=E LCLNTFYL=A
All other necessary parameters are read from the default configuration file, xcom.cnf.
Parameters
The notification parameters are shown below. LOCAL_NOTIFY Specifies the user on the local system who is to be notified that Unicenter CA-XCOM Data Transport has completed a transfer. Unicenter CA-XCOM Data Transport uses the NOTIFYL parameter to determine the type of notification to use. Range: 0 to 64 characters Default: None LCLNTFYL Specifies the local user notification level. Range: The range of values is listed in the following table: Value A or ALL W or WARN E or ERROR Default: ALL Description NOTIFY on transfer completion. NOTIFY only if the transfer received a warning or error. NOTIFY only if the transfer received an error.
359
NOTIFYL The local user notification flag. Range: The range of values is listed in the following table: Value WRITE MAIL NONE ALL Default: None Note: The L in NOTIFYL indicates that the local system governs the processing of the resulting notification on that system. NOTIFY_NAME The user on the remote system who is to be notified when Unicenter CA-XCOM Data Transport completes a transfer. Note: If the remote system is an IBM mainframe, Unicenter CA-XCOM Data Transport uses the value of NOTIFYR to determine the type of notification to deliver. If the remote system is a UNIX or Linux system, the user receives a mail message. Range: 0 to 12 characters Default: None NOTIFY_TERM Specifies which terminals to write to if NOTIFYL=WRITE. If NOTIFY_TERM is not set, all users specified in LOCAL_NOTIFY are notified at the first terminal where they are logged in, as found in the system table. Range: 0 to 256 characters Default: None Description A message is displayed on the workstation where the user is logged in. A mail message will be sent to the user. No notification is sent. A message is displayed on all workstations attached to the server.
360
User Guide
NOTIFYR Specifies the remote user notification type when sending data to a remote system. Range: The range of values is listed in the following table: Value WRITE MAIL TSO WTO CICS LU ROSCOE NONE ALL Default: None Note: The R in NOTIFYR indicates that the remote system governs the processing of the resulting notification on that system. RMLNTFYL Specifies the remote user notification level when sending data to a remote system. Range: The range of values is listed in the following table: Value A or ALL W or WARN E or ERROR Default: ALL Description NOTIFY on transfer completion. NOTIFY only if the transfer received a warning or error. NOTIFY only if the transfer received an error. Description A message is displayed on the screen. A mail message is sent to the user. The specified TSO user is notified. Unicenter CA-XCOM Data Transport writes to the log only (WTO). The specified CICS user is notified. The specified Logical Unit is notified. Notify Advantage CA-Roscoe user. No notification is sent. Write to all users.
361
All other necessary parameters are read from the default configuration file, xcom.cnf.
362
User Guide
Example 2 In the following example, the xcomtcp command is used. If the transfer is interrupted, it restarts from the most recent checkpoint of every 2000 records, and up to three attempts are made to retry the transfer at intervals of 30 seconds.
xcomtcp -f CHECKPOINT_COUNT=2000 NUMBER_OF_RETRIES=3 RESTART_SUPPORTED=YES RETRY_TIME=30
All other necessary parameters are read from the default configuration file, xcom.cnf.
Parameters
The checkpoint and restart parameters are shown below. CHECKPOINT_COUNT Defines how often (based on record count) the sending system requests a checkpoint to be taken. The value 0000 indicates no checkpointing. Range: 0 to 9999 Default: 1000 Note: This is a Version 2 parameter. NUMBER_OF_RETRIES Maximum number of retries before a transfer is logged as failed and taken out of the transfer queue. If the value is 0, no retries are attempted. Range: 0 to 255 Default: 1 Note: This is a Version 2 parameter. RESTART_SUPPORTED Specifies whether automatic restart is to be supported on a transfer. Range: YES or NO Default: YES Note: This is a Version 2 parameter.
363
RETRY_TIME The number of seconds between retries of unsuccessful transfers. Range: 0 to 99999 Default: 1 Note: This is a Version 2 parameter.
364
User Guide
Chapter
XcomAPI XcomQAPI
The XcomAPI provides the ability to submit transfers to Unicenter CA-XCOM Data Transport. The XcomQAPI provides the same functionality as the XCOMQM command line, but through an API.
XcomAPI
The XcomAPI routine uses C structures defined in the xcomapi.h file to pass information to Unicenter CA-XCOM Data Transport. The Unicenter CA-XCOM Data Transport XcomAPI function call takes a starting state and a parameter block structure as its arguments. For transfers using SNA, before invoking XcomAPI, an SNA session must be active with the desired remote system. For the location of the xcomapi.h file, see the Unicenter CA-XCOM Data Transport Getting Started for your platform.
XcomQAPI
The XcomQAPI routine uses C structures defined in the xcomapi.h file to return information from the Unicenter CA-XCOM Data Transport Queue. The Unicenter CA-XCOM Data Transport XcomQAPI function call takes a parameter field as its argument, which allows you to delete entries from the queue, suspend a transfer, resume a suspended transfer, display the list of entries in the queue, and display detailed information about the queue entries.
41
These commands set the appropriate access permissions for using Unicenter CA-XCOM Data Transport with your program.
Link Libraries
When linking libraries, you must use the appropriate Unicenter CA-XCOM Data Transport libraries for non-queued transfers that use SNA/APPC or TCP/IP protocols. For queued XcomAPI transfers and XcomQAPI requests that are not combined with an XcomAPI transfer, either set of files is satisfactory. Sample links for use with both SNA and TCP/IP transfers are provided in the makefile and qapimake files distributed with Unicenter CA-XCOM Data Transport. For the locations of the library files and the API source files, see the Getting Started for your platform. SNA Libraries The following libraries are required for performing non-queued SNA transfers:
libxcom.a libxcomcomp.a
TCP/IP Libraries The following libraries are required for performing non-queued TCP/IP transfers:
libxcomcomp.a libxcomtcp.a libxcomtxpi.a
42
User Guide
Starting States
Valid starting states are as follows: Starting State
LOCAL_SEND
Used For Initiates the transmission of a local file to a remote system as a report, job, or file transfer. Initiates the transmission of a remote file to the local system. The value returned by XcomAPI is zero if the transfer was successful. If not, an error code as defined in the startst.h header file is generated.
43
*blksize, /* block size */ /* remote printing parameters */ *local_file_sr, /* local filename for sending reports */ *class, /* printjob class */ *destination, /* name of remote printer */ *form, /* name of special forms to be used */ *fcb, /* Form Control Block */ *copies, /* number of copies to be printed */ *report_title, /* report name (banner) to be used on separator sheet */ *hold, /* flag for MVS spoolers */ *spool_flag, /* turns on spooling on receiving side */ *disposition, /* MVS file disposition */ *carriage_control_characters, /* A - ASA chars in column 1 M -IBM Machine chars (MVS) */ *local_file_sj, /* local filename for sending jobs */ *userid, /* user id */ *password, /* password */ *queue, /* YES - queue transactions NO - execute immediately */ *start_time, /* time to start scheduled transaction */ *start_date, /* date to start scheduled transaction */ *notifyr, /* TSO / WTO / CICS / LU / VM */ *notify_name, /* who to notify */ *local_notify, /* user name for notification */ *notifyl, /* MAIL / WRITE */ *notify_term, /* user's terminal to notify if notifyl=WRITE */ *maxreclen, /* maximum record length */ *code_flag, /* ASCII / BINARY / EBCDIC */ *carriage_flag, /* specifies if it is a text file or a type of record packing to use */ *truncation, /* YES - truncation is allowed for this transfer */ *compress, /* YES / NO */ *xtrace, /* trace level */ *stat_frequency, /* How often to put record stats to Q-record */ *debug_flag, /* YES - debug output written to /tmp/<tid>.it file */ *xlogfile, /* log for locally initiated transactions */ *tempdir, /* directory to hold temporary files */ /* parameters used by xcom62 version 2 only */ *version, *number_of_retries, *allocation_type, *checkpoint_count, *num_of_dir_blocks, *primary_alloc, *secondary_alloc, *restart_supported, /* parameters used by XCOM 3.1 only */ *trusted, *domain, *den, *expdt, *retpd, *label, *tape, *unitct, *volct, *volsq, *labelnum *tapedisp, /* parameters used by xcom r11 only */ *xcomfullssl *configssl, *rmtntfyl,
44
User Guide
*lclntfyl, *storcls, *datacls, *mgtclas, *dsntype, /* Reserved for future use */ *seclabel, *hfs_flag, /* parameters normally taken from shared memory but may be overwritten in API */ *xlpcmd, /* print command with full path */ *xppcmd, /* postprocess command with full path */ *xprecmd, /* pre-allocation exit command with full path */ *xendcmd, /* ending exit command with full path */ *xnotifycmd, /* path name of command to notify users */ *shell_cmd, /* command to run shell scripts */ *eol_classes, /* print classes having NL added at end of record */ *convert_classes, /* classes needing ebcdic-ascii translation */ *metacode_classes, /* classes needing variable length records */ *ppVersion; /* Enable xcompp.bat for all transfers? */ } XCOM_PARM; typedef struct { char user_name[128]; /* char array_message[128]; char array_message2[128]; char array_err_message[128]; } XCOM_QUEUE_ENTRY; user name */ /* return text from multi-entries */ /* return text from multi-entries */ /* return text from multi-entries */
typedef XCOM_QUEUE_ENTRY XCOM_QUEUE[9999]; typedef struct { char funccode[2]; /* function code */ char tid[7]; /* transfer id (6 characters + null) */ char global_tid[128]; /* local transfer id */ char remote_tid[128]; /* remote transfer id */ int queue_open_once; /* allow queue open once */ int nMax_Queue_Entries; /* Maximum number of queue_entry */ int nQueueEntries; /* number of queue_entry returned */ int trace_level; /* trace level */ FILE *trace_stream; /* file handle for trace file */ char trace_filename[256]; /* name of the trace file */ char start_time[128]; /* start time */ char end_time[128]; /* end time */ char user_name[128]; /* remote user name */ char group_name[128]; /* group name */ char transfer_name[128]; /* user definable id for transfer request */ char xferdata[128]; /* user data -- transfer specific */ char sysdata[128]; /* user data -- system dependent */ char in_out[128]; /* in_out value */ char pid[128]; /* process id */ char remote_system[128]; /* remote lu name */ char file_type[128]; /* file type */ char transfer_type[128]; /* transfer type */ char user_group[128]; /* owned by user from group */ char lfile[257]; /* local file */ char file[257]; /* temporary file */ char rfile[257]; /* remote file */ char file_option[128]; /* file creation option */ char curr_cond[128]; /* current condition */ char curr_status[128]; /* current status */ char curr_state[128]; /* current TP state */ char rec_read_write[128]; /* record read or written to file */ char byte_read_write[128]; /* bytes read or written to file */ char blocks_trans[128]; /* blocks transmitted */ char bytes_trans[128]; /* bytes transmitted */
45
char sdsmessage[160]; char head_message[128]; char queue_message[128]; char start_message[128]; char start_message2[128]; char end_message[128]; XCOM_QUEUE *pQueue; } XCOM_QUEUE_PARM;
/* /* /* /*
/* message test for SDSNOTE */ title message */ return text from queue */ return text from start of xcomd service */ return text from start of xcomd service */ /* return text from end of process */ /* A array of XCOM_QUEUE structure */
#ifdef _NO_PROTO int XcomAPI(); #else int XcomAPI(int invocation_mode,XCOM_PARM xparmblock); #endif #ifdef _NO_PROTO int XcomQAPI(); #else int XcomQAPI(XCOM_QUEUE_PARM * xqueueblock); #endif #endif /* __INCL_XCOMAPI_H */
Member Names
The member names in the following list are used to create C structures that specify aspects about a transfer. The appropriate information is then passed to Unicenter CA-XCOM Data Transport by the XcomAPI routine. The XcomAPI member names are listed below in alphabetical order.
46
User Guide
allocation_type Indicates the unit of storage allocation for a dataset created on an IBM mainframe. Range: The range of values is listed in the following table: Value CYL TRK BLK
Default: CYL
Note: Version 2 parameter. blksize Specifies the block size of the data set created on an IBM mainframe. Range: 0 to 32767 If the record format is Fixed or fixed block Variable Undefined
Default: 800
Then the block size must be A multiple of the record length 4 bytes larger than the record length Larger than the largest record length. A maximum of 5 digits can be entered
47
carriage_control_characters Indicates the type of printer carriage control codes, if any, that are included in the report file Note: For report transfers only. Range: The range of values is listed in the following table: Value ASA IBM BYPASSASA OTHER
Default: OTHER
Description ASA control codes in column 1. IBM Machine Characters (valid only for IBM mainframes). If data is already in ASA format, bypass conversion. No carriage-control codes are used.
carriage_flag Specifies the type of file being transferred and some special characteristics of the conversion done during the transfer. Range: The range of values is listed in the following table: Value YES Description Indicates that the transferred file is a text file and a newline character should be added to the end of incoming records. Also, newline characters are removed from the ends of lines before an outgoing record is sent. Indicates no special processing. Indicates a text file with record packing. Uses 2K pack buffer. Indicates a binary file of variable-length records with a field of 4 bytes preceding each record. Applies to local initiated transfers only. Indicates a binary file of variable-length records with a field of 8 bytes preceding each record. Applies to local initiated transfers only. Used for certain applications that require an MVS-style BDW and RDW preceding each record. Indicates a text file with record packing. Uses 31K pack buffer.
NO MPACK VLR
VLR2
XPACK
48
User Guide
Note: MPACK does not support a MAXRECLEN (actual record length) over 2K. XPACK does not support a MAXRECLEN (actual record length) over 31K.
Default: YES
checkpoint_count Defines how often (based on record count) the sending system requests a checkpoint to be taken. The value 0000 indicates no checkpointing. Range: 0 to 9999 Default: 1000 Note: Version 2 parameter. class The print class assigned to a report transferred to a remote system. If the remote system is an IBM mainframe, this field designates the JES SYSOUT class. Note: For report transfers only. Example: Enter B to print the report through SYSOUT=B. Range: 1 character Default: None code_flag Used to identify the type of data being transferred. Range: The range of values is listed in the following table: Value ASCII Description An ASCII file is being transferred. This indicates that the incoming file is assumed to be ASCII format, and is not translated. Therefore the file on the remote system should be in ASCII format before it is transferred. A binary file, such as an executable file, is being transferred. This indicates to a remote system that it is not to translate the data it is exchanging with your system.
BINARY
49
Value EBCDIC
Description An EBCDIC file is being transferred. The transferred data is translated from EBCDIC to ASCII format when the local system receives the data, and from ASCII to EBCDIC format when the local system sends the data.
Default: ASCII
codetabl Specifies the prefix to the file names, atoe.tab and etoa.tab, that contain the external ASCII-to-EBCDIC and EBCDIC-to-ASCII custom character conversion tables. These custom character conversion tables determine which external translation tables will be used by the transfer. This parameter is valid only if INTERNAL_CONVERSION_TABLES=NO. Range: 0 to 12 characters Default: None compress Indicates the compression type. When communicating with an IBM mainframe, if the data file contains any empty lines, COMPRESS can only be set to YES, LZSMALL, LZMEDIUM or LZLARGE. Note: All compression types are not supported on all platforms. See the partner platform documentation for supported compression types. Range: The range of values is listed in the following table: Note: The LZ values enable LZ (Lempel-Ziv) compression to replace sequences of data bytes that occur more than once in a datastream with a code value. Value COMPACT LCOMPACT LZLARGE LZMEDIUM Description RJE compaction algorithm optimized for uppercase English text. RJE compaction algorithm optimized for lowercase English text. Activates LZ compression to search back 32K in the datastream for a matching string. Activates LZ compression to search back 16K in the datastream for a matching string.
410
User Guide
Description General-purpose algorithm that runs fast and gives reasonable compression. Activates LZ compression to search back 4K in the datastream for a matching string. Indicates no compression. Run length encoding. Indicates run length encoding of binary zeros and blanks only. Greater compression than LZRW3 but less than LZSMALL, LZMEDIUM, and LZLARGE. The value n can be 1 through 9.
convert_classes A character string containing print classes for which EBCDIC-to-ASCII conversions are performed. For incoming report transfers only. Range: 1 to 64 characters Default: None copies The number of copies to be sent. If this parameter is not specified, the remote system queues one copy of the report to the systems default printer. For report transfers only. Range: 1 to 999 Default: 1 dataclas Specifies the name of the data class to be used when allocating a new SMS-managed data set. Note: This parameter applies only to mainframe SMS data sets. Range: 1 to 8 characters Default: None
411
debug_flag Specifies whether a trace will be output to the file /tmp/<tid> instead of to the default path /usr/spool/xcom/trace/<tid>.TRA. In addition to the transfer trace information, the initialization will also be traced. The trace level is still taken from the variable XTRACE. Note: <tid> refers to the 6-digit transfer ID number. Range: The range of values is listed in the following table: Value YES NO Description The trace is output to /tmp/<tid> The trace is output to /usr/spool/xcom/trace/<tid>.TRA. For HP-UX systems: /var/spool/xcom/trace/<tid>.TRA For OSF Digital UNIX systems: /var/opt/xcom/trace/<tid>.TRA.
Default: NO
den Specifies the density to be used in creating a tape on the local or remote system. Valid values are the same as those for the DEN parameter in JCL. Range: 1 to 4 Default: None destination Identifies the printer or other device on the remote system where the report is to be sent. If this parameter is not specified, the remote system sends the report to the system's default printer. For report transfers only. Range: The range of values is listed in the following table: Value 0 to 16 characters 0 to 21 characters
Default: None
Description For indirect transfers and for Version 1. For transfers that are not indirect and for Version 2.
412
User Guide
disposition Indicates what the remote system does with the report file after the report has been printed. For report transfers only. Note: This field is not used when the remote system is an IBM mainframe. Range: The range of values is listed in the following table: If the value is DELETE KEEP HOLD
Default: DELETE
domain The Windows domain name for use in authenticating the user ID and password when accessing a Windows based machine that has sharable disks and drives that belong to that domain. This allows users to access these sharable drives without having to have a local user ID or password defined to the machine. Range: 1 to 64 characters Default: None dsntype Specifies the data set definition. Note: This parameter applies only to mainframe SMS data sets. Value LIBRARY PDS Description Defines a PDSE Defines a partitioned data set
Note: These values are IBM standards for SMS processing. Range: 1 to 8 characters Default: None
413
eol_classes A character string containing print classes for which an ASCII newline character will be appended to each record. For incoming report transfers only. Range: 1 to 64 characters Default: None expdt Specifies an expiration date for the tape data set in terms of a two-digit designation for the year and a three-digit designation for the day of the year. For example, in the expiration date 02021, 02 is the year, that is, 2002, and 021 is the 21st day of that year when the tape data set expires. For example, if 02021 is an expiration date, 2002 is the year and 021 is the 21st day of the year. Format: yyddd Default: None Note: EXPDT and RETPD are mutually exclusive; specify one or the other. fcb Identifies the FCB JCL parameter when sending the report file to an IBM mainframe, defining print density, lines per page, and so on. For report transfers only. Range: 0 to 4 characters Default: None file_option Indicates how the transferred data is to be processed by the receiving system. For file transfers only. Range: The range of values is listed in the following table: Value CREATE APPEND REPLACE
Default: CREATE
Description Create a new file on the receiving system. Append the transferred data to an existing file on the receiving system. Replace an existing file on the receiving system.
414
User Guide
Note: When creating a file on an IBM mainframe system, some additional information may be necessary. For more information, see the explanations for RECORD_FORMAT, BLKSIZE, VOLUME, and UNIT parameters. file_type Indicates the type of transmission. Value SEND_FILE SEND_REPORT SEND_JOB RECEIVE_FILE Description File transfer Report to be printed Job Retrieval of a file
form The type of form that should be used to print the report. Since Unicenter CA-XCOM Data Transport places the print job in the remote system's print queue, the print control functions depend on the remote system. Verify beforehand that the requested form is available at the remote site. For report transfers only. Note: When sending a report to a VAX computer, leave this parameter blank unless you are certain that this is a valid form type. VMS interprets this to mean that no special form is being requested. Range: 0 to 10 characters Default: None hold Indicates whether this transferred report file is to be placed on HOLD status on the remote system or is to be readied for immediate printing. Specify Y to request that it be held (spooled) on an MVS system. Range: YES or NO Default: NO
415
label Indicates the type of label associated with a tape data set. The following table lists the valid values for this parameter. Value Processing type: AL, AUL, BLP, LTM, NL, NSL, SL, SUL Description Represent the types of processing to be applied to data sets on tape.
Note: Unicenter CA-XCOM Data Transport for z/OS supports only standard label tapes. Default: AL labelnum Indicates the sequence number of the data set on the tape. The following table lists the valid values for this parameter. Value Sequence number (0001-9999) Default: 0001 lclntfyl Specifies the local user notification level. Range: The range of values is listed in the following table: Value A or ALL W or WARN E or ERROR Default: ALL Description NOTIFY on transfer completion. NOTIFY only if the transfer received a warning or error. NOTIFY only if the transfer received an error. Description This value identifies the sequence number of a data set on tape.
416
User Guide
local_file The name of the file on the local system that is being transferred. If this variable is null or unset, standard input is read. In this manner, Unicenter CA-XCOM Data Transport commands can be used in a pipeline or with redirection. All UNIX or Linux file naming conventions apply. For wildcard transfers, use an asterisk as a file name to indicate that all files within the specified directory are to be transferred. For example, the statement "LOCAL_FILE=/NAMES/*" indicates that all files under the NAMES directory are to be transferred. When a prefix is followed by an asterisk (*), all members beginning with a specific prefix are to be transferred. For example, LOCAL_FILE=/NAMES/AL* requests that files AL, ALEX, and ALICE are all to be transferred. The same rules apply if an asterisk is followed by a suffix. The actual file name range (not including its path) for wildcard transfers can be between 0 - 71 characters. This also includes the file extension where applicable. File names over 71 characters are truncated. However, when sending files to a mainframe PDS, any file name over 8 characters in length is truncated. These systems do not recognize file extensions. For example, a file called longfilename.txt will be truncated to longfile and a file called file.txt will be truncated to file. Note: If QUEUE=YES, user must specify full path name. Range: 0 to 256 characters Default: None local_file_rf The file name that is created, appended, or replaced on the local system when it receives a file. At the command prompt or in a script, if this value is null or unset, then Unicenter CA-XCOM Data Transport writes to the stdout. All UNIX or Linux file naming conventions apply. For wildcard transfers, use an asterisk (*) as a file name to indicate that multiple files will be received. For example, LOCAL_FILE_RF=/PAYROLL/*. If multiple files are received and the user specifies a file name, all files received by the partner are written to that specified file as one single file. For platforms that support it, you can specify a common file extension to be appended to each file name. For example, LOCAL_FILE_RF=/PAYROLL/*.TXT.
417
Note: If QUEUE=YES, the full path name must be specified. Range: 0 to 256 characters Default: None local_file_sj Indicates the name of the file on the local system to be sent as a job. All the UNIX or Linux file naming conventions apply. If this value is null or unset, then Unicenter CA-XCOM Data Transport reads the standard input file. Note: If QUEUE=YES, user must specify full path name. Range: 0 to 256 characters Default: None local_file_sr Specifies the local file name to be sent as a report to the remote system. If this value is null or unset, then Unicenter CA-XCOM Data Transport reads the standard input file. For report transfers only. Note: If QUEUE=YES, user must specify the full path name. Range: 0 to 256 characters Default: None local_notify Specifies the user on the local system who is to be notified that Unicenter CA-XCOM Data Transport has completed a transfer. Unicenter CA-XCOM Data Transport uses the NOTIFYL parameter to determine the type of notification to use. Range: 0 to 64 characters Default: None
418
User Guide
lrecl Specifies the actual or maximum length, in bytes, of a logical record. Corresponds to the JCL LRECL subparameter. Range: 0 to 32767 If the format is Variable blocked record Fixed or fixed block record
Default: 160
Then the maximum length of a logical record must be equal to the Maximum record length plus 4 Constant record length
maxreclen For Windows NT, UNIX, and Linux systems, the locally initiating Unicenter CA-XCOM Data Transport system determines the values for MAXRECLEN, TRUNCATION, and LRECL, for send and receive operations. When the local Unicenter CA-XCOM Data Transport system initiates a transfer of a text file, this parameter designates the length, in bytes, of the largest record that can be transferred. If a record length is longer than this value, Unicenter CA-XCOM Data Transport uses the value in the TRUNCATION parameter on the initiating side to determine whether to terminate the transfer or to truncate the record and continue the transfer. When Unicenter CA-XCOM Data Transport transfers binary files, this value indicates the length of the records that are transferred. On a receive operation, MAXRECLEN is set to whatever the LRECL value is on the initiating side. Range: 1 to 32767 Default: 1024 metacode_classes Classes of print jobs that are saved in metacode format, a variable length record format. For incoming report transfers only. Range: 0 to 64 characters Default: None
419
mgmtclas Specifies the name of the management class to use when allocating a new SMSmanaged data set. Note: This parameter applies only to mainframe SMS data sets. Range: 1 to 8 characters Default: None notify_name The user on the remote system who is notified when Unicenter CA-XCOM Data Transport completes a transfer. Note: If the remote system is an IBM mainframe, Unicenter CA-XCOM Data Transport uses the value of NOTIFYR to determine the type of notification to deliver. If the remote system is a UNIX or Linux system, the user receives an email message. Range: 0 to 12 characters Default: None notifyl The local user notification flag. Range: The range of values is listed in the following table: Value WRITE MAIL NONE ALL Default: None Description A message is displayed on the workstation where the user is logged in. A mail message is sent to the user. No notification is sent. A message is displayed on all workstations attached to the server.
420
User Guide
notifyr Specifies the remote user notification type when sending data to a remote system. Range: The range of values is listed in the following table: Value WRITE MAIL TSO WTO CICS LU ROSCOE NONE ALL Default: None notify_term Specifies terminals to write if NOTIFYL=WRITE. If NOTIFY_TERM is not set, all users specified in LOCAL_NOTIFY are notified at the first terminal where they are logged in as found in the system table. Range: 0 to 256 characters Default: None number_of_retries Maximum number of retries before a transfer is logged as failed and taken out of the transfer queue. If the value is 0, no retries are attempted. Range: 0 to 255 Default: 1 Note: Version 2 parameter. Description A message is displayed on the screen. A mail message is sent to the user. The specified TSO user is notified. Unicenter CA-XCOM Data Transport writes to the log only (WTO). The specified CICS user is notified. The specified Logical Unit is notified. Notify Advantage CA-Roscoe user. No notification is sent. Write to all users.
421
num_of_dir_blocks Specifies the number of directory blocks to allocate for a dataset created on an IBM mainframe. Range: 0 to 32767 Default: 0 Note: Version 2 parameter password The password associated with the user ID on a remote system. Range: 0 to 31 characters Default: None primary_alloc Identifies primary storage allocation for a data set created on an IBM mainframe. Range: 0 to 99999 Default: 1 Note: Version 2 parameter port The number of the TCP/IP port on the remote Unicenter CA-XCOM Data Transport server. Used for TCP/IP transfers only. Range: 0 to 65535 Default: 8044
422
User Guide
protocol The type of communication protocols to use. Range: The range of values is listed in the following table: Value SNA TCPIP
Default: SNA
Description For transfers using SNA/APPC communication protocols For transfers using TCP/IP communication protocols
queue Indicates whether to execute the transmission request immediately or to allow the request to be queued. If the user does not specify a .cnf file, and has not changed a .cnf file, the default value is YES. Note: If NO is specified and the remote system is unavailable, the request aborts. If YES is specified, start_time and start_date are read. Range: The range of values is listed in the following table: Value YES Description The transfer request goes into a queue and executes depending on the traffic in the queue and START_DATE and START_TIME. The transfer starts immediately.
NO
Default: NO
423
rmtntfyl Specifies the remote user notification level when sending data to a remote system. Range: The range of values is listed in the following table: Value A or ALL W or WARN E or ERROR Default: ALL record_format Specifies the record format of a dataset created on an IBM mainframe. This corresponds to the JCL RECFM subparameter. Range: The range of values is listed in the following table: Value F FA Description Fixed unblocked Fixed unblocked ANSI Fixed blocked Record Length The same length as the data set. The same length as the data set. Fixed. Contains ISO/ANSI/FIPS control characters. Fixed record length with multiple records per block. Multiple records per block where these records contain ISO/ANSI/FIPS control characters. Multiple records per block written as standard blocks. Contains machine code control characters. Comment Description NOTIFY on transfer completion. NOTIFY only if the transfer received a warning or error. NOTIFY only if the transfer received an error.
FB
FBA
Fixed.
FBS
Fixed.
FM
424
User Guide
Value FS
Comment Written as standard blocks where these records do not contain any truncated blocks or unfilled tracks.
U V VA
Undefined Variable unblocked Variable unblocked ANSI Variable blocked Variable blocked ANSI
Undefined. Variable. Variable. Contains ISO/ANSI/FIPS control characters. Multiple records per block. Multiple records per block where these records contain ISO/ANSI/FIPS control characters. Multiple records per block where these records contain machine code control characters. May have multiple records per block where these records can span more than one block. Contains machine code control characters. A record can span more than one block.
VB VBA
Variable. Variable.
VBM
Variable.
VBS
Variable.
VM
Variable.
VS
Variable.
Default: VB
425
remote_file Indicates the file on the remote computer to which the transferred data is being written. If you are creating the file (FILE_OPTION=CREATE), the file name must be consistent with the file naming conventions of the remote system. The local Unicenter CA-XCOM Data Transport system does not validate this name. The remote I/O system determines whether the file name is valid. For wildcard transfers, use an asterisk (*) as a file name to indicate and to inform the receiving partner that multiple files will be sent. For example, REMOTE_FILE=/PAYROLL/*. If multiple files are sent and the user specifies a file name, all files received by the partner are written to that specified file as one single file. An asterisk used to send files to an IBM mainframe system shows that all files are to be transferred to a partitioned data set (PDS). For platforms that support it, you can specify a common file extension to append to each file name; for example, REMOTE_FILE=/PAYROLL/*.TXT. Note: For send file transfers only. Range: 1 to 256 characters Default: None remote_file_rf Indicates the name of the file to be retrieved from the remote system. For wildcard transfers, use an asterisk (*) as a file name to indicate that all files within the specified PDS/Directory should be transferred. For example, the statement REMOTE_FILE_RF=/NAMES/* indicates that all files under the NAMES directory should be transferred. When a prefix is followed by an asterisk, all members beginning with a specific prefix are transferred. For example, REMOTE_FILE_RF=/NAMES/AL* requests that files AL, ALEX, and ALICE should be transferred. The same rules apply if an asterisk is followed by a suffix.
426
User Guide
The actual file name range (not including its path) for wildcard transfers can be between 0 and 71 characters. This also includes the file extension where applicable. File names over 71 characters are truncated. Note: For retrieve file transfers only. Range: 1 to 256 characters Default: None remote_system The name of the remote system that receives a file, job or report. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None remove_trail_blanks Indicates whether or not to remove the blanks at the end of each record when receiving a text file. Range: YES or NO Default: NO
427
report_title This field contains the report title and job number that will be printed on the report. The field has the following format: 8 characters Job Name 2 characters Blanks 8 characters Job Number
The Job ID is optional and can be skipped. The Job Name can also be skipped, but if you skip the Job name and want to use the job number, you must pad the number with 10 blanks. For more information, see the appendix Parameters. Note: For report transfers only. Range: 0 to 21 alphanumeric or blank characters Default: None restart_supported Specifies whether automatic restart is to be supported on a transfer. Range: YES or NO Default: YES Note: Version 2 parameter. retpd Specifies the number of days (1 to 9999) that the tape data set being created is to be retained.
Range: 1 to 9999 Default: None
Note: RETPD and EXPDT are mutually exclusive; specify one or the other.
428
User Guide
secondary_alloc Identifies secondary storage allocation for a dataset created on an IBM mainframe. Range: 0 to 99999 Default: 0 Note: Version 2 parameter. secure_socket Specifies whether to use an OpenSSL socket or non-OpenSSL socket for transfers. Value YES Description Performs secure transfer. The transfer uses an OpenSSL socket and must to connect to a SSL listener on the remote partner. NO Performs non secure transfer. The transfer uses a non-OpenSSL socket. Default: NO shell_cmd Name of the command that runs jobs, reports, notification scripts, and post processing scripts on the local system. Range: 1 to 256 characters Default: /bin/ksh spool_flag Indicates whether the report is to be spooled to disk or printed immediately. For report transfers only. Note: If the remote system is an IBM mainframe, this parameter has no effect on the transfer. Range: YES or NO Default: YES
429
start_date Indicates the date on which the transfer becomes eligible for execution. The format is mm/dd/yy. If this field is blank, the current date is used. Format: mm/dd/yy Default None start_time Indicates the time when the transfer becomes eligible for execution. The military format of hh:mm:ss is used. If this field is blank, then the current time is used. Format: hh:mm:ss Default: None stat_frequency Indicates the frequency with which transfer statistics are made available to xcomqm. Intended for tuning high-speed links. Longer values help performance, but byte/record counts in xcomqm -D may be slightly behind the actual counts. Range: 1 to 9999 records Default: 10 storclas Specifies the name of the storage class for a new SMS-managed data set. Note: This parameter applies only to mainframe SMS data sets. Range: 1 to 8 characters Default: None tape Indicates to the remote system whether the volume is a tape volume or a disk file. Yes indicates a tape volume and that mounts are allowed when performing dynamic allocation. No indicates that the transfer is to a disk file. Range: YES or NO Default: NO
430
User Guide
tempdir Indicates the directory in which temporary files for jobs and reports can be created. Range: 1 to 256 characters Default: /tmp truncation Indicates whether Unicenter CA-XCOM Data Transport truncates excess characters in the source file if the record exceeds the maximum record length as indicated by the MAXRECLEN parameter. If NO is selected, and the maximum record length is exceeded, Unicenter CA-XCOM Data Transport aborts the transfer. This parameter is ignored if CARRIAGE_FLAG=NO. Note: Truncation is not valid for BINARY data or for non-text data received on the UNIX or Linux platform. Range: YES or NO Default: NO trusted Allows the user to request a trusted transfer and the partners Unicenter CA-XCOM Data Transport TRUSTED database to be searched to verify the users credentials. This eliminates the need for the user to specify a USERID and PASSWORD. If XCOM_TRUSTED_OVR is set to NO or no USERID is specified, the USERID of the process that initiated the transfer will be used. Note: TRUSTED=YES cannot be specified with indirect transfers, because this is not supported. Range: YES, NO, Y, N Default: NO unit Specifies the unit on which a dataset is to be created on an IBM mainframe. Note: Used when FILE_OPTION=CREATE. Range: 0 to 6 characters Default: None
431
unitct Specifies the number of units to be allocated on the remote system. Range: 1 to 20 Default: None userid The user ID which the security system on a remote system checks before granting access for the file transfer. Range: 0 to 12 characters Default: None version Indicates the version of the Unicenter CA-XCOM Data Transport protocol to be used for this transfer. For using TCP/IP, only a value of 2 is valid. Range: 1 or 2 Default: 2 Note: Version 2 parameter. volct Specifies the maximum number of volumes to be used in processing a multivolume output tape data set on the remote system. Range: 1 to 255 Default: None volsq Specifies the sequence number of the first volume of a multi-volume remote data set to be used. Range: 1 to 255 Default: None
432
User Guide
volume Specifies the volume on which a dataset is to be created on an IBM mainframe. Range: 0 to 6 characters Default: None xbuffsize Specifies the buffer size to determine size of records to be read from UNIX or Linux files. xcom_config_ssl Specifies the configssl.cnf file path and file name. Range: 1 to 256 characters Default: /usr/ spool/xcom/config/configssl.cnf, except for the following:
For HP-UX systems: /var/spool/xcom/config/configssl.cnf For OSF Digital UNIX systems: /var/opt/xcom/config/configssl.cnf
xcom_show_cipher Specifies whether to display encryption algorithms in the Unicenter CA-XCOM Data Transport queue detailed information, which is used for transfers. Value NO YES Default: NO Description Do not display encryption algorithms in the queue detail information. Display encryption algorithms in the queue detail information.
433
xendcmd The name of the post processing command optionally invoked by the Unicenter CA-XCOM Data Transport transfer program after any type of transfer is finished, whether successful or not. Invoked after partner communications have ended. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcomend For HP-UX systems: /opt/xcom/lib/xcomend For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcomend
xidest Specifies the name of the LU or TCP/IP address on the intermediate destination that is designated for store-and-forward transfers. If this variable is null or unset, then a direct connection to a remote system is attempted. If it contains a value, it is taken to be the name of an intermediate Unicenter CA-XCOM Data Transport that will handle traffic to and from the named remote system. Note: For store-and-forward transfers only. Range: 0 to 14 characters Default: None xlogfile The name of the file where Unicenter CA-XCOM Data Transport logs activity. If you do not specify this parameter, the systemwide log file /usr/spool/xcom/xcom.log is used. If you specify this parameter with a different file name, the logging information is only sent to the specified file. Note: If QUEUE=YES, specify the full path name. Range: 0 to 256 characters Default: /usr/spool/xcom/xcom.log, except for the following:
434
User Guide
xlpcmd Name of the post-processing command used to send print jobs to the spooler. For incoming reports only. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcomlp For HP-UX systems: /opt/xcom/lib/xcomlp For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcomlp
xluname Indicates the name of the local LU. This name must match the remote LU name on the remote system. Range: 1 to 17 characters Default: None Note: Not used in Unicenter CA-XCOM Data Transport for RS/6000 SNA Services or RS/6000 SNA Server. xmode Indicates the mode name associated with the SNA/APPC configuration for the XLUNAME-Remote LU name pair. This name must match the mode name defined on the remote system. Range: 1 to 8 characters Default: XCOMMODE Note: Not used in Unicenter CA-XCOM Data Transport for RS/6000 SNA Services or RS/6000 SNA Server. xnodespec Required for Brixton and SunLink APPCs. Indicates the name of the node that specifies the gateway to use for the transfer. Does not apply to other APPCs. Range: 1 to 64 characters Default: None
435
xnotifycmd Specifies the path name of the command that Unicenter CA-XCOM Data Transport will use to notify users on the local system of the completion of a transfer. This is normally a shell script that composes a message and invokes mail or write as appropriate. Range: 0 to 256 characters Default: System For UNIX/Linux systems For HP-UX systems For OSF Digital UNIX systems Value /usr/lib/xcom/xcomntfy /opt/xcom/lib/xcomntfy /usr/opt/xcom/lib/xcomntfy
xppcmd Specifies the path name of the command used for user-defined post processing, for file transfers only. Only used when the local system is receiving the file. Range: 0 to 64 characters Default: System For UNIX/Linux systems For HP-UX systems For OSF Digital UNIX systems Value /usr/lib/xcom/xcompp /opt/xcom/lib/xcompp /usr/opt/xcom/lib/xcompp
436
User Guide
xprecmd Specifies the path name of the command used for user-defined pre-allocation processing, for locally and remotely initiated transfers. Specify this parameter in xcom.glb to invoke the pre-allocation exit xcompre. Range: 0 to 64 characters The sample xcompre script is located in the directory as indicated below: System For UNIX/Linux systems For HP-UX systems
Default: None
xtrace Indicates the level of desired execution tracing. Range: The range of values is listed in the following table: Value 0 1 to 8 9 10
Default: 0
Description No tracing Levels of tracing from 1 (lowest) to 8 (highest) Show the contents of the data buffers Includes levels 1 to 9 plus some additional detailed technical information
437
Option Parameters
The option parameters in the following list are used to pass and retrieve information from the queue request. funccode Used to define a function parameter to pass to XcomQAPI(). Value r Aentryname Centryname Dentryname Hentryname L[ ] La Rentryname Rfentryname Description Display the release level of xcomqm and exit. Release a held transfer. Get a trace of a transfer. Display details about a queue entry. Hold a scheduled transfer. List your queued transfers. List all queued transfers. Remove a queue entry. Force the entry to be removed from the queue. Use this command when you want to remove a transfer that is still active. Remove all completed or scheduled entries from the queue. If you use this option on an active transfer, it interrupts the transfer. Terminate an active transfer.
R*
Tentryname
438
User Guide
Value Tfentryname
Description Force termination of the transfer. Use this command when you want to remove a transfer that is still active. Caution! When using SNA/APPC protocols, the TP will ABEND and it may be necessary to restart the underlying SNA software. When using TCP/IP, xcomtcp will ABEND.
Suspend a transfer. Resume a suspended transfer. Create a trace file. Display queue entry information. Used to change the value of: FILE_OPTION LOCAL_FILE REMOTE_FILE. Note: This option can be called only when xcbp->state is in PREALLOCATION_STATE.
Note: The entryname variable represents the Transaction ID, which is the six-digit name of the transfer entry in the queue. tid A queue entry TID number. queue_open_once Open queue flag. Define this only once at first call of XcomQAPI. The value should be set to 0. nMax_Queue_Entries Defines maximum queue entries. The value should be set to equal MAX_QUEUE_ENTRIES in the xcom.glb file. trace_level Defines the trace level. The value can be set to 0, 1, or 9.
439
API Examples
trace_filename It defines a trace file name and its location; for example, /usr/spool/xcom/trace/xcomqapi.tra.
API Examples
The following API is an example of a file transfer. It uses the XcomAPI routine to pass information to Unicenter CA-XCOM Data Transport. This sample API program is the apitest.c file distributed with Unicenter CA-XCOM Data Transport. (For the location of this file, see the Unicenter CA-XCOM Data Transport Getting Started for your platform.) Note: The API example provided on your distribution media may have been updated for your Unicenter CA-XCOM Data Transport system and may be different from the example shown below.
/* remember to link with the appropriate xcom libraries for each protocol */ xcomparm.protocol = "TCPIP"; /* "SNA" or "TCPIP" */ xcomparm.remote_system = "remote_host"; xcomparm.port = "8044"; xcomparm.xluname = "LOCUNIX"; xcomparm.xnodespec = NULL; xcomparm.xmode = "XCOMMODE";
440
User Guide
API Examples
xcomparm.xidest = NULL; xcomparm.local_file = "/usr/include/xcom/xcomapi.h"; xcomparm.remote_file = "/home/user/newfile.name"; xcomparm.local_file_rf = "/tmp/receive.filename"; xcomparm.remote_file_rf = "/home/user/file.there"; xcomparm.file_option = "REPLACE"; xcomparm.remove_trail_blanks = NULL; xcomparm.volume = NULL; xcomparm.unit = NULL; xcomparm.record_format = NULL; xcomparm.lrecl = NULL; xcomparm.blksize = NULL; xcomparm.local_file_sr = NULL; xcomparm.class = NULL; xcomparm.destination = NULL; xcomparm.form = NULL; xcomparm.fcb = NULL; xcomparm.copies = NULL; xcomparm.report_title = NULL; xcomparm.hold = NULL; xcomparm.spool_flag = NULL; xcomparm.disposition = NULL; xcomparm.carriage_control_characters = NULL; xcomparm.local_file_sj = NULL; xcomparm.userid = "uuuuuuuu"; xcomparm.password = "xxxxxxxx"; /* if queue = NO, must link with right xcom lib */ xcomparm.queue = "NO"; xcomparm.start_time = NULL; xcomparm.start_date = NULL; xcomparm.notifyr = NULL; xcomparm.notify_name = NULL; xcomparm.local_notify = NULL; xcomparm.notifyl = NULL; xcomparm.notify_term = NULL; xcomparm.maxreclen = NULL; xcomparm.code_flag = "ASCII"; xcomparm.carriage_flag = NULL; xcomparm.truncation = NULL; xcomparm.compress = NULL; xcomparm.xtrace = "10"; xcomparm.stat_frequency = NULL; xcomparm.debug_flag = NULL; xcomparm.xlogfile = NULL; xcomparm.tempdir = NULL; xcomparm.xlpcmd = NULL; xcomparm.xnotifycmd = NULL; xcomparm.eol_classes = NULL; xcomparm.convert_classes = NULL; xcomparm.metacode_classes = NULL;
441
API Examples
/* These are version two parms */ xcomparm.version = NULL; xcomparm.number_of_retries = NULL; xcomparm.allocation_type = NULL; xcomparm.checkpoint_count = NULL; xcomparm.num_of_dir_blocks = NULL; xcomparm.primary_alloc = NULL; xcomparm.secondary_alloc = NULL; xcomparm.restart_supported = NULL; /* These parms are new for V3 XCOM */ xcomparm.xppcmd = NULL; xcomparm.xprecmd = NULL; xcomparm.xendcmd = NULL; xcomparm.shell_cmd = NULL; /* These parms are new for V3.1 XCOM */ xcomparm.trusted = NULL; xcomparm.domain = NULL; xcomparm.den = NULL; xcomparm.expdt = NULL; xcomparm.retpd = NULL; xcomparm.label = NULL; xcomparm.tape = NULL; xcomparm.unitct = NULL; xcomparm.volct = NULL; xcomparm.volsq = NULL; xcomparm.labelnum = NULL; xcomparm.tapedisp = NULL; /* These parms are new for r11 XCOM */ xcomparm.xcomsslfull = NULL; xcomparm.configssl = NULL; xcomparm.codetabl = NULL; xcomparm.rmtntfyl = NULL; xcomparm.lclntfyl = NULL; xcomparm.storcls = NULL; xcomparm.datacls = NULL; xcomparm.mgtclas = NULL; xcomparm.dsntype = NULL; /* Reserved for future use */ xcomparm.seclabel =NULL; xcomparm.hfs_flag =NULL; starting_state=LOCAL_SEND; printf("==== API started ===\n"); rc=XcomAPI(starting_state, xcomparm); printf("==== API ended ===\n"); if (!rc) printf("==== Transfer successful\n"); else printf("==== %s\n", msgstrng(rc,0)); /* Reset System Privilages for second transfer */ if (XsetSysPriv(2) !=0) { printf("====XsetSysPriv() faild\n"); } }
442
User Guide
API Examples
443
API Examples
/* call option 'La' to list all queue entries */ xcomqparm->funccode[0] = 'L'; xcomqparm->funccode[1] = 'a'; rc=XcomQAPI(xcomqparm); /* check for error message */ if (strlen((*xcomqparm->pQueue)[0].array_err_message)) printf("%s", (*xcomqparm->pQueue)[0].array_err_message); /* print detail information for all queue entries */ for (i = 0; i < xcomqparm->nQueueEntries; i++) { printf("%s", (*xcomqparm->pQueue)[i].user_name); printf("%s", (*xcomqparm->pQueue)[i].array_message); } if ((xcomqparm->nQueueEntries == 0) && strlen((*xcomqparm>pQueue)[0].array_message)) printf("%s", (*xcomqparm->pQueue)[0].array_message); /* call option 'Dxxxxxx' to display detail record information */ memset(xcomqparm->lfile,0,sizeof(xcomqparm->lfile)); memset(xcomqparm->rfile,0,sizeof(xcomqparm->rfile)); strcpy(xcomqparm->tid, "000001"); xcomqparm->funccode[0] = 'D'; rc=XcomQAPI(xcomqparm); /* check for error message */ if (strlen((*xcomqparm->pQueue)[0].array_err_message)) printf("%s", (*xcomqparm->pQueue)[0].array_err_message); /* display detail record information */ if (strlen(xcomqparm->head_message)) printf("%s", xcomqparm->head_message); if (strlen(xcomqparm->global_tid)) printf("%s", xcomqparm->global_tid); if (strlen(xcomqparm->remote_tid)) printf("%s", xcomqparm->remote_tid); if (strlen(xcomqparm->group_name)) printf("%s", xcomqparm->group_name); if (strlen(xcomqparm->transfer_name)) printf("%s", xcomqparm->transfer_name); if (strlen(xcomqparm->xferdata)) printf("%s", xcomqparm->xferdata); if (strlen(xcomqparm->sysdata)) printf("%s", xcomqparm->sysdata); if (strlen(xcomqparm->start_time)) printf("%s", xcomqparm->start_time); if (strlen(xcomqparm->transfer_type)) printf("%s", xcomqparm->transfer_type); if (strlen(xcomqparm->lfile)) printf("%s", xcomqparm->lfile); if (strlen(xcomqparm->file)) printf("%s", xcomqparm->file); if (strlen(xcomqparm->sdsmessage)) printf("%s", xcomqparm->sdsmessage); if (strlen(xcomqparm->rfile)) printf("%s", xcomqparm->rfile); if (strlen(xcomqparm->in_out)) printf("%s", xcomqparm->in_out); if (strlen(xcomqparm->remote_system)) printf("%s", xcomqparm->remote_system); if (strlen(xcomqparm->end_time)) printf("%s", xcomqparm->end_time); if (strlen(xcomqparm->pid)) printf("%s", xcomqparm->pid); if (strlen(xcomqparm->user_group)) printf("%s", xcomqparm->user_group); if (strlen(xcomqparm->curr_cond)) printf("%s", xcomqparm->curr_cond); if (strlen(xcomqparm->curr_status)) printf("%s", xcomqparm->curr_status);
444
User Guide
API Examples
if (strlen(xcomqparm->curr_state)) printf("%s", xcomqparm->curr_state); if (strlen(xcomqparm->rec_read_write)) printf("%s", xcomqparm->rec_read_write); if (strlen(xcomqparm->byte_read_write)) printf("%s", xcomqparm->byte_read_write); if (strlen(xcomqparm->blocks_trans)) printf("%s", xcomqparm->blocks_trans); if (strlen(xcomqparm->bytes_trans)) printf("%s", xcomqparm->bytes_trans); if (strlen((*xcomqparm->pQueue)[0].array_message)) printf("%s", (*xcomqparm->pQueue)[0].array_message); /* call option 'R*' to remove queue entries */ xcomqparm->funccode[0] = 'R'; xcomqparm->funccode[1] = '*'; rc=XcomQAPI(xcomqparm); /* check for error message */ if (strlen((*xcomqparm->pQueue)[0].array_err_message)) printf("%s", (*xcomqparm->pQueue)[0].array_err_message); /* display detail information for removed queue entries */ for (i = 0; i < xcomqparm->nQueueEntries; i++) { printf("%s", (*xcomqparm->pQueue)[i].array_message); printf("%s", (*xcomqparm->pQueue)[i].array_message2); } if ((xcomqparm->nQueueEntries == 0) && strlen((*xcomqparm>pQueue)[0].array_message)) printf("%s", (*xcomqparm->pQueue)[0].array_message); if (!rc) printf("==== Call XcomQAPI successful !\n"); else printf("==== %s\n", msgstrng(rc, 0)); /* call option 'gxxxxxx' to display queue entry information */ memset(xcomqparm->lfile,0,sizeof(xcomqparm->lfile)); memset(xcomqparm->rfile,0,sizeof(xcomqparm->rfile)); memset(xcomqparm->file_option,0,sizeof(xcomqparm->file_option)); xcomqparm->funccode[0] = 'g'; strcpy(xcomqparm->tid, "000001"); rc=XcomQAPI(xcomqparm); /* check for error message */ if (strlen((*xcomqparm->pQueue)[0].array_err_message)) printf("%s", (*xcomqparm->pQueue)[0].array_err_message); /* display queue entry information */ if (strlen((*xcomqparm->pQueue)[0].array_message)) printf("%s", (*xcomqparm->pQueue)[0].array_message); if (strlen(xcomqparm->group_name)) printf("%s", xcomqparm->group_name); if (strlen(xcomqparm->lfile)) printf("%s", xcomqparm->lfile); if (strlen(xcomqparm->rfile)) printf("%s", xcomqparm->rfile); if (strlen(xcomqparm->user_name)) printf("%s", xcomqparm->user_name); if (strlen(xcomqparm->transfer_type)) printf("%s", xcomqparm->transfer_type); if (strlen(xcomqparm->file_type)) printf("%s", xcomqparm->file_type); if (strlen(xcomqparm->file_option)) printf("%s", xcomqparm->file_option); /* call option 'pxxxxxx' to change value: FILE_OPTION LOCAL_FILE REMOTE_FILE note: This option only allows to call when xcbp->state is in PREALLOCATION_STATE */
445
xcomqparm->funccode[0] = 'p'; strcpy(xcomqparm->tid, "000001"); strcpy(xcomqparm->file_option, "CREATE"); strcpy(xcomqparm->lfile, "/home/user/test.txt"); strcpy(xcomqparm->rfile, "/home/user/test.del"); rc=XcomQAPI(xcomqparm); /* check for error message */ if (strlen((*xcomqparm->pQueue)[0].array_err_message)) printf("%s", (*xcomqparm->pQueue)[0].array_err_message); /* print out queue entry information */ if (strlen((*xcomqparm->pQueue)[0].array_message)) printf("%s", (*xcomqparm->pQueue)[0].array_message); printf("==== } } /* free memory */ if (xcomqparm->pQueue != NULL) free(xcomqparm->pQueue); if (xcomqparm != NULL) free(xcomqparm); } QAPI ended ===\n");
-1
-9 -1100 -1801
446
User Guide
Description XCOMQM is unable to close the index file. XCOMQM detected an invalid command line option.
447
Chapter
51
AS/400
AS/400
This section contains information about important aspects of the AS/400 operating system.
Naming Conventions
Use the following format to specify an AS/400 file:
libraryname/filename(membername)
The following table describes the parts of an AS/400 file name: Part libraryname filename membername Description The name of the library that holds the file. The name of the file you wish to access. Periods are allowed within the file name. The name of the member in the file. If this component is omitted, it defaults to the file name.
Additional Features
XQUE is a Unicenter CA-XCOM Data Transport feature that allows the unattended transfer of reports from output queues to other Unicenter CA-XCOM Data Transport nodes. XQUE can select specific classes of reports (based on the user, job name, form, etc.) from output queues. XQUE also allows user and/or workstation groups to be equated to printer destinations on remote Unicenter CA-XCOM Data Transport nodes. You may use XQUE, for example, to get reports back to your host system that are generated on an AS/400 that you reach through IBMs HCF facility, or between multiple AS/400s connected within a pass-through environment.
52
User Guide
AS/400
Configuration Issues
If you are configuring the VTAM LU that represents the AS/400 on a mainframe, make sure that the VTAM USS message 10 is not sent to that LU. IBMs APPC software cannot start a session when this message, commonly called the welcome message, is sent. To prevent this problem, the VTAM or NCP USSTAB definition must be set to a table that does not have a USSMSG10. The table that IBM originally provided with VTAM is a good alternative because it does not include message 10.
Case Sensitivity
Because the IBM AS/400 is case-sensitive, you must enter the user ID and password in uppercase.
53
z/OS
z/OS
This section contains information about important aspects of the z/OS operating system.
Naming Conventions
Use the following format to name a z/OS file (data set):
[level1.level2.level3...level7].level8[(membername)]
The following table describes the parts of a z/OS file name: Part level Description Required. A file name can consist of multiple levels separated by a period. Each level has the following characteristics: It can be up to eight uppercase characters long. It starts with either an alphabetic character or a national character ($, #, @, +, -, :, _). There is a limit of eight levels with a total of 44 characters, including the separating periods. In most z/OS environments, a data set name is further restricted by security rules created by the installation. Contact the appropriate personnel within your organization for details. Typically, the high-level name (first-level name) must match your z/OS user ID or some other predefined index. membername Required for z/OS partitioned data sets only. Specifies the particular member in a z/OS partitioned data set (PDS). A PDS is a library containing members that are each separate sequential files. The member name is appended to the end of the file name in parentheses. Range: One to eight alphanumeric or national characters. Note: Most sites catalog all files through the system master catalog. In short, this means that the system will be able to locate the file you specify by name only. With the rare occurrence of an uncataloged file, you need to specify the volume and unit information for the device that holds the file.
54
User Guide
z/OS
Examples
The following are examples of valid z/OS data set names:
SYS1.VTAMLST C54684.UTILITY.CNTL(JOBCARD) PROD.PAYROLL.SEPT90.TIMECARD.DATA TESTDATA A.$DDD.LOAD
DCB Information
z/OS characteristics must be pre-defined when creating a new file. Collectively, the following characteristics are known as Data Control Block (DCB) parameters: Blocksize Logical record length Record format Volume Unit For more information regarding any of these fields, see the IBM JCL reference manual.
55
Novell NetWare
Additional Features
You should be aware of the following additional features of Unicenter CA-XCOM Data Transport for z/OS: CICS interfaceTurn this on by indicating that you wish to notify CICS in the appropriate remote system notify field in your version of Unicenter CA-XCOM Data Transport. To do this, provide the VTAM APPLID of the CICS system in the related ID field. Your z/OS CICS application development team can provide you with this. Invoking this interface should start a CICS transaction program following the successful completion of a transfer if one has been provided at the host. Store-and-forwardPerform transfers between two nodes connected to an intermediate z/OS system by invoking the indirect transfer feature in your version of Unicenter CA-XCOM Data Transport. This asks you for the final destination LU name and sends a transfer in two stages. The first stage goes to the z/OS or JES spool, where it waits for the final destination to be connected before the second stage occurs.
Novell NetWare
This section contains information about important aspects of the Novell Netware operating system.
Naming Conventions
Use the following format to name a Netware file: Note: Unicenter CA-XCOM Data Transport for LAN Workstation accesses files from any Novell file server in a NetWare network.
[server\]volume:directory\subdirectory\...\filename
56
User Guide
OpenVMS
Unicenter CA-XCOM Data Transport limits the length of this field as indicated below. The actual name on the destination system may be longer. Type of transfer Direct transfers using Version 2 protocols. Indirect transfers or transfers using Version 1 protocols. Specify Up to 21 characters. Up to 16 characters.
Restriction
Unicenter CA-XCOM Data Transport for NetWare LAN does not support library transfers to Novell NetWare systems.
OpenVMS
This section contains information about important aspects of the OpenVMS operating system.
Naming Conventions
Use the following format to name an OpenVMS Alpha file or an OpenVMS VAX file:
device[directory]filename.type;version
The entire file specification can be a maximum of 255 characters. The file type can be a maximum of 31 characters.
57
OpenVMS
The following table describes the parts of an OpenVMS file name: Part device Description A disk drive name. If the device is not specified, the default provided in the SYSUAF (as defined on the DEC system) for that user is used. Range: 1 to 15 characters. Note: The Unicenter CA-XCOM Data Transport remote USERID field determines the SYSUAF USERID. directory Directory and subdirectory information. If this information is not provided, defaults will be selected as described under device above. Note: Unicenter CA-XCOM Data Transport accepts angle brackets (< >) in OpenVMS file names, which are converted to square brackets on the DEC computer. Example PLAYERS1:<BRIDGE>CARD.DAT is treated as equivalent to PLAYERS1:[BRIDGE]CARD.DAT filename.type version The specific file within the directory. OpenVMS null file names are used if the file name and type are not provided. The version of the file. The OpenVMS operating system can keep multiple versions of a file each time that file is saved. It is normal to omit this number to indicate that you want the most recent version of a file, the highest version number.
For further information on OpenVMS file specifications, see the OpenVMS documentation.
Restrictions
The following restrictions apply to Unicenter CA-XCOM Data Transport for OpenVMS Alpha and Unicenter CA-XCOM Data Transport for OpenVMS VAX: Specifying transfer typeAll transfers must be TYPE=SCHEDULE (for batch) or QUEUED (from ISPF). Non-queued host transfersDue to restrictions in the DEC SNA software, the z/OS TYPE=EXECUTE (non-queued) transfer feature fails with an 8003 sense code. It is not supported by Unicenter CA-XCOM Data Transport to an OpenVMS system.
58
User Guide
OpenVMS
Operating systemUnicenter CA-XCOM Data Transport currently supports the OpenVMS Alpha and OpenVMS VAX operating systems. The Unicenter CA-XCOM Data Transport guides frequently abbreviate the name of this operating system as VAX. This is not meant to imply support for UNIX. ConnectivityThe DECNET/SNA software is based on the Physical Unit 2.0 standard and not on the more flexible 2.1. This means that the system must be connected to a VTAM (PU 5) system in an SNA network. Unicenter CA-XCOM Data Transport uses the store-and-forward function, described previously as an additional z/OS, VM, and VSE feature, to transfer files with other Unicenter CA-XCOM Data Transport partners. Multiple session configurationDigital does not support parallel sessions with a z/OS system. However, if three file transfers are needed concurrently with an OpenVMS system, it does allow you to define three APPC logical units as a group. A group name can be from one to eight characters. The first character must be alphabetic, while the rest can be any combination of alphanumeric or national characters. Try to use mnemonic names. This feature is useful for assigning nicknames as well. The following example calls three logical units, LUD1, LUD2, and LUD3, and assigns them a group name of LAVAX. Code the GROUP and LU parameters for this #PSOTAB entry as follows: GROUP=LAVAX, LU=(LUD1,LUD2,LUD3) Type LAVAX as the remote system name to schedule transmissions to this VAX through the menu interface. When using the batch interface, use the GROUP parameter instead of the LU parameter. Use the following code: GROUP=LAVAX Groups can be used with all the Unicenter CA-XCOM Data Transport interfaces, including the Process SYSOUT Interface. Initiating the session bind requestAlthough separate VTAM LU names can be used for Unicenter CA-XCOM Data Transport sessions, you should not LOGAPPL these LUs to Unicenter CA-XCOM Data Transport when configuring on z/OS or VM. This will fail with an 0801 or 8003 sense code since the DEC software must initiate the session bind request. Compression optionsPack options are not supported. Only COMPRESS=YES is supported for compression for versions prior to version 3.0. ASCII-basedThe OpenVMS platform is an ASCII-based system.
59
OS/2
OS/2
This section contains information about important aspects of the OS/2 operating system.
Naming Conventions
OS/2 supports the FAT file system as well as the High Performance File System (HPFS). This section addresses the HPFS format. Use the following format to name an OS/2 file in the HPFS format:
d:\[directory name]\[..]\filename
Note: Unicenter CA-XCOM Data Transport for OS/2 does not support the transfer of extended attributes. The following table defines the parts of an HPFS file name for OS/2: Part d: Description A particular device. The C drive is the most common local hard drive, and the F drive is the most common network drive. PCs also support a facility in which a section of memory (RAM) can be used as a virtual disk drive. In high-speed link environments, the performance of Unicenter CA-XCOM Data Transport is directly related to the speed of the disk drive. In most environments, the fastest to the slowest devices are as follows: RAM disks (D drive) Directly connected hard disks (C drive) Network disks (F drive) If you do not specify a drive, the default (current) drive is used.
510
User Guide
OS/2
Description One or more optional directories, allowing you to organize the drive. Range: Up to 254 characters, including an optional extension (like a file). If you do not specify a directory, the default (current) directory is used. Note: If you specify a destination file name in a directory that does not exist, Unicenter CA-XCOM Data Transport for OS/2 creates the directory for you. See the target systems configuration to determine if this option has been set.
filename
Required. The name of the data file. Range: 1 to 254 characters. Separate components of the name with periods. Note: Executable binary files end with the extension .EXE, while executable batch files end with .CMD.
Restrictions
The following restrictions apply to CA-XCOM for OS/2: APPC limitationsDue to the vast number of vendor APPCs and link types supported by Unicenter CA-XCOM Data Transport, consult the APPC vendors manual for restrictions on the services provided by that vendor. These restrictions may impact such features as z/OS TYPE=EXECUTE transfers, environments that you can or cannot send to, etc. No library transfersUnicenter CA-XCOM Data Transport for OS/2 Version 2 does not support library transfers from z/OS mainframes. No extended attributesUnicenter CA-XCOM Data Transport for OS/2 does not support the transfer of extended attributes. Packing optionsVersions of Unicenter CA-XCOM Data Transport for OS/2 prior to Version 3.0 do not support some of the various packing options available on other Unicenter CA-XCOM Data Transport systems. For example, they do not support the UNIX or Linux packing option carriage_flag=MPACK.
511
Stratus
Stratus
This section contains information about important aspects of the Stratus operating system.
Naming Conventions
Use the following format to name Stratus files:
#top_directory>group_directory>home_directory>filename.suffix
All names must be unique to that level. The following table describes the parts of a Stratus file name: Part top_directory Description The physical disk(s). Range: 1 to 32 characters. group_directory A group of user home directories. Range: 1 to 32 characters. home_directory The users home directory. This directory resides in a group directory. Range: 1 to 32 characters. filename Required. The name of the Stratus file. Range: 1 to 32 characters. suffix A file classification. You can have multiple suffixes at the end of a file name. Each suffix starts with a period. The following table describes some common Stratus suffixes: File type source object list error program module Suffixes .pl1, .cobol, .c .obj .list .error .pm Examples payroll.c, application.cobol payroll.obj, application.obj payroll.list, application.list payroll.error, application.error payroll.pm, application.pm
512
User Guide
Stratus
Part
513
Tandem
Tandem
This section contains information about important aspects of the Tandem operating system.
Naming Conventions
Use the following format to name a Tandem file:
\<system>.<volume>.<subvolume>.<filename>
All of these components are restricted to eight characters, except as indicated below. The following table describes the parts of a Tandem file name: Part system volume subvolume filename Description The system name. Up to seven characters. The disk name. Can be thought of as a directory name. The name of your file.
Example
The following example uses a volume of $CLX12, a subvolume of SCI, and a file name of FILE1:
$CLX12.SCI.FILE1
The Tandem file system is not a tree structure. Each volume.subvolume is independent, that is, it has no subvolumes above or below.
514
User Guide
Tandem
Key-sequenced files (for Replace only)Key-sequenced files are supported only for the Replace operation. The file must already exist for Unicenter CAXCOM Data Transport to perform an action on it.
515
UNIX/Linux
ENTRY_SEQ RELATIVE
Note: Key sequence files are supported only if the file exists. You can do a replace but not a create.
UNIX/Linux
This section contains information about important aspects of the UNIX and Linux operating systems.
Naming Conventions
Use the following format to name a UNIX or Linux file:
/directory/subdirectory/.../filename
Use up to 256 characters for the entire path of the file; there are no restrictions on size for the individual parts of the path.
516
User Guide
VM
The following table describes the parts of a UNIX/Linux path: Part / (slash) directory filename Description The root directory when it is in the first position: otherwise, the slash separates directories and file names in the path. The directory that contains the file. You can specify more than one directory in a path. The name of the UNIX or Linux file.
VM
This section contains information about important aspects of the VM operating system.
Naming Conventions
Use the following format to name VM files under the CMS operating system:
filename.filetype
The two parts can be a maximum of eight characters in length. They can consist of letters, numbers, and/or national characters ($, #, @, +, -, :, _). In general, lowercase letters are not allowed. In the Unicenter CA-XCOM Data Transport for VM parameters FILE and LFILE, the file name and file type are specified as one string with a period as a separator. For minidisk specifications:
CP OWNER is taken from the volume field, if present. Otherwise, the userid field is used. CP address is taken from the unit specification. The default is 191.
Note: You may have two files with the same file name and file type, but they cannot reside on the same minidisk.
517
VM
DCB Information
CMS file characteristics must be predetermined when creating a new file. You must specify the following parameters: Record formatThis can be fixed (F) or variable (V). Logical record lengthThis is the number of characters in the longest line of the file.
Restriction
The following table lists the maximum logical record lengths for different file types: File type Disk file Job (RDR file) Report (PRT file) Maximum logical record length 32767 bytes 80 bytes 133 bytes
518
User Guide
VSE
VSE
This section contains information about important aspects of the VCE operating system.
The following table describes the parts of a VSAM file name: Part file-id Description The name given to the data set when it was defined using IDCAMS by including the following line in the JCL:
DEFINE CLUSTER (NAME (file-id)...
V catalog-id
Indicates that this is a VSAM file. Optional. The name of the user catalog that owns the VSAM data set as defined using IDCAMS by including the following line in the JCL:
DEFINE USERCATALOG (NAME (catalog-id)...
Leave this field blank if the data set is owned by the master catalog.
519
VSE
The following table describes the parts of a SAM file name: Part file-id Description The name that identifies this data set in the VTOC of the specific DASD volume. This is the file-id you specify on the DLBL JCL statement. Range: 1 to 44 characters Note: Do not enclose it in quotes. S unit Indicates that this is a SAM file. The physical device address as defined by the CUU parameter on the ASSGN JCL statement. It identifies the disk drive on which this file resides. This parameter can be omitted if the UNIT or VOL parameters are specified, or if a DASD manager is in use. Optional for output files. The starting location of the file on the disk, as defined on the EXTENT JCL statement. If a DASD manager is in use, specify a value of 1. size Optional for output files. Indicates how much space this data set will use, as defined on the EXTENT JCL statement. For CKD devices, this is the number of tracks. For FBA devices, this is the number of blocks.
location
520
User Guide
VSE
Part override
Description Optional for output files. Indicates whether this file should be processed as if the FLLTAB option for DASDM were coded as indicated by the override parameter. The override applies only to the processing for the file whose data set name is on the statement that the statement where the override appears. The following are the available override parameters and their equivalent DFLTAB option: 1. 2. 3. DMYES to force DASDM=YES for this file. DMNO to force DASDM=NO for this file DMEPIC to force DADSM=EPIC for this file.
Note: If you are running with a DASD manager, the DASD managers STRTTRK or Trigger value is placed in the location field. DASD manager pools should be indicated by putting the pool name in the Volume parameter. For EPIC/VSE users, you can omit the following: The location if you want EPIC to default to its STRTTRK value The size if you want EPIC to default to its DEFEXT value The Volume information if you want EPIC to default to its DEFPOL value For CA-Dynam users who want to access Dynam catalog controlled files (included GDG data sets), no extent information should be entered (no cuu, location, size, or override information and no Volume or Unit parameters for the files you are referencing).
521
VSE
The following table describes the parts of a TAPE file name: Part file-id Description The name that identifies this data set in the tape manager catalog or in the HDR1 label on the tape. This is the file ID you specify on the TLBL JCL statement. Range: 1 to 44 characters. Note: When the file ID contains imbedded spaces or commas, it should be enclosed in quotes. Note: IBM only supports a 17-character file ID in a tape header label. If you have a tape manager, 44-character tape file IDs may be supported. Unicenter CA-XCOM Data Transport does not validate your file ID, but takes whatever you put on the statement and passes it along to IBMs OPEN routine or to your tape manager as you have entered it. T Indicates that this is a TAPE file. Note: If you enter a transfer request from a platform that has not yet implemented the extended tape processing parameters or menu interface fields for controlling tape processing to a Unicenter CA-XCOM Data Transport/VSE server, you must use the T option. You are restricted to standard label tape processing.
522
User Guide
VSE
Part unit
Description The physical device address as defined by the CUU parameter on the ASSGN JCL statement. If you are using TAPEM=YES|EPIC, Unicenter CA-XCOM Data Transport ignores any units coded and the tape manager does the tape AVR and assignment. If you are not using the tape manager, the primary assignment is made to the first unit Unicenter CA-XCOM Data Transport finds. Other units found are assigned as temporary alternates. This parameter can be omitted if you prefer to use the UNIT parameter to specify a unit or two units (primary and alternate). This parameter can be used in conjunction with the UNIT parameter to specify a primary unit and up to four alternate units that will be assigned by Unicenter CA-XCOM Data Transport prior to open. Units specified on the statement containing the file-id will be assigned before units specified on the UNIT parameter. The unit parameter is ignored because tape processing is only supported when you have a tape manager on your VSE system.
override
Optional for output files. Indicates whether this file should be processed as if the DFLTAB option for TAPEM were coded as indicated by the override parameter. The following are the available override parameters and their equivalent DFLTAB option:
TMYES to force TAPEM=YES for this file TMNO to force TAPEM=NO for this file TMEPIC to force TAPEM=EPIC for this file
Note: The override applies only to the processing for the file whose data set name is on the statement that the override appears on. It is in effect for this transfer only.
DTF Information
VSE file characteristics must be predetermined when creating the files. If sending to or receiving from a VSE system you must specify the following: The record format (RECFM), which can be either fixed (F), fixed blocked (FB), variable (V), or variable blocked (VB). The logical record length (LRECL) indicates the number of characters in the longest record in the file. The block size (BLKSIZE), which can be either equal to the LRECL for fixed files, a multiple of the LRECL for fixed blocked files, the LRECL +4 for variable files, or the BLKSIZE +4 for variable blocked files.
523
VSE
Restrictions
The following restrictions apply to Unicenter CA-XCOM Data Transport for VSE: No FILEOPT=ADD for receiving VSEUnicenter CA-XCOM Data Transport for VSE does not support FILEOPT=ADD if the VSE is receiving the file. No Checkpoint/Restart for SAMUnicenter CA-XCOM Data Transport for VSE does not support checkpoint/restart for SAM jobs.
524
User Guide
Naming Conventions
Unicenter CA-XCOM Data Transport for Windows only supports the FAT file system. Use the following format to name Windows files:
d:\[directory name]\..\filename.[ext]
The following table describes the parts of a Windows file name: Part d Description A particular device. The C drive is the most common local hard drive, the A drive is the most common floppy, and the F drive is the most common network drive. PCs support a facility in which a section of memory (RAM) can also be used as a virtual disk drive. In high-speed link environments, the performance of Unicenter CA-XCOM Data Transport is directly related to the speed of the disk drive. In most environments, the fastest to the slowest devices are as follows: RAM disks (D drive) Directly connected hard disks (C drive) Network disks (F drive) Floppy disks (A or B drive) Note: If you do not specify a drive, the default drive, that is, the current drive, is used. This directory in Windows changes, depending on the last application accessed. directory name One or more optional directories, which allow you to assign organization to the drive. Range: 1 to eight characters with an optional 3-character extension (like a file). If you specify a destination file name with a directory that does not exist, Unicenter CA-XCOM Data Transport for Windows creates the directory for you. Note: If you do not specify a directory, the default directory, that is, the current directory, is used.
525
Part filename
Description Required. The name of the data file. Range: 1 to 8 characters (characters past position eight generate an error).
ext
The file extension used to further identify the file. Executable programs must use the extension .EXE or .COM. Range: 1 to 3 characters. Note: If you do not specify an extension, Unicenter CA-XCOM Data Transport does not supply a default.
Restrictions
The following restriction applies to Unicenter CA-XCOM Data Transport for Windows: APPC restrictionsDue to the vast number of vendor APPCs and link types supported by Unicenter CA-XCOM Data Transport, consult the APPC vendors manual for restrictions on the services provided by that vendor. These restrictions may impact such features as z/OS TYPE=EXECUTE transfers and environments to which you can send. Note: This is a single-user system. Do not send multiple simultaneous transfers to this partner.
526
User Guide
Naming Conventions
Unicenter CA-XCOM Data Transport for Windows NT supports the standard Windows NT file names and the Universal Naming Convention (UNC). The file naming conventions for Windows NT are similar to those for Windows, with some significant differences, some of which are outlined below. Use the following format to name files when using standard Windows NT file names:
d:[\][directory name\..\]filename[.ext]
Use the following format to name files when using UNC file names:
\\server name\share name\directory\filename
527
The following table describes the parts of Windows NT file names and UNC file names: Part d directory name Description Required. A particular device, indicated as a drive letter. Required. One or more optional directories and subdirectories. Subdirectories can take the form of name[.ext]. Note: The form of the directory name and file name depend on the operating system running on the server. filename Required. The name of the data file. For FAT file systems, filename is 1 to 8 characters. NTFS and HPFS file systems support long file names, up to 256 characters, including the extension. Names may or may not be case sensitive, depending on the file system on the server. For FAT, NTFS, and HPFS, names are not case sensitive. You can use uppercase and lowercase when creating a name, and they will display as typed, but internally Windows NT makes no distinction for this. For example, Windows NT would consider MYFILE and MyFiLe as references to the same file. Windows NT also creates an MS-DOS-style name based on the long name for compatibility with environments where long file names are not always supported. ext The file extension used to further identify the file. For FAT file systems, the extension is up to 3 characters. For NTFS and HPFS, the extension is included in the long file name limit of 256 characters. Note: If you do not specify an extension, Unicenter CA-XCOM Data Transport does not supply a default. server name share name The name of the server. The share name is network provider dependent. For Microsoft Windows networks this is the name of the share. For NetWare networks this is the name of the volume.
528
User Guide
Additional Features
Additional features include the following:
File Systems
The standard Windows NT file systems are: File Allocation Table format (FAT) Windows NT File System format (NTFS) High-performance File System format (HPFS)
File Access
Unicenter CA-XCOM Data Transport accesses files locally or from any file server on the Microsoft Windows Network or the NetWare or Compatible Network, or any other network provider installed on the Windows NT system. For transfers to Windows NT systems running any release of Unicenter CA-XCOM Data Transport, the following apply:
Security
Windows NT is a secured system, because Windows NT requires a valid user ID and password (as defined when setting up a user account under NT) in order to log into or connect to an NT server. User IDs and passwords are case sensitive. Unicenter CA-XCOM Data Transport uses the underlying NT security system to log into the server as the user defined in the XCOM_USERID parameter. The authority to logon locally is required because there is no facility in Unicenter CA-XCOM Data Transport for Windows NT to allow for another domain to be specified. When a transfer is sent from another system (such as z/OS), USERID and PASSWORD must be supplied. The following methods model sending transfers from a Unicenter CA-XCOM Data Transport for z/OS system to a local Windows NT drive.
Methods of handling NT systems security from Unicenter CA-XCOM Data Transport are as follows:
Employing some security All users employ the same user ID. Set XCOM_USERID and XCOM_PASSWORD= to a valid NT user ID and password that has local logon authority in the xcom.glb file on the NT side. On the z/OS side, send a transfer with parameter USERID=' ' (blank between two single quotes). This will use the user ID and password from the xcom.glb file.
529
Employing user level securityUsers employ their own user ID and password. Set XCOM_USERID and XCOM_PASSWORD= to an INVALID NT user ID and password in the xcom.glb file on the Windows NT side. On the z/OS side, send a transfer with parameters USERID= and PASSWORD= with a valid NT user ID that has local logon authority. This causes Unicenter CAXCOM Data Transport to use the user ID and password supplied. If a password is not supplied, and xcom.glb is checked, the transfer will fail due to the invalid ID and password in the xcom.glb file on the NT side.
Note: If either of these methods is to be successful, in the case where Unicenter CA-XCOM Data Transport for z/OS is sending to Unicenter CA-XCOM Data Transport for Windows NT, the Unicenter CA-XCOM Data Transport for z/OS default table MUST have USEROVR=YES. USEROVR=YES is the default. This allows the user ID in the MVS JCL to override the batch job ID. For information about the USEROVR parameter, see the Unicenter CA-XCOM Data Transport for z/OS Administrator Guide.
Home Directory
A Windows NT user can have a default home directory assigned by the Windows NT administrator.
Unicenter CA-XCOM Data Transport limits the length of this field as indicated below. The actual name on the destination system may be longer. Type of transfer Direct transfers using Version 2 protocols. Indirect transfers or transfers using Version 1 protocols. Specify Up to 21 characters. Up to 16 characters.
530
User Guide
Restrictions
Access to directories and files on drives formatted for NTFS can be controlled with the security features of Windows NT Version 3.51 or higher. Access to all files on a Windows NT system can be controlled by the permissions set on a directory or file. The access rights of the user ID on the remote system determine the actions permitted for the transfer. Users cannot use a directory or file unless they have been granted the appropriate permissions.
531
Chapter
61
Setting Expiration
Setting Expiration
When generating a CA certificate, the default_days parameter in cassl.conf that controls the expiration of server and client certificates is not used for CA certificates. The certificate is generated with a default expiration of 30 days. Use the following procedure to change the default expiration: 1. Add days nnn to the makeca script line. The following line is an example of how the makeca script is shipped:
Openssl req x509 newkey rsa out ./certs/cassl.pem outform PEM
2.
To change the expiration to one year, change the line before running the makeca script:
Openssl req x509 newkey rsa out ./certs/cassl.pem outform PEM days 365
This shell script uses the cassl.conf file to generate a certificate and key file. The certificate, cassl.pem, is saved in the certs subdirectory. The key file, generated as casslkey.pem, is saved in the private subdirectory. Note: When running the makeca script the first time, the pseudo-random number generator (PRNG) file does not exist and issues a warning to this effect. The makeca utility generates the PRNG file the first time it is run and does not issue this warning on subsequent executions. This is only a warning; you can continue with the next step. 3. To list the certificate just created, issue the following command to use the listca script:
./listca
62
User Guide
This shell script displays the CA certificate and the information stored in the package.
2.
The makeserver shell script uses the serverssl.conf file and the cassl.pem file to generate a server certificate and a key file. The server certificate, servercert.pem, is saved in the certs subdirectory. The key file, generated as serverkey.pem, is saved in the private subdirectory. 3. To list the certificate just created, issue the following command to use the listserver script:
./listserver
This shell script displays the server certificate and information stored in the package.
The makeclient shell script uses the clientssl.conf file and the cassl.pem file to generate a client certificate and a key file. The certificate, clientcert.pem, is saved in the certs subdirectory. The key file, generated as clientkey.pem, is saved in the private subdirectory.
63
To list the certificate just created, issue the following command to use the listclient script:
./listclient
The listclient shell script displays the client certificate and information stored in the package.
2.
For z/OS, specify the TCP/IP port that will accept SSL connection requests using the SSLPORT default options table parameter. In addition, the default options table parameter, SSL, must also be set to one of the following values: ONLYto allow incoming SSL transfers only ALLOWto allow both incoming SSL and incoming non-SSL transfers to this server
For UNIX, during installation, manually add the txpis service and the TCP/IP port that will accept SSL connection requests to the inetd configuration files. For Windows, specify the TCP/IP port that that will accept SSL connection requests using the SSL Port Number on the TCP/IP tab in the Global Parameters GUI.
4.
Verify that the port that receives incoming SSL connections is a unique port that is not in use by any other application. The port used for incoming TCP/IP connections cannot also be used for incoming SSL connections. If Unicenter CA-XCOM Data Transport will be receiving both incoming TCP/IP connections and incoming SSL connections, then two ports are required.
64
User Guide
For z/OS, reassemble the default options table and restart the Unicenter CA-XCOM Data Transport server (started task). For UNIX and Windows, restart the Unicenter CA-XCOM Data Transport service.
2.
For z/OS, the XCOM_CONFIG_SSL parameter can also be specified as a destination member parameter. For UNIX and Windows, the XCOM_CONFIG_SSL parameter can also be specified in your configuration (cnf) file. For z/OS, specify the SECURE_SOCKET parameter in the SYSIN01, the destination member, or the default options table. For UNIX and Windows, specify the SECURE_SOCKET parameter in the configuration (cnf) file.
3.
4.
Specify the port through which the remote Unicenter CA-XCOM Data Transport partner accepts SSL connections. Use one of the following parameters:
5.
65
Appendix
Parameters
Use parameter values to control the variables that govern the behavior of Unicenter CA-XCOM Data Transport.
xcom.cnf or filename.cnf
xcom.glb
Program defaults
Parameters
A1
Parameter Format
When using Unicenter CA-XCOM Data Transport from the command prompt or with a script, and when editing configuration files, the Unicenter CA-XCOM Data Transport parameters consist of assignment statements. The format for assignment statements is as follows:
PARAMETER_NAME (always all uppercase, with underscore character (_) when indicated) An equal sign (=) A character string terminated by a new-line
Note: Parameter values are always in uppercase. However, when specifying directories, file names, user IDs and passwords, you may use uppercase and lowercase.
Syntax
The syntax for assignment statements is as follows:
PARAMETER_NAME=value
Example
In the following example, the parameter EXPIRATION_TIME is set to a value of 6000 seconds.
EXPIRATION_TIME=6000
This controls the maximum time in seconds that a transaction is held in the transfer queue after execution.
Guidelines
Note the following guidelines for using Unicenter CA-XCOM Data Transport parameters:
When you type trailing spaces and tabs from the command line as part of a parameter value, they are stripped by the command line processor (the shell). When you type trailing spaces and tabs into a file or script with an editor, such as vi, they are treated as part of a parameter value. These trailing spaces and tabs should be removed. If they are not removed they can cause confusion and unpredictable or undesirable results. Empty lines and lines beginning with a pound sign (#) are discarded.
A2
User Guide
List of Parameters
Examples In the following examples, the spacespacespace represents trailing spaces. If you type the following at the command line, the trailing spaces are ignored:
xcom62 -c1 LOCAL_FILE=xyzspacespacespace
If you type the following into any configuration file using an editor, the spacespacespace would be treated as part of the name of the LOCAL_FILE.
LOCAL_FILE=xyzspacespacespace
List of Parameters
The following is a full list of parameters for Unicenter CA-XCOM Data Transport for UNIX and Linux. The default values listed here are based on the defaults as supplied in the sample files xcom.glb and xcom.cnf that come with Unicenter CA-XCOM Data Transport. Any defaults not specified by these files come from the programs own defaults.
AGE_TIME
The number of seconds before waiting queue entries are removed from queue. If the value is 0, the waiting queue entries never age and are never removed from the queue. Range: 0 to 86313600 (999 days) Default: 432000 (5 days)
Parameters
A3
List of Parameters
ALLOCATION_TYPE
Indicates the unit of storage allocation for a dataset created on an IBM mainframe. Range: The range of values is listed in the following table: Value CYL TRK BLK Description Cylinders Tracks Blocks
ATOE_FILENAME
The name of the file containing the ASCII-to-EBCDIC character conversion table. This is a custom file used only for specifying custom translation tables from ASCII to EBCDIC, if needed. Range: 0 to 256 characters Default: /usr/spool/xcom/convtab/atoe.tab, except for the following:
BLKSIZE
Specifies the block size of a dataset created on an IBM mainframe. Note: Used when FILE_OPTION=CREATE. Range: 0 to 32767 If the record format is Fixed or fixed block Variable Undefined
Default: 800
Then the block size must be A multiple of the record length 4 bytes larger than the record length Larger than the largest record length
A4
User Guide
List of Parameters
CARRIAGE_CONTROL_CHARACTERS
Indicates the type of printer carriage-control codes, if any, that are included in the report file. Note: For report transfers only. Range: The range of values is listed in the following table: Value ASA IBM BYPASSASA OTHER
Default: OTHER
Description ASA control codes in column 1. IBM Machine Characters (valid only for IBM mainframes). If data is already in ASA format, bypass conversion. No carriage-control codes are used.
CARRIAGE_FLAG
Specifies the type of file being transferred and some special characteristics of the conversion done during the transfer. Range: The range of values is listed in the following table: Value YES Description Indicates that the transferred file is a text file and a newline character should be added to the end of incoming records. Also, newline characters are removed from the ends of lines before an outgoing record is sent. Indicates no special processing. Indicates a text file with record packing. Uses 2K pack buffer. Indicates a binary file of variable-length records with a field of 4 bytes preceding each record. Applies to local initiated transfers only. Indicates a binary file of variable-length records with a field of 8 bytes preceding each record. Applies to local initiated transfers only. Used for certain applications that require an MVS-style BDW and RDW preceding each record. Indicates a text file with record packing. Uses 31K pack buffer.
NO MPACK VLR
VLR2
XPACK
Parameters
A5
List of Parameters
Note: MPACK does not support a MAXRECLEN (actual record length) over 2K. XPACK does not support a MAXRECLEN (actual record length) over 31K.
Default: YES
CHECKPOINT_COUNT
Defines how often (based on record count) the sending system requests a checkpoint to be taken. The value 0000 indicates no checkpointing. Range: 0 to 9999 Default: 1000 Note: Version 2 parameter.
CLASS
The print class assigned to a report transferred to a remote system. If the remote system is an IBM mainframe, this field designates the JES SYSOUT class. Note: For report transfers only.
Example
Enter B to print the report through SYSOUT=B. Range: 1 character Default: None
CODE_FLAG
Used to identify the type of data being transferred. Range: The range of values is listed in the following table: Value ASCII Description An ASCII file is being transferred. This indicates that the incoming file is assumed to be ASCII format, and is not translated. Therefore the file on the remote system should be in ASCII format before it is transferred. A binary file, such as an executable file, is being transferred. This indicates to a remote system that it is not to translate the data it is exchanging with your system.
BINARY
A6
User Guide
List of Parameters
Value EBCDIC
Description An EBCDIC file is being transferred. The transferred data is translated from EBCDIC to ASCII format when the local system receives the data, and from ASCII to EBCDIC format when the local system sends the data.
Default: ASCII
CODETABL
Specifies the prefix to the file names, atoe.tab and etoa.tab, that contain the external ASCII-to-EBCDIC and EBCDIC-to-ASCII custom character conversion tables. These custom character conversion tables determine which external translation tables will be used by the transfer. This parameter is valid only if INTERNAL_CONVERSION_TABLES=NO. Range: 0 to 3 alphanumeric characters Default: None
COMPRESS
Indicates the compression type. When communicating with an IBM mainframe, if the data file contains any empty lines, COMPRESS can only be set to YES, LZSMALL, LZMEDIUM or LZLARGE. Note: All compression types are not supported on all platforms. For supported compression types, see the partner platform documentation. Range: The range of values is listed in the following table: Value COMPACT LCOMPACT LZLARGE LZMEDIUM LZRW3 Description RJE compaction algorithm optimized for uppercase English text. RJE compaction algorithm optimized for lowercase English text. Activates LZ compression to search back 32K in the datastream for a matching string. Activates LZ compression to search back 16K in the datastream for a matching string. General-purpose algorithm that runs fast and gives reasonable compression.
Parameters
A7
List of Parameters
Description Activates LZ compression to search back 4K in the datastream for a matching string. Indicates no compression. Run length encoding. Indicates run length encoding of binary zeros and blanks only. Greater compression than LZRW3 but less than LZSMALL, LZMEDIUM, and LZLARGE. The n value can be 1 to 9.
Note: The LZ values enable LZ (Lempel-Ziv) compression to replace sequences of data bytes that occur more than once in a datastream with a code value.
Default: YES
CONTROL
For multiple transfers. Use the syntax for performing a single transfer and then separate parameters for different transfers in the same configuration file by using this parameter. Range: NEWXFER or NONE Default: NEWXFER
CONVERT_CLASSES
A character string containing print classes for which EBCDIC-to-ASCII conversions will be performed. For incoming report transfers only. Range: 1 to 64 characters Default: None
COPIES
The number of copies that are to be sent. If this parameter is not specified, the remote system queues one copy of the report to the systems default printer. For report transfers only. Range: 1 to 999 Default: 1
A8
User Guide
List of Parameters
CREATE_DIR
Indicates whether to create the specified directory if it does not exist. Range: The range of values is listed in the following table: Value YES NO Default: YES Description Create the directory if it does not exist. Do not create the directory if it does not exist.
DATACLAS
Specifies the name of the data class to use when allocating a new SMS-managed data set. Note: This parameter applies only to mainframe SMS data sets. Range: 1 to 8 characters Default: None
DEBUG_FLAG
Specifies whether a trace will be output to the file /tmp/<tid> instead of to the default path /usr/spool/xcom/trace/<tid>.TRA. In addition to the transfer trace information, the initialization will also be traced. The trace level is still taken from the variable XTRACE. Note: The <tid> variable refers to the 6-digit transfer ID number. Range: The range of values is listed in the following table: Value YES NO Description The trace is output to /tmp/<tid> The trace is output to /usr/spool/xcom/trace/<tid>.TRA. For HP-UX systems: /var/spool/xcom/trace/<tid>.TRA For OSF Digital UNIX systems: /var/opt/xcom/trace/<tid>.TRA.
Default: NO
Parameters
A9
List of Parameters
DEN
Specifies the density to be used in creating a tape on the remote system. Valid values are the same as those for the DEN parameter in JCL. Range: 1 to 4 Default: None
DESTINATION
Identifies the printer or other device on the remote system where the report is to be sent. If this parameter is not specified, the remote system sends the report to the system's default printer. For report transfers only. Range: The range of values is listed in the following table: Value 0 to 16 characters 0 to 21 characters
Default: None
Description For indirect transfers and for Version 1. For transfers that are not indirect and for Version 2.
DESTINATION_TYPE
The type of target system. Range: HOST, MIDRANGE, or OTHER Default: OTHER
DISPLAY_PASSWORD_IN_TRACE
Determines if Unicenter CA-XCOM Data Transport displays password information in the trace files. Range: The range of values is listed in the following table: Value YES ENCRYPT Description Encrypted and plain text passwords are displayed in the trace files. Encrypted passwords are displayed in the trace files.
A10
User Guide
List of Parameters
Value NO
Default: NO
DISPOSITION
Indicates what the remote system does with the report file after the report has been printed. For report transfers only. Note: This field is not used when the remote system is an IBM mainframe. Range: The range of values is listed in the following table: If the value is DELETE KEEP HOLD
Default: DELETE
DOMAIN
The Windows domain name for use in authenticating the user ID and password when accessing a Windows based machine that has sharable disks and drives that belong to that domain. This allows users to access these sharable drives without having to have a local user ID or password defined to the machine. Range: 1 to 15 characters Default: None
DSNTYPE
Specifies the data set definition. Note: This parameter applies only to mainframe SMS data sets. Value LIBRARY PDS Description Defines a PDSE Defines a partitioned data set
Parameters
A11
List of Parameters
Note: These values are IBM standards for SMS processing. Range: 1 to 8 characters Default: None
EOL_CLASSES
A character string containing print classes for which an ASCII newline character will be appended to each record. For incoming report transfers only. Range: 1 to 64 characters Default: None
ETOA_FILENAME
The name of the file containing the EBCDIC-to-ASCII character conversion table. This is a custom file used only for specifying custom translation tables from EBCDIC to ASCII, if needed. Range: 1 to 256 characters Default: /usr/spool/xcom/convtab/etoa.tab, except for the following:
EXPDT
Specifies an expiration date for the tape data set in terms of a two-digit designation for the year and a three-digit designation for the day of the year. For example, in the expiration date 02021, 02 is the year (namely, 2002) and 021 is the 21st day of that year when the tape data set expires. For example, if 02021 is an expiration date, 2002 is the year and 021 is the 21st day of the year. Format: yyddd Default: None Note: EXPDT and RETPD are mutually exclusive; specify one or the other.
A12
User Guide
List of Parameters
EXPIRATION_TIME
The maximum time, in seconds, that a transaction is held in the transfer queue after completion. When the maximum time is reached, all references to the transaction are removed from the queue, including trace files and temporary files. Note: If EXPIRATION_TIME is set to no value in xcom.glb, the program default of 6000 is used. Range: 0 to 32767 Default: 6000
FCB
Identifies the FCB JCL parameter when sending the report file to an IBM mainframe, defining print density, lines per page, and so on. For report transfers only. Range: 0 to 4 characters Default: None
FILE_OPTION
Indicates how the transferred data is to be processed by the receiving system. For file transfers only. Range: The range of values is listed in the following table: Value CREATE APPEND REPLACE Description Create a new file on the receiving system. Append the transferred data to an existing file on the receiving system. Replace an existing file on the receiving system.
Parameters
A13
List of Parameters
For wildcard transfers: Value CREATE APPEND Description Create the PDS/Directory and add the transferred members. If the PDS/Directory already exists, the transfer fails with an error. Add transferred members/files. If the PDS/Directory does not exist or the member/file already exists, the transfer fails with an error. Add or replace transferred members/files. If the PDS/Directory does not exist, The transfer fails with error XCOMN0403E Cannot open output fileNo such file or directory.
REPLACE
Default: CREATE
Note: When creating a file on an IBM mainframe system, some additional information may be necessary. For more information, see the RECORD_FORMAT, BLKSIZE, VOLUME, and UNIT parameters.
FILE_OPTION_RF
Indicates how the transferred data is to be processed by the receiving system (that is, the local system). Used when the transfer type is Retrieve File. If a value is not specified, then the value of FILE_OPTION is used. If no default is specified in FILE_OPTION or FILE_OPTION_RF, then the value defaults to CREATE. Range: The range of values is listed in the following table: Value CREATE APPEND REPLACE Description Create a new file on the receiving system. Append the transferred data to an existing file on the receiving system. Replace an existing file on the receiving system.
For wildcard transfers: Value CREATE APPEND Description Create the PDS/Directory and add the transferred members. If the PDS/Directory already exists, the transfer fails with an error. Add transferred members/files. If the PDS/Directory does not exist or the member/file already exists, the transfer fails with an error.
A14
User Guide
List of Parameters
Value REPLACE
Description Add or replace transferred members/files. If the PDS/Directory does not exist, The transfer fails with error XCOMN0403E Cannot open output fileNo such file or directory.
Default: CREATE
FORM
The type of form that should be used to print the report. Since Unicenter CA-XCOM Data Transport places the print job in the remote system's print queue, the print control functions depend on the remote system. The user must verify beforehand that the requested form is available at the remote site. For report transfers only. Note: When sending a report to a VAX computer, leave this parameter blank unless you are certain that this is a valid form type. VMS interprets this to mean that no special form is being requested. Range: 0 to 10 characters Default: None
HOLDFLAG
Indicates whether a transferred report file is to be placed on HOLD on the remote system or is to be printed immediately. For report transfers only. Range: YES or NO Default: NO
INTERNAL_CONVERSION_TABLES
Indicates whether internal or external conversion tables should be used for ASCII-to-EBCDIC conversion and EBCDIC-to-ASCII conversion. The external conversion files may be customized to meet your needs. For the appropriate directory and file name, see ATOE_FILENAME and ETOA_FILENAME. Range: The range of values is listed in the following table: Value YES Description Use internal conversion tables.
Parameters
A15
List of Parameters
Value NO
Default: YES
LABEL
Indicates the type of label associated with a tape data set. The following table lists the valid values for this parameter. Value Processing type: AL, AUL, BLP, LTM, NL, NSL, SL, SUL Description Represent the types of processing to be applied to data sets on tape.
Note: Unicenter CA-XCOM Data Transport for z/OS supports only standard label tapes. Example: LABEL=BLP The type of processing to be applied to this data set is BLP. Default: AL
LABELNUM
Indicates the sequence number of the data set on the tape. The following table lists the valid values for this parameter. Value Sequence number (0001 to 9999) Description This value identifies the sequence number of a data set on tape.
Example: LABELNUM=2 This specification refers to the second data set on the tape. Default: 0001
A16
User Guide
List of Parameters
LCLNTFYL
Specifies the local user notification level. Range: The range of values is listed in the following table: Value A or ALL W or WARN E or ERROR Default: ALL Description NOTIFY on transfer completion. NOTIFY only if the transfer received a warning or error. NOTIFY only if the transfer received an error.
LOCAL_FILE
The name of the file on the local system that is being transferred. If this variable is null or unset, standard input is read. In this manner, Unicenter CA-XCOM Data Transport commands can be used in a pipeline or with redirection. All UNIX or Linux file naming conventions apply. For wildcard transfers, use an asterisk as a file name to indicate that all files within the specified directory are to be transferred. For example, the statement "LOCAL_FILE=/NAMES/*" indicates that all files under the NAMES directory are to be transferred. When a prefix is followed by an asterisk (*), all members beginning with a specific prefix are to be transferred. For example, LOCAL_FILE=/NAMES/AL* requests that files AL, ALEX, and ALICE are all to be transferred. The same rules apply if an asterisk is followed by a suffix. The actual file name range (not including its path) for wildcard transfers can be between 0 and 71 characters. This also includes the file extension where applicable. File names over 71 characters are truncated. However, when sending files to a mainframe PDS, any file name over 8 characters in length is truncated. These systems do not recognize file extensions. For example, a file called longfilename.txt will be truncated to longfile and a file called file.txt will be truncated to file. Note: If QUEUE=YES, user must specify full path name. Range: 0 to 256 characters Default: None
Parameters
A17
List of Parameters
LOCAL_FILE_RF
The file name that is created, appended, or replaced on the local system when it receives a file. All UNIX or Linux file naming conventions apply. At the command prompt or in a script, if this value is null or unset, then Unicenter CA-XCOM Data Transport writes to the stdout. For wildcard transfers, use an asterisk (*) as a file name to indicate that multiple files will be received. For example, LOCAL_FILE_RF=/PAYROLL/*. If multiple files are received and the user specifies a file name, all files received by the partner are written to that specified file as one single file. For platforms that support it, you can specify a common file extension to be appended to each file name. For example, LOCAL_FILE_RF=/PAYROLL/*.TXT. Note: If QUEUE=YES, user must specify full path name. Range: 0 to 256 characters Default: None
LOCAL_FILE_SJ
Indicates the name of the file on the local system to be sent as a job. All the UNIX or Linux file naming conventions apply. If this value is null or unset, then Unicenter CA-XCOM Data Transport reads the standard input file. Note: If QUEUE=YES, user must specify full path name. Range: 0 to 256 characters Default: None
LOCAL_FILE_SR
Local file name to be sent as a report to the remote system. If this value is null or unset, then Unicenter CA-XCOM Data Transport reads the standard input file. For report transfers only. Note: If QUEUE=YES, user must specify full path name. Range: 0 to 256 characters Default: None
A18
User Guide
List of Parameters
LOCAL_NOTIFY
Specifies the user on the local system who is to be notified that Unicenter CA-XCOM Data Transport has completed a transfer. Unicenter CA-XCOM Data Transport uses the NOTIFYL parameter to determine the type of notification to use. Range: 0 to 64 characters Default: None
LRECL
Specifies the actual or maximum length, in bytes, of a logical record. Corresponds to the JCL LRECL subparameter. Range: 0 to 32767 If the format is Variable blocked record Fixed or fixed block record
Default: 160
Then the maximum length of a logical record must be equal to the Maximum record length plus 4 Constant record length
MAX_QUEUE_ENTRIES
The maximum number of entries allowed in the transfer queue. Once the maximum number of queue entries is reached, subsequent transfer attempts are rejected by Unicenter CA-XCOM Data Transport. Note: This value depends on the memory available when Unicenter CA-XCOM Data Transport is started. Range: 0 to 32767 Note: The value cannot be set larger than the maximum allowed memory segment divided by 512.
Default: 50
Parameters
A19
List of Parameters
MAX_REMOTE_TCP
The maximum number of simultaneous remote TCP/IP transfers accepted by Unicenter CA-XCOM Data Transport. Transfers received after this limit has been reached are rejected. Note: Setting this parameter to 0 prohibits any remote transfers from taking place. Range: 0 to 999 Default: 32
MAX_SESSIONS_ENTRIES
The maximum number of partners that can be described in the XCOM.SES file. Range: 1 to 999 Default: 15
MAXRECLEN
For Windows NT, UNIX, and Linux systems, the locally initiating Unicenter CA-XCOM Data Transport system determines the values for MAXRECLEN, TRUNCATION, and LRECL, for send and receive operations. When the local Unicenter CA-XCOM Data Transport system initiates a transfer of a text file, this parameter designates the length, in bytes, of the largest record that can be transferred. If a record length is longer than this value, Unicenter CA-XCOM Data Transport uses the value in the TRUNCATION parameter on the initiating side to determine whether to terminate the transfer or to truncate the record and continue the transfer. When Unicenter CA-XCOM Data Transport transfers binary files, this value indicates the length of the records that are transferred. On a receive operation, MAXRECLEN is set to whatever the LRECL value is on the initiating side. Range: 1 to 32767 Default: 1024
METACODE_CLASSES
Classes of print jobs that will be saved in metacode format, a variable length record format. For incoming report transfers only. Range: 0 to 64 characters Default: None
A20
User Guide
List of Parameters
MGMTCLAS
Specifies the name of the management class to use when allocating a new SMS-managed data set. Note: This parameter applies only to mainframe SMS data sets. Range: 1 to 8 characters Default: None
NOTIFY_NAME
The user on the remote system who is to be notified when Unicenter CA-XCOM Data Transport completes a transfer. Note: If the remote system is an IBM mainframe, Unicenter CA-XCOM Data Transport uses the value of NOTIFYR to determine the type of notification to deliver. If the remote system is a UNIX or Linux system, the user receives an email message. Range: 0 to 12 characters Default: None
NOTIFYL
The local user notification flag. The L in NOTIFYL indicates that the local system governs the processing of the resulting notification on that system. Range: The range of values is listed in the following table: Value WRITE MAIL ALL NONE Description A message is displayed on the workstation where the user is logged in. A mail message is sent to the user. Write to all users. No notification is sent.
Default: None
Note: The L in NOTIFYL indicates that the local system governs the processing of the resulting notification on that system.
Parameters
A21
List of Parameters
NOTIFYR
Specifies the remote user notification type when sending data to a remote system. Range: The range of values is listed in the following table: Value WRITE MAIL TSO WTO CICS LU ROSCOE ALL NONE Description A message is displayed on the screen. A mail message is sent to the user. The specified TSO user is notified. Unicenter CA-XCOM Data Transport writes to the log only (WTO). The specified CICS user is notified. The specified Logical Unit is notified. Notify Advantage CA-Roscoe user. Write to all users. No notification is sent.
Default: None
Note: The R in NOTIFYR indicates that the remote system governs the processing of the resulting notification on that system.
NOTIFY_TERM
Specifies which terminals to write to if NOTIFYL=WRITE. If NOTIFY_TERM is not set, all users specified in LOCAL_NOTIFY are be notified at the first terminal where they are logged in, as found in the system table. Range: 0 to 256 characters Default: None
NUMBER_OF_RETRIES
Maximum number of retries before a transfer is logged as failed and taken out of the transfer queue. If the value is 0, no retries are attempted. Range: 0 to 255 Default: 1 Note: Version 2 parameter.
A22
User Guide
List of Parameters
NUM_OF_DIR_BLOCKS
Specifies the number of directory blocks to allocate for a data set created on an IBM mainframe. Range: 0 to 32767 Default: 0 Note: Version 2 parameter
PASSWORD
The password associated with the user ID on a remote system. Range: 0 to 31 characters Default: None
PORT
The number of the TCP/IP port on the remote Unicenter CA-XCOM Data Transport server. Used for TCP/IP transfers only. Range: 1 to 65535 Default: 8044
PRIMARY_ALLOC
Identifies primary storage allocation for a dataset created on an IBM mainframe. Range: 0 to 99999 Default: 1 Note: Version 2 parameter
Parameters
A23
List of Parameters
PRIORITY
Indicates the priority that Unicenter CA-XCOM Data Transport uses for scheduling a transfer. If two transfers are scheduled for the same time, the one with the high priority is processed before one with a normal or low priority. Range: The range of values is listed in the following table: Value HIGH NORMAL LOW Description Set high priority. Set medium priority. Set low priority.
Default: NORMAL
PROTOCOL
The type of communication protocols to use. Range: The range of values is listed in the following table: Value SNA TCPIP
Default: SNA
Description For transfers using SNA/APPC communication protocols For transfers using TCP/IP communication protocols
QUEUE
Indicates whether to execute the transmission request immediately or to allow the request to be queued. If the user does not specify a .cnf file, and has not changed a .cnf file, the default value is YES. Note: If NO is specified and the remote system is unavailable, the request aborts. If YES is specified, START_TIME and START_DATE are read.
A24
User Guide
List of Parameters
Range: The range of values is listed in the following table: Value YES NO Description The transfer request goes into a queue and executes depending on the traffic in the queue and START_DATE and START_TIME. The transfer starts immediately.
Default: YES
QUEUE_PATH
Directory containing the transfer queue data files. Range: 0 to 256 characters Default: /usr/spool/xcom/Q, except for the following:
For HP-UX systems: /var/spool/xcom/Q For OSF Digital UNIX systems: /var/opt/xcom/Q
RMTNTFYL
Specifies the remote user notification level when sending data to a remote system. Range: The range of values is listed in the following table: Value A or ALL W or WARN E or ERROR Default: ALL Description NOTIFY on transfer completion. NOTIFY only if the transfer received a warning or error. NOTIFY only if the transfer received an error.
Parameters
A25
List of Parameters
RECORD_FORMAT
Specifies the record format of a dataset created on an IBM mainframe. This corresponds to the JCL RECFM subparameter. Range: The range of values is listed in the following table: Value F FA Description Fixed unblocked Fixed unblocked ANSI Fixed blocked Record Length The same length as the data.set The same length as the Contains data.set ISO/ANSI/FIPS control characters. Fixed Fixed record length with multiple records per block. Multiple records per block where these records contain ISO/ANSI/FIPS control characters. Multiple records per block written as standard blocks. Comment
FB
FBA
Fixed
FBS
Fixed
FM FS
The same length as the Contains machine code data.set control characters. The same length as the Written as standard data.set blocks where these records do not contain any truncated blocks or unfilled tracks. Undefined Variable Variable Contains ISO/ANSI/FIPS control characters. Multiple records per block.
U V VA
VB
Variable
A26
User Guide
List of Parameters
Value VBA
Comment Multiple records per block where these records contain ISO/ANSI/FIPS control characters. Multiple records per block where these records contain machine code control characters. May have multiple records per block where these records can span more than one block. Contains machine code control characters. A record can span more than one block.
VBM
Variable
VBS
Variable
VM
Variable
VS
Variable
Default: VB
REMOTE_FILE
Indicates the file on the remote computer to which the transferred data is being written. If you are creating the file (FILE_OPTION=CREATE), the file name must be consistent with the file naming conventions of the remote system. The local Unicenter CA-XCOM Data Transport system does not validate this name. The remote I/O system determines whether the file name is valid. For wildcard transfers, use an asterisk (*) as a file name to indicate and to inform the receiving partner that multiple files will be sent. For example, REMOTE_FILE=/PAYROLL/*. If multiple files are sent and the user specifies a specific file name, all files received by the partner are written to that specified file as one single file. An asterisk used to send to an IBM mainframe system shows that all files are to be transferred to a partitioned data set (PDS). For platforms that support it, you can specify a common file extension to append to each file name. For example, "REMOTE_FILE=/PAYROLL/*.TXT".
Parameters
A27
List of Parameters
Note: For send file transfers only. Range: 1 to 256 characters Default: None
REMOTE_FILE_RF
Indicates the name of the file to be retrieved from the remote system. For wildcard transfers, use an asterisk (*) as a file name to indicate that all files within the specified PDS/Directory should be transferred. For example, the statement REMOTE_FILE_RF=/NAMES/* indicates that all files under the NAMES directory should be transferred. When a prefix is followed by an asterisk, all members beginning with a specific prefix are transferred. For example, REMOTE_FILE_RF=/NAMES/AL* requests that files AL, ALEX, and ALICE should be transferred. The same rules apply if an asterisk is followed by a suffix. The actual file name range (not including its path) for wildcard transfers can be between 0 and 71 characters. This also includes the file extension where applicable. File names over 71 characters are truncated. Note: For retrieve file transfers only Range: 1 to 256 characters Default: None
REMOTE_SYSTEM
The name of the remote system that receives a file, job or report. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None
A28
User Guide
List of Parameters
REMOTE_SYSTEM_RF
The name of the remote system that sends a file on a receive file operation. If no value is specified here, the value in REMOTE_SYSTEM is used. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None
REMOTE_SYSTEM_SJ
The name of the remote system to which a job is sent. If no value is specified here, the value in REMOTE_SYSTEM is used. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None
REMOTE_SYSTEM_SR
The name of the remote system to which a report is sent. If no value is specified here, the value in REMOTE_SYSTEM is used. For SNA/APPC protocols, the name is as specified in the SNA/APPC configuration of the local system. For RS/6000, this is the LU6.2 Side Information record. For TCP/IP protocols, the value can be the remote systems IP address, host name, or domain name. Range: 1 to 256 characters Default: None
Parameters
A29
List of Parameters
REMOVE_TRAIL_BLANKS
Indicates whether or not to remove the blanks at the end of each record when receiving a text file. Range: YES or NO Default: NO
REPORT_TITLE
This field contains the report title and job number that will be printed on the report. The field has the following format: 8 characters Job Name 2 characters Blanks 8 characters Job Number
The Job ID is optional and can be skipped. The Job Name can also be skipped, but if you skip the Job name and want to use the job number, you must pad the number with 10 blanks. Note: For report transfers only
Examples
REPORT_TITLE=Salary94 REPORT_TITLE= Job12345 Job23456
Non-example
REPORT_TITLE=
Job34567
This is not a valid REPORT_TITLE because the Job Number spans both sub fields. This parameter is used by Unicenter CA-XCOM Data Transport on remote systems in the following ways: System MVS VAX/VMS UNIX/Linux Other systems Uses the REPORT_TITLE To interpret a non-blank value in this field as specifying the generation of a separator (banner) page for this value. To print with the report. To allow Unicenter CA-XCOM Data Transport to pass this field to the LP spooler as a title field. As a descriptive comment only and does not print it as part of the report.
A30
User Guide
List of Parameters
RESTART_SUPPORTED
Specifies whether automatic restart is to be supported on a transfer. Range: YES or NO Default: YES Note: Version 2 parameter.
RETPD
Specifies the number of days (1 to 9999) that the tape data set being created is to be retained.
Range: 1 to 9999 Default: None
Note: RETPD and EXPDT are mutually exclusive; specify one or the other.
RETRY_TIME
The number of seconds between retries of unsuccessful transfers. Range: 0 to 99999 Default: 1 Note: Version 2 parameter.
SAVE_PASSWORD_IN_CNF
Determines if the xcomtool GUI saves the password in the .CNF file. Range: The range of values is listed in the following table: Value YES NO Description The xcomtool GUI saves the password in the .CNF file in encrypted format. The xcomtool GUI does not save the password in the .CNF file and blanks the password field out after each operation.
Parameters
A31
List of Parameters
Default: NO
SECONDARY_ALLOC
Identifies secondary storage allocation for a dataset created on an IBM mainframe. Range: 0 to 99999 Default: 0 Note: Version 2 parameter.
SECURE_SOCKET
Specifies whether to use an OpenSSL socket or non-OpenSSL socket for transfers. Range: The range of values is listed in the following table: Value YES Description Performs secure transfer. The transfer uses an OpenSSL socket and must to connect to a SSL listener on the remote partner. NO Performs non-secure transfer. The transfer uses a non-OpenSSL socket. Default: NO
SESSIONS_FILE
The path name of the xcom.ses file, which tells Unicenter CA-XCOM Data Transport how many sessions can be used by a single LU. Range: 0 to 256 characters Default: /usr/spool/xcom/config/xcom.ses, except for the following:
For HP-UX systems: /var/spool/xcom/config/xcom.ses For OSF Digital UNIX systems: /var/opt/xcom/config/xcom.ses
A32
User Guide
List of Parameters
SHELL_CMD
Name of the command that runs jobs, reports, notification scripts, and post processing scripts on the local system. Range: 1 to 256 characters Default: /bin/ksh
SOCK_DELAY
TCP/IP socket option TCP_NODELAY. Refers to the Nagle algorithm for send coalescing. By default, small sends may be delayed. Should have no impact for normal Unicenter CA-XCOM Data Transport record sizes. Used for TCP/IP transfers only. Note: Socket options affect the way Unicenter CA-XCOM Data Transport uses the TCP/IP stack implementation. Range: The range of values is listed in the following table: Value YES NO
Default: YES
Description Small sends may be delayed. (Does not disable the Nagle algorithm.) All sends are immediate. (Disables the Nagle algorithm.)
SOCK_RCV_BUF_SIZE
TCP/IP socket option SO_RCVBUF. The buffer size for receives. Use zero for the default size provided by the socket implementation. The value for SOCK_RCV_BUF_SIZE can be smaller than the value for TXPI_BUF_SIZE. Used for TCP/IP transfers only. Note: Socket options affect the way Unicenter CA-XCOM Data Transport uses the TCP/IP stack implementation. Range: 0 to 65536 Default: 0
Parameters
A33
List of Parameters
SOCK_SEND_BUF_SIZE
TCP/IP Socket option SO_SNDBUF. The buffer size for sends. Use zero for the default size provided by the socket implementation. The value for SOCK_SEND_BUF_SIZE can be smaller than the value for TXPI_BUF_SIZE. Used for TCP/IP transfers only. Note: Socket options affect the way Unicenter CA-XCOM Data Transport uses the TCP/IP stack implementation. Range: 0 to 65536 Default: 0
SPOOL_FLAG
Indicates whether the report is to be spooled to disk or printed immediately. For report transfers only. Note: If the remote system is an IBM mainframe, this parameter has no effect on the transfer. Range: YES or NO Default: YES
START_DATE
Indicates the date on which the transfer becomes eligible for execution. The format is mm/dd/yy. If this field is blank, the current date is used. Example A value of 02/28/99 indicates February 28, 1999 as the start date. Format: mm/dd/yy Default: None
START_TIME
Indicates the time when the transfer becomes eligible for execution. The military format of hh:mm:ss is used. If this field is blank, then the current time is used.
Example
A value of 14:00:00 indicates 2 p.m. as the start time. Format: hh:mm:ss Default: None
A34
User Guide
List of Parameters
STAT_FREQUENCY
Indicates the frequency with which transfer statistics are made available to xcomqm. Intended for tuning high-speed links. Longer values help performance, but byte/record counts in xcomqm -D may be slightly behind the actual counts. Range: 1 to 9999 records Default: 10
STORCLAS
Specifies the name of the storage class for a new SMS-managed data set. Note: This parameter applies only to mainframe SMS data sets. Range: 1 to 8 characters Default: None
SYSTEM_USER_DATA
A user-defined text data field that can be used by an application as a customized system identifier. When specified in the configuration file of a locally initiated transfer, this identifying information is sent to the remote system and can be used to identify the system to certain applications. When received, the identifying information is displayed in the xcomqm detail display if the -D option is used, and is labeled System user data. Range: 0 to 10 characters Default: None
TAPE
Indicates to the remote system whether the volume is a tape volume or a disk file. Yes indicates a tape volume and that mounts are allowed when performing dynamic allocation. No indicates that the transfer is to a disk file. Range: YES or NO Default: None
Parameters
A35
List of Parameters
TCP_CMD
Path and name of the Unicenter CA-XCOM Data Transport program started by the XCOMD service that is used for queued locally initiated transfers, and for all remotely initiated transfers for TCP/IP protocols. Range: 0 to 256 Default: /usr/lib/xcom/xcomtcp, except for the following:
For HP-UX systems: /opt/xcom/lib/xcomtcp For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcomtcp
TEMPDIR
Indicates the directory in which temporary files for jobs and reports can be created. Range: 1 to 256 characters Default: /tmp
TP_CMD
Command to start a transaction program using SNA protocols. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcomtp For HP-UX systems: /opt/xcom/lib/xcomtp For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcomtp
TRACE_PATH
The directory containing the trace data files. Range: 0 to 256 characters Default: /usr/spool/xcom/trace, except for the following:
For HP-UX systems: /var/spool/xcom/trace For OSF Digital UNIX systems: /var/opt/xcom/trace
A36
User Guide
List of Parameters
TRANSFER_NAME
Allows a user to assign a name to a transfer. This name is also available to the remote Unicenter CA-XCOM Data Transport system. In addition, if the remote Unicenter CA-XCOM Data Transport system has defined a transfer identifier, that name is available to the local Unicenter CA-XCOM Data Transport for UNIX or Linux system. When received, the transfer identifier is displayed in the xcomqm display if the -D option is used, and is labeled Transfer name. The equivalent to this parameter on MVS is the transfer identifier (XFERID). Range: 0 to 10 characters Default: None
TRANSFER_TYPE
Generated by the graphical user interface to specify the type of transfer to initiate. Can also be used in a configuration file that has multiple transfers in it, to specify a different transfer type from the default value. Range: 1 to 4 Value 1 2 3 4
Default: 3
Note: The functionality of this parameter is similar to using the -cnumber command with xcom62 or xcomtcp at the command line. However, the values used to indicate the type of transfer are different.
Parameters
A37
List of Parameters
TRANSFER_USER_DATA
A user-defined text data field that can be used by an application as a customized transfer identifier. When specified in the configuration file of a locally initiated transfer, this identifying information is sent to the remote system and can be used to identify the transfer to certain applications. When received, the identifying information is displayed in the xcomqm detail display if the -D option is used, and is labeled Transfer user data. Range: 0 to 10 characters Default: None
TRUNCATION
Indicates whether Unicenter CA-XCOM Data Transport truncates excess characters in the source file if the record exceeds the maximum record length as indicated by the MAXRECLEN parameter. If NO is selected, and the maximum record length is exceeded, Unicenter CA-XCOM Data Transport aborts the transfer. This parameter is ignored if CARRIAGE_FLAG=NO. Note: Truncation is not valid for BINARY data or for non-text data received on the UNIX or Linux platform. Range: YES or NO Default: NO
TRUSTED
Allows the user to request a trusted transfer and the partners Unicenter CA-XCOM Data Transport TRUSTED database to be searched to verify the users credentials. This eliminates the need for the user to specify a USERID and PASSWORD. If XCOM_TRUSTED_OVR is set to NO or no USERID is specified, the USERID of the process that initiated the transfer will be used. Note: TRUSTED=YES cannot be specified with indirect transfers, because this is not supported. Range: YES, NO, Y, N Default: NO
TRUSTED_PATH
The directory containing the trusted files. Default: /user/spool/xcom/trusted
A38
User Guide
List of Parameters
TXPI_BUF_SIZE
For TCP/IP transfers, the internal buffer size for sends and receives. The default size allows multiple Unicenter CA-XCOM Data Transport records to be received in a single socket call. With this default, if your Unicenter CA-XCOM Data Transport record size is less than 32K, Unicenter CA-XCOM Data Transport will attempt to receive multiple records in a single socket call. Used for TCP/IP transfers only. Range: 0 to 65536 Default: 32768
TXPI_RECEIVE_TIMEOUT
Maximum wait time, in seconds, that this Unicenter CA-XCOM Data Transport waits to receive from the partner system. If a value of 0 is specified, it waits indefinitely. Use for TCP/IP transfers only. Range: 0 to 999 seconds Default: 0
TXPI_SEND_CHECK_FREQ
Indicates the frequency that Unicenter CA-XCOM Data Transport checks to see if incoming error information is available when sending data. For example, if the value is 5, a check is made every fifth time that data is sent, to determine if data is available for receiving. Larger values give better performance. Smaller values minimize the sending of data after the partner reports an error. Used for TCP/IP transfers only. Range: 0 to 9999 Default: 10
TXPI_TERM_TIMEOUT
Maximum wait time, in seconds, for partner to terminate TCP/IP communications. If a transfer terminates normally, both sides of the conversation coordinate the termination, and there should be no need to wait. This timeout will occur only during an error in the termination of the connection. Used for TCP/IP transfers only. Range: 0 to 999 seconds Default: 20 seconds
Parameters
A39
List of Parameters
UMASK
Used to set the permissions assigned to a file when the file is being created and received on the system for the first time. The value is expressed as an octal number (base 8). The octal number has the same meaning as in the standard umask command. Range: 000 to 777 Default: 022
UNIT
Specifies the unit on which a dataset is to be created on an IBM mainframe. Note: Used when FILE_OPTION=CREATE. Range: 0 to 6 characters Default: None
UNITCT
Specifies the number of units to be allocated on the remote system. This is a tape parameter and is used when the partner is an IBM mainframe. Range: 1 to 20 Default: None
UNIT_RF
Specifies the unit from which a dataset is to be retrieved from an IBM mainframe. Range: 0 to 6 characters Default: None
USE_TP_SECURITY
Only for NCR systems using SNA. When set to YES, Unicenter CA-XCOM Data Transport instructs the APPC to send out the user ID and password in the APPC attach request. Note: This parameter applies to outgoing security only. Range: YES or NO Default: NO
A40
User Guide
List of Parameters
USERID
The user ID that the security system on a remote system checks before granting access for the file transfer. Range: 0 to 12 characters Default: None
VERSION
Indicates the version of the Unicenter CA-XCOM Data Transport protocol to be used for this transfer. For using TCP/IP, only a value of 2 is valid. Range: 1 or 2 Default: 2 Note: Version 2 parameter.
VOLCT
Specifies the maximum number of volumes to be used in processing a multi-volume output tape data set on the remote system. Range: 1 to 255 Default: None
VOLUME
Specifies the volume on which a dataset is to be created on an IBM mainframe. Range: 0 to 6 characters Default: None
VOLUME_RF
Specifies the volume from which a dataset is to be retrieved from an IBM mainframe. Range: 0 to 6 characters Default: None
Parameters
A41
List of Parameters
VOLSQ
Specifies the sequence number of the first volume of a multi-volume remote data set to be used. Range: 1 to 255 Default: None
XCOM_CONFIG_SSL
Specifies the configssl.cnf file path and file name. Range: 1 to 256 characters Default:
For UNIX/Linux systems: /usr/spool/xcom/config/configssl.cnf For HP-UX systems: /var/spool/xcom/config/configssl.cnf For OSF Digital UNIX systems: /var/opt/xcom/config/configssl.cnf
XCOM_PASSWORD
Specifies the default password for remotely initiated transfers. Range: 0 to 31 characters Default: None
XCOM_SHOW_CIPHER
Specifies whether to display encryption algorithms in the Unicenter CA-XCOM Data Transport queue detailed information, which is used for transfers. Range: The range of values is listed in the following table: Value NO YES Default: NO Description Do not display encryption algorithms in the queue detail information. Display encryption algorithms in the queue detail information.
A42
User Guide
List of Parameters
XCOM_TRUSTED_OVR
Specifies if the user is permitted to override the user ID by using the USERID parameter for locally initiated trusted transfers. If XCOM_TRUSTED_OVR is set to YES, the user is permitted to override the user ID by using the USERID parameter. If it is set to NO, the user ID of the process that initiated the transfer is used. Range: YES, NO, Y, N Default: NO
XCOM_USERID
The default user ID for remotely initiated transfers. Range: 0 to 12 characters Default: xcom
XCOMPRE_LOCAL
Indicates whether the xcompre script file for a locally initiated transfer should be run.
Default: NO
XENDCMD
The name of the post processing command optionally invoked by the Unicenter CA-XCOM Data Transport transfer program after any type of transfer is finished, whether successful or not. Invoked after partner communications have ended. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcomend For HP-UX systems: /opt/xcom/lib/xcomend For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcomend
Parameters
A43
List of Parameters
XIDEST
Specifies the name of the remote system on the intermediate destination that is designated for store-and-forward transfers. If this variable is null or unset, then a direct connection to a remote system is attempted. Note: For store-and-forward transfers only. Range: 0 to 14 characters Default: None
XLOGFILE
The name of the file where Unicenter CA-XCOM Data Transport logs activity. If you do not specify this parameter, the systemwide log file/usr/spool/xcom/xcom.log is used. If you specify this parameter with a different file name, the logging information is only sent to the specified file. Note: If QUEUE=YES, specify the full path name. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/spool/xcom/xcom.log For HP-UX systems: /var/spool/xcom/xcom.log For OSF Digital UNIX systems: /var/opt/xcom/xcom.log
XLPCMD
Name of the post-processing command used to send print jobs to the spooler. For incoming reports only. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcomlp For HP-UX systems: /opt/xcom/lib/xcomlp For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcomlp
A44
User Guide
List of Parameters
XLUNAME
Indicates the name of the local LU. This name must match the remote LU name on the remote system. Range: 1 to 17 characters Default: None Note: Not used in Unicenter CA-XCOM Data Transport for RS/6000 SNA Services or RS/6000 SNA Server.
XMODE
Indicates the mode name associated with the SNA/APPC configuration for the XLUNAMERemote LU name pair. This name must match the mode name defined on the remote system. Range: 1 to 8 characters Default: XCOMMODE Note: Not used in Unicenter CA-XCOM Data Transport for RS/6000 SNA Services or RS/6000 SNA Server.
XNODESPEC
Required for Brixton and SunLink APPCs. Indicates the name of the node that specifies the gateway to use for the transfer. Does not apply to other APPCs. Range: 1 to 64 characters Default: None
XNOTIFYCMD
Path name of the command that Unicenter CA-XCOM Data Transport will use to notify users on the local system of the completion of a transfer. This is normally a shell script that composes a message and invokes mail or write as appropriate. Range: 0 to 256 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcomntfy For HP-UX systems: /opt/xcom/lib/xcomntfy For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcomntfy
Parameters
A45
List of Parameters
XPPCMD
Path name of the command used for user-defined post processing, for file transfers only. Only used when the local system is receiving the file. Range: 0 to 64 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcompp For HP-UX systems: /opt/xcom/lib/xcompp For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcompp
XPRECMD
Path name of the command used for user-defined pre-allocation processing, for locally and remotely initiated transfers. Specify this parameter in xcom.glb to invoke the pre-allocation exit xcompre. Range: 0 to 64 characters Default:
For UNIX/Linux systems: /usr/lib/xcom/xcompre For HP-UX systems: /opt/xcom/lib/xcompre For OSF Digital UNIX systems: /usr/opt/xcom/lib/xcompre
XTRACE
Indicates the level of desired execution tracing. Range: The range of values is listed in the following table: Value 0 1 to 8 9 10 Default: 0 Description No tracing Levels of tracing from 1 (lowest) to 8 (highest) Show the contents of the data buffers Includes levels 1 to 9 plus some additional detailed technical information
A46
User Guide
Appendix
Messages
The messages contained in this section are written to a specified log file on the local system (see the XLOGFILE parameter). Some messages are also displayed on the users terminal and sent to the remote system. The messages are listed in ascending order.
Error Messages
Messages with numbers ranging from 0 to 255 are informational or prompt messages. Messages numbering between 100 and 255 represent Unicenter CA-XCOM Data Transport states and are used in traces, and so on. Message numbers of 256 and above are error messages. The following is an example of a Unicenter CA-XCOM Data Transport message:
XCOMU0010I XCOM62 STARTING TRANSFER
Message ID Content
The first four characters of the message ID, XCOM, are constant. The Unicenter CA-XCOM Data Transport system that generated the message is indicated by the fifth character of the message ID. The system identifier convention of the fifth character is as follows: Character Position 1-4 5 Explanation The first through fourth characters are always the string XCOM. The fifth character is used as follows: Character C D E Refers to the following system IBM or Microsoft PC-DOS, MS-DOS, and OS/2 Digital Equipment Corp. VAX/VMS, OpenVMS Alpha, and OpenVMS VAX IBM VSE
Messages
B1
Error Messages
Character Position
Explanation K M N R S T U V W 8 IBM CICS IBM z/OS Windows NT Netware IBM AS/400 Tandem UNIX/Linux IBM VM Windows IBM Stratus Computer
Note: Some of the system identifiers in this list represent systems that are supported for existing customers but are no longer generally available. See the chapter, "Introduction, for a list of currently available Unicenter CA-XCOM Data Transport platforms. 6-9 10 The sixth through ninth characters are used for the message number, for example: 0001 The tenth character is used as follows Character I E Indicates An informational message. No action is required on the part of the user. An error message. Usually some action is necessary to correct the problem or to determine the cause. A prompt requesting a response by the user. A warning message that some type of failure is occurring which may or may not be fatal to what you are doing.
P W
B2
User Guide
List of Messages
List of Messages
The following pages list messages that Unicenter CA-XCOM Data Transport can return in response to job requests, with explanations and recommended user actions, where appropriate. In the list, the four-character constant (XCOM) and the component identifier (in our case, U for UNIX or Linux), have been deleted from each message ID. The messages are listed in numerical order. 0007I Major code: 0x00000000 Descriptive message Reason: This is a return code from the underlying system software. It is usually followed by a message describing the meaning of the code. Action: Refer to the documentation for the SNA LU 6.2 or other system software. 0008I Minor code: 0x00000000 Descriptive message Reason: This is a return code from the underlying SNA APPC. Action: Refer to the documentation for the SNA LU 6.2 software. 0010I Starting XCOM Transfer on Thu Aug 8 12:19:18 2002 Reason: This start of transfer message is issued when a locally initiated transfer is begun. It is simultaneously placed in the transfer log. Action: None required.
Messages
B3
List of Messages
0011I
Transfer ended; 0 blocks (0 bytes) transmitted in 0 seconds (0 bytes/second) Reason: This message marks the completion of a locally initiated transfer. It placed in the log and written to standard error at the end of a transfer. Action: None required.
0016E
Transfer started by a remote system. Reason: This message is issued when a transfer is started by a remote system by allocating the Unicenter CA-XCOM Data Transport transaction program. Action: None required.
0017I
Transfer expired and was removed from queue. Reason: The transfer has expired and has been removed from the queue. Action: None required.
0022I
Transfer suspended by user Reason: The transfer has been suspended by the user. This is an informational message that is sent to the remote side of the conversation to inform the remote system and user that the transfer has been suspended. Action: None required.
B4
User Guide
List of Messages
0023I
Transfer resumed by RESUME command. Reason: The transfer has been resumed by a RESUME command issued from the screen interface or by the use of the XCOMQM command. Action: None required.
0024I
Transfer scheduled for future execution. Reason: The transfer is placed in the Unicenter CA-XCOM Data Transport schedulers queue. Action: None required.
0025I
Remotely initiated retry. Reason: The retry was initiated by the remote system. Action: None required.
0026I
Remotely initiated first try. Reason: The transfer was initiated by the remote system. Action: None required.
Messages
B5
List of Messages
0027I
Remotely initiated restart. Reason: The restart was initiated by the remote system. Action: None required.
0028I
Starting locally initiated transfer. Reason: The locally initiated transfer is starting. Action: None required.
0288E
System function failed (Wait Timed Out). Reason: A call to system( ) has failed. This function is used to initiate command functions from within Unicenter CA-XCOM Data Transport. If wait timed out is specified after the error message text, this indicates that the transferred job did not complete before the DAEMON_TIMEOUT period expired. Action: Retry the transfer. This message may indicate the failure of a system call in a sendjob or in a pre or post processing script. If the problem persists, take a trace and contact Computer Associates Customer Support.
0029I
Locally initiated transfer started. Reason: The locally initiated transfer has started. Action: None required.
B6
User Guide
List of Messages
0030E
Cannot process a non-queued TCPIP transfer from xcom62. Reason: A transfer using TCP/IP was attempted using the xcom62 command. Action: Use the xcomtcp command for transfers using TCP/IP protocols.
0031E
Cannot process a non-queued SNA/APPC transfer from xcomtcp. Reason: A transfer using SNA/APPC was attempted using the xcomtcp command. Action: Make sure xcomd is running. Use the xcom62 command for transfers using SNA/APPC protocols.
0046I
CONFIRMED_CHECKPOINT Reason: Unicenter CA-XCOM Data Transport is confirming a checkpoint. Action: None provided.
0047I
Local transfer restarted. Reason: The local transfer has restarted. Action: None required. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
Messages
B7
List of Messages
0052I
Transfer held. Reason: The transfer was held from starting at the time for which it was scheduled. Action: None required. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0053I
Transfer released. Reason: The transfer was released to start at the time for which it was scheduled. Action: None required.
0075P
Warning: xcomd will abort. Data may be lost. Go ahead? Reason: This is a warning message allowing you one last chance before forcefully bringing down the Unicenter CA-XCOM Data Transport scheduler. Action: Respond with y if you want to stop the daemon. Any other reply will not stop the process.
0077I
Aborting xcomd; PID=0 Reason: Unicenter CA-XCOM Data Transport scheduler is being forced down. Action: None required. The daemon will stop.
B8
User Guide
List of Messages
0078P
Please answer y(yes) or n(no). Reason: Please answer y(yes) or n(no). Action: Reply to the prompt with a y or an n.
0079I
xcomd: stop requested. Reason: A user has requested that the Unicenter CA-XCOM Data Transport scheduler to stop gracefully. Action: None required.
0080I
xcomd: stop request received. Reason: A user has requested that the Unicenter CA-XCOM Data Transport scheduler, xcomd, stop, and that request has been received by the running daemon process. Action: None required.
0081I
xcomd: stop request rejected. Reason: The Unicenter CA-XCOM Data Transport scheduler has rejected a users request to stop. Unicenter CA-XCOM Data Transport scheduler cannot be stopped while there are started or active transfers in the queue. Action: Suspend all active transfers and retry the operation.
Messages
B9
List of Messages
0082I
xcomd: stop request accepted. Reason: The Unicenter CA-XCOM Data Transport scheduler has accepted a users request to stop. Action: None required.
0085P
Configuration cannot be read correctly. Defaults will be taken. Reason: Some parameters cannot be taken from the configuration file. This may be caused by the following reasons: - the configuration file contains errors or invalid parameters. - the read() system call returned an error. Action: Reply to the prompt. If you do not want defaults to be taken for parameters that cannot be parsed, reply cancel and check your configuration file. Otherwise, reply ok.
0086P
Configuration cannot be read correctly. No action will be taken. Reason: Some parameters cannot be taken from the configuration file. This may be caused by the following reasons: - the configuration file contains errors. - the read() system call returned an error. Action: Reply ok. If you do not want defaults to be taken for parameters that cannot be parsed, check your configuration file and try to open it again.
B10
User Guide
List of Messages
0087P
Do you want to save changes? Reason: This warning message appears when you are about to loose some changes you made to Unicenter CA-XCOM Data Transport parameters to give you the last chance to save the changes in file. Action: Reply to the prompt.
0088I
xcomd started. Reason: The Unicenter CA-XCOM Data Transport scheduler has started. Action: None required.
0089I
xcomd ended. Reason: The Unicenter CA-XCOM Data Transport scheduler has ended. Action: None required.
0090I
Problems starting xwait, Retrying... Reason: The Unicenter CA-XCOM Data Transport wait process is unable to start. Action: None required.
Messages
B11
List of Messages
0092I
xwait started. Reason: The Unicenter CA-XCOM Data Transport wait process has started. Action: None required.
0100I
XEXIT Reason: The Unicenter CA-XCOM Data Transport transaction program is about to exit. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0102I
CLEANUP Reason: The state machine is about to enter CLEANUP state. In this state, the LU 6.2 conversation is deallocated. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0103I
TP_VALID Reason: The state machine is about to enter TP_VALID state. In this state, Unicenter CA-XCOM Data Transport accepts incoming remote allocates if the GET_ALLOCATE verb has been issued. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
B12
User Guide
List of Messages
0105I
ALLOCATE_CONVERSATION Reason: The state machine is about to enter ALLOCATE_CONVERSATION state. It is about to issue the allocate verb for the remote transaction program. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0106I
GET_ALLOCATE Reason: The state machine is about to enter GET_ALLOCATE state. In this state, incoming allocates are sought by the local transaction program. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0107I
DEALLOCATE_CONVERSATION Reason: The state machine is about to enter DEALLOCATE_CONVERSATION state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
Messages
B13
List of Messages
0108I
SEND_HEADER Reason: The state machine is about to enter SEND_HEADER state. In this state, a buffer is allocated, the Unicenter CA-XCOM Data Transport header record is created from the transfer parameters, and the header is sent. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0109I
REQUEST_HEADER_CONFIRMATION Reason: The state machine is about to enter REQUEST_HEADER_CONFIRMATION state where the incoming header is confirmed, and, if necessary, the connection is turned around. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0111I
SEND_MAXLRECL Reason: The state machine is about to enter SEND_MAXLRECL state. Here, the state machine will send the maximum logical record length as specified in the configuration file. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
B14
User Guide
List of Messages
0112I
SENDING_DATA Reason: The state machine is about to enter SENDING_DATA state. Unicenter CA-XCOM Data Transport sends one data record each time it enters this state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0113I
DATA_CONFIRM Reason: The state machine is about to enter DATA_CONFIRM state. In this state, the transaction program issues the confirm that is sent at the end of a data file. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0114I
SEND_TRAILER Reason: The state machine is about to enter SEND_TRAILER state. The trailer record containing the number of records is sent. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
Messages
B15
List of Messages
0115I
TRAILER_CONFIRM Reason: The state machine is about to enter TRAILER_CONFIRM state. The Unicenter CA-XCOM Data Transport transaction program is about to issue a deallocate confirm verb for the conversation. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0116I
RECEIVE_HEADER Reason: The state machine is about to enter RECEIVE_HEADER state. In this state, Unicenter CA-XCOM Data Transport receives the incoming header. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0117I
CONFIRM_HEADER Reason: The state machine is about to enter CONFIRM_HEADER state. The Unicenter CA-XCOM Data Transport transaction program is about to issue the confirmed LU 6.2 verb. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
B16
User Guide
List of Messages
0118I
RECEIVE_MAXLRECL Reason: The state machine is about to enter RECEIVE_MAXLRECL state. The transaction program receives the maximum record length record and uses it to initialize system parameters. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0119I
RECEIVE_DATA Reason: The state machine is about to enter RECEIVE_DATA state. In this state, the data records are received, decompressed, unpacked, and written to the target file. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0120I
DATA_CONFIRMED Reason: The state machine is about to enter DATA_CONFIRMED state. It issues the confirmed verb and closes the received file in preparation for receiving the trailer record. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
Messages
B17
List of Messages
0121I
RECEIVE_TRAILER Reason: The state machine is about to enter RECEIVE_TRAILER state. A receive_and_wait verb is issued for the incoming Unicenter CA-XCOM Data Transport trailer record. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0122I
TRAILER_CONFIRMED Reason: The state machine is about to enter TRAILER_CONFIRMED state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0123I
PROCESS_DATA Reason: The state machine is about to enter PROCESS_DATA state. In this state, the transaction program compares the record count actually received to the count sent in the trailer record. If they dont match, the state machine enters an invalid trailer state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
B18
User Guide
List of Messages
0125I
TERMINATE_INITIATE_CHECK Reason: The state machine is about to enter TERMINATE_INITIATE_CHECK state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0127I
TP_DONE Reason: The state machine is about to enter TP_DONE state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0128I
RECEIVE_FEATURE_RECORD Reason: The state machine is about to enter RECEIVE_FEATURE_RECORD state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0129I
SEND_FILE_DESCRIPTOR Reason: The state machine is about to enter SEND_FILE_DESCRIPTOR state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
Messages
B19
List of Messages
0130I
REQUEST_FEATURE_RECORD_CONFIRM Reason: The state machine is about to enter REQUEST_FEATURE_RECORD_CONFIRM state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0131I
CONFIRMED_FEATURE_RECORD Reason: The state machine is about to enter CONFIRMED_FEATURE_RECORD state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0152I
LOCAL_SEND Reason: The state machine is about to enter LOCAL_SEND state. In this state, the transaction program initializes several internal variables, logs the startup message, and sets the userid for this transfer. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
B20
User Guide
List of Messages
0153I
LOCAL_RECEIVE Reason: The state machine is about to enter LOCAL_RECEIVE state. In this state, the transaction program initializes several internal variables, logs the startup message, and sets the userid for this transfer. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0154I
REMOTE_SEND Reason: The state machine is about to enter REMOTE_SEND state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0155I
REMOTE_RECEIVE Reason: The state machine is about to enter REMOTE_RECEIVE state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0156I
OPEN_REMOTE_INPUT_FILE Reason: The state machine is about to enter OPEN_REMOTE_INPUT_FILE state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
Messages
B21
List of Messages
0157I
OPEN_LOCAL_INPUT_FILE Reason: The state machine is about to enter OPEN_LOCAL_INPUT_FILE state. The local input file is about to be opened. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0158I
OPEN_OUTPUT_FILE Reason: The state machine is about to enter OPEN_OUTPUT_FILE state. The output file is about to be opened. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0159I
LOCAL_ATTACH Reason: The state machine is about to enter LOCAL_ATTACH state. In this state, the transaction program tries to establish a connection to the local LU 6.2 SNA server. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
B22
User Guide
List of Messages
0161I
REMOTE_ATTACH Reason: The state machine is about to enter REMOTE_ATTACH state. In this state, the invoked transaction program tries to establish a connection to the local LU 6.2 SNA server. Action: This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0162I
SET_UP_OVERLAY Reason: The state machine is about to enter SET_UP_OVERLAY state. In this state, the indirect transfer header record is created. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0163I
SEND_OVERLAY Reason: The state machine is about to enter SEND_OVERLAY state. In this state, it sends the overlay record that is part of the indirect transfer protocol. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
Messages
B23
List of Messages
0164I
RECEIVE_OVERLAY Reason: The state machine is about to enter RECEIVE_OVERLAY state. An indirect transfer has been requested by the remote side and the overlay record is about to be received. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0165I
DO_SYSTEM Reason: The state machine is about to enter DO_SYSTEM state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0167I
SET_REMOTE_USER_ID Reason: The state machine is about to enter SET_REMOTE_USER_ID state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0168I
DO_COMMAND Reason: The state machine is about to enter DO_COMMAND state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
B24
User Guide
List of Messages
0169I
SEND_FEATURE_RECORD Reason: The state machine is about to enter SEND_FEATURE_RECORD state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0170I
RECEIVE_FILE_DESCRIPTOR Reason: The state machine is about to enter RECEIVE_FILE_DESCRIPTOR state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0171I
RESTART_TRANSFER Reason: The state machine is about to enter RESTART_TRANSFER state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0172I
CHECKPOINT_CONFIRM_REQUEST Reason: The state machine is about to enter CHECKPOINT_CONFIRM_REQUEST state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
Messages
B25
List of Messages
0173E rc=173 sense=xxxx Reason: The state machine is about to enter OPEN_COMPRESS state. rc=173 indicates OPEN_COMPRESS and is not an error. Action: If sense=0, no action is required. If sense=>0, take a Unicenter CA-XCOM Data Transport trace and contact Computer Associates Customer Support. 0180I SENDING_ERROR Reason: The state machine is about to enter SENDING_ERROR state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program. 0182I RECEIVE_ERROR Reason: An error message is being received from the remote partner. The Unicenter CA-XCOM Data Transport transaction program issues a receive and wait verb to retrieve the text. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
B26
User Guide
List of Messages
0185I
SEND_ERROR_MESSAGE Reason: The state machine is about to enter SEND_ERROR_MESSAGE state. A send error verb has been issued and the text of the error encountered is sent. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0186I
WAIT_FOR_REMOTE_DEALLOCATE Reason: The state machine is about to enter WAIT_FOR_REMOTE_DEALLOCATE state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0187I
TRANSFER_FAILED Reason: The Unicenter CA-XCOM Data Transport transfer has failed. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0188I
CHECK_RETURN_CODES Reason: Unicenter CA-XCOM Data Transport is checking return codes at the end of a transfer. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
Messages
B27
List of Messages
0200I
LOCAL_NOTE Reason: The state machine is about to enter LOCAL_NOTE state. In this state, the transaction program initializes several internal variables, logs the startup message, and sets the userid for this transfer. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0201I
REMOTE_NOTE Reason: The state machine is about to enter REMOTE_NOTE state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0202I
LOCAL_NOTE_ATTACH Reason: The state machine is about to enter LOCAL_NOTE_ATTACH state. In this state, the transaction program tries to establish a connection to the local LU 6.2 SNA server. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
B28
User Guide
List of Messages
0203I
ALLOCATE_NOTE_CONVERSATION Reason: The state machine is about to enter ALLOCATE_NOTE_CONVERSATION state. It is about to issue the allocate verb for the remote transaction program. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0204I
SENDING_NOTE_DATA Reason: The state machine is about to enter SENDING_NOTE_DATA state. Unicenter CA-XCOM Data Transport sends one sdsnote when it enters this state. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0205I
DATA_NOTE_CONFIRM Reason: The state machine is about to enter DATA_NOTE_CONFIRM state. In this state, the transaction program issues the confirm that is sent at the end of a sdsnote. Action: None. This message is used to report the state of the Unicenter CA-XCOM Data Transport transaction program.
0211I
queue entry (TID=000000) removed. Reason: Queue entry was removed from the queue. Action: None. This message is used to report the status of the transfer.
Messages
B29
List of Messages
0212I
transfer (TID=000000) suspended. Reason: Transfer was suspended. Action: None. This message is used to report the status of the transfer.
0213I
transfer (TID=000000) terminated. Reason: Transfer was terminated. Action: None. This message is used to report the status of the transfer.
0214I
transfer (TID=000000) resumed. Reason: Transfer was resumed. Action: None. This message is used to report the status of the transfer.
0215I
transfer (TID=000000) held. Reason: Transfer was held. Action: None. This message is used to report the status of the transfer.
B30
User Guide
List of Messages
0216I
transfer (TID=000000) released. Reason: Transfer was released. Action: None. This message is used to report the status of the transfer.
0283E
Error allocating send buffer Reason: An error was encountered when trying to increase the send buffer size using realloc() call. Action: Retry the transfer. This error may be caused by memory fragmentation.
0284E
Error forking: Error 0 Reason: Cannot create an additional process. Either the user or system process limit has been reached. Action: Check your system and user process limits. Your system administrator may be able to supply you with this information and/or raise these limits.
0285E
Error creating pipe Reason: An error occurred in creating a pipe. File descriptors are not available to open a UNIX or Linux pipe. You may have exceeded the limit on the number of open files you are allowed. Action: Contact your system administrator.
Messages
B31
List of Messages
0286E
Error setting local user id Reason: An error occurred in setting the local user ID. The call to setuid failed. Action: Be sure that the local Unicenter CA-XCOM Data Transport transaction program is either owned by the invoking user or is running setuid root. Use fully qualified filenames.
0287E
Error setting remote user id Reason: An error was encountered while trying to log on to the partner. Action: Check that the remotely requested user ID is valid on the partner system and that the initiator has entered it and the password for it correctly. Check the case for the password.
0288E
System function failed Reason: A call to system() has failed. This function is used to initiate command functions from within Unicenter CA-XCOM Data Transport. Action: The transfer was successful but the send job or a script failed. Retry the transfer. If the problem persists, take a Unicenter CA-XCOM Data Transport trace and contact Computer Associates Customer Support.
B32
User Guide
List of Messages
0289E
Command failed, RC=n Reason: A command issued using the system() call has returned a non-zero completion code. A send job failed when the job was submitted on the remote partner. The transfer to send the job was successful, however. Action: Retry the transfer. Put debugging statements in the job. See the sample postprocessing scripts for debugging statements. If the problem persists, contact Computer Associates Customer Support.
0290E Error sending overlay Reason: Send of indirect transfer record failed. Action: Retry the transfer. This may be due to a network problem. If the error persists, contact your network administrator or Computer Associates Customer Support.
Messages
B33
List of Messages
0291E
Send of indirect transfer record failed: Descriptive message Reason: An error has occurred while attempting to send the overlay record for an indirect file transfer. Action: Check the SNA connectivity and retry. If the problem persists, contact Computer Associates Customer Support.
0292E
Error sending error message to remote system: Descriptive message Reason: An error was encountered while sending an error message to the remote system. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0296E
Error deallocating conversation: Descriptive message Reason: An error was detected while deallocating a send conversation. This deallocate occurred after sending a file. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0297E
Error requesting header confirmation: Descriptive message Reason: The remote Unicenter CA-XCOM Data Transport transaction program did not confirm the transfer request header that it received. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
B34
User Guide
List of Messages
0298E
Unable to allocate remote transaction program: Descriptive message Reason: The APPC interface returned an error after an attempt was made to allocate a Unicenter CA-XCOM Data Transport transaction program on a remote LU. For transfers using TCP/IP protocols, refer to the common return codes and explanations listed in the system errno.h file. Action: Check that the remote transaction program can be allocated. On z/OS and OS/390, this means that the APPL is active. On other systems, there are different criteria for accessibility. Check that the listener is running on the remote system for TCP/IP transfers and is listening on the specified port.
0299E
Cannot attach to LU 6.2 facility on local initiate: Descriptive message Reason: An error was detected when a locally initiated transfer request attempted to attach to the APPC manager process. Action: This is frequently an SNA configuration problem. Check the SNA status as well as your connection status. Check the REMOTE_SYSTEM parameter to make sure that it contains the name of the connection profile that you want to use for this transfer.
0300E
Cannot attach to LU 6.2 facility on remote allocate: Descriptive message Reason: An error was detected when a remotely initiated transfer request transaction program attempted to attach to the APPC manager process. Action: Check the SNA configuration and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
Messages
B35
List of Messages
0301E Unable to start APPC Communications Reason: Error starting SNA Services. Action: Check for problems starting your SNA APPC. 0302E Unable to open local input file: Descriptive message Reason: A problem was encountered while trying to open a Unicenter CA-XCOM Data Transport input file; the data following the explanation is the reason. Action: Check the existence and permissions on the file you have specified. 0303E Send of XCOM header failed: Descriptive message Reason: An error has occurred while attempting to send a transfer header record. Action: Check the SNA connectivity and retry. If the problem persists, contact Computer Associates Customer Support. 0304E Send of Maximum Record Length failed: Descriptive message Reason: An error has occurred while attempting to send the maximum logical record length as part of the file transfer setup procedure. Action: Check the MAXRECLEN parameter and retry. If the problem persists, contact Computer Associates Customer Support.
B36
User Guide
List of Messages
0305E
Receive of incoming header failed: Descriptive message Reason: An error was detected while attempting to receive a transfer request header from a remote system. Action: Check the SNA connectivity and retry. If the problem persists, contact Computer Associates Customer Support.
0309E
Error reading local input file: Descriptive Message Reason: An error occurred while reading the input file. The system call read() returned -1. The error number displayed is the value of the system variable errno. Action: Check the descriptive message, fix the problem, and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0310I
Received error from remote system. Reason: An error has been received from the remote system and has been placed in the log. Action: Check the error received from the remote system and fix the problem detailed there. Error messages from partner Unicenter CA-XCOM Data Transport systems can be found in the manuals for those platforms.
Messages
B37
List of Messages
0311E
Send of user data record failed: Descriptive message Reason: An error was returned from the APPC interface while attempting to send data to a remote system. Action: Check the SNA connectivity and retry. If the problem persists, contact Computer Associates Customer Support.
0312E
Confirm to last data record failed: Descriptive message Reason: The APPC interface has returned an error when attempting to issue a confirm following the last data record in a transfer. Action: Check the SNA connectivity and retry. If the problem persists, contact Computer Associates Customer Support.
0313E
Negative response to data confirm request: Descriptive message Reason: Negative response to data confirm request. Action: Check that the target file is not open or locked. Contact Computer Associates Customer Support.
0314E
Send of trailer record failed: Descriptive message Reason: The send of trailer record failed. An error was returned by the SNA subsystem after the Unicenter CA-XCOM Data Transport trailer was sent. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
B38
User Guide
List of Messages
0315E
Trailer record not confirmed Reason: The trailer record was not confirmed. The remote side has detected an error in the Unicenter CA-XCOM Data Transport trailer, either in its format or in the number of records transferred. Action: This error may be the result of a send text file which contains zero-length records. If this is the case, try to send the file with the compression turned on.
0318E Receive_and_wait failed to turn line around Reason: This may be a communication or internal error. Action: Retry the transfer. If the error persists, contact your network administrator or Computer Associates Customer Support. 0319E Error confirming checkpoint: Descriptive message Reason: There is an error in confirming the checkpoint. Action: Possible network problems. Try turning off checkpointing. Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support. 0320E Error issuing confirmed for checkpoint: Descriptive message Reason: There is an error issuing confirmed for the checkpoint. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
Messages
B39
List of Messages
0321E
Error requesting trailer confirmation: Descriptive message Reason: An error was encountered when requesting trailer confirmation. Action: Check the SNA connectivity and retry. If the problem persists, contact Computer Associates Customer Support.
0322E
Preallocation User Exit failed, RC=n Reason: The user customized script specified by the XPRECMD parameter failed. Action: Check for errors in the user customized script specified by the XPRECMD parameter. The sample script provided is xcompre.
0403E
Cannot open output file: Descriptive message Reason: Cannot open the output file using the requested action. Action: Check the problem reported by the descriptive message, fix the problem, and retry the transfer.
0404E
Error confirming header: Descriptive message Reason: An error was encountered when attempting to issue a confirmed response to an incoming header. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
B40
User Guide
List of Messages
0405E
Error receiving maxreclen: Descriptive message Reason: An error was encountered when trying to read an incoming maximum record length record or when trying to realloc() a read buffer of the size specified in the record received. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0406E
Error while trying to read Feature Negotiation Record: Descriptive message Reason: An error was encountered while trying to read a feature negotiation record. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0407E
Error compress flag in feature negotiation protocol Reason: Compression type provided by the remote system is not supported. Action: Check Unicenter CA-XCOM Data Transport configuration file on the remote system and retry.
0408E
Error encountered in feature negotiation protocol Reason: An error was encountered in feature negotiation protocol. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
Messages
B41
List of Messages
0409E
Error encountered trying to confirm feature negotiation record: Descriptive message Reason: An error was encountered in trying to confirm a feature negotiation record. Action: Possible SNA configuration problems. Check RUSIZES. Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0410E
Error sending feature negotiation record: Descriptive message Reason: An error occurred in sending a feature negotiation record. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0411E
Error while confirming feature negotiation record: Descriptive message Reason: An error occurred while confirming a feature negotiation record. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0412E
Error receiving data: Descriptive message Reason: An error was detected by the SNA APPC receive and wait verb or TCP/IP while reading incoming data. Action: Check the TCP/IP or SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
B42
User Guide
List of Messages
0413E
Trailer invalid Reason: The count in the received trailer record did not match the actual number of records received. Action: Make sure your version of Unicenter CA-XCOM Data Transport is up to date. Retry the transfer. If the problem persists, take a Unicenter CA-XCOM Data Transport trace and contact Computer Associates Customer Support.
0415E
Error receiving trailer: Descriptive message Reason: The receive and wait issued for an incoming trailer record has failed. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0416E
Error writing output file: Descriptive message Reason: The write() system call has returned a -1. This probably means that the file system is out of space or that the users file size limit has been exceeded. Action: Check the free space in the file system. If free space is not the problem, check the size of the users ulimit (file size limit) and compare it to the size of the file that caused the transfer to fail. Repair the problem and retry the transfer. If you are transferring files larger than 2 GB, make sure your version of Unicenter CA-XCOM Data Transport supports large file sizes.
Messages
B43
List of Messages
0418E
Transmission interrupted: signal received Reason: An interrupt signal has been received and transmission has been interrupted. Action: Retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0422E
Login incorrect. Reason: User ID and/or password do not match security database. Action: Provide correct user ID and/or password.
0423I
Error receiving file descriptor record. Reason: An error occurred while trying to receive a file descriptor record. Action: Check the SNA connectivity and retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0424E
Attempting to create an existing file Reason: You cannot create an existing file. Action: Decide whether you want to replace the target file or create one using a different name. Set the parameters appropriately and retry the transfer.
B44
User Guide
List of Messages
0425E
Cannot seek to position on restart Reason: When trying to reposition a file to restart a transfer, the fseek() call returned a -1. This usually indicates a file that has been updated since its transfer was interrupted. Action: Determine why the file was updated and/or retry the transfer.
0426E
Restarting from beginning of file Reason: Checkpointing information was not found. Action: None required. The transfer will restart from the beginning of the file.
0427E
Error starting TP: no retry possible Reason: A call to execl() subroutine returned a non-zero return code; the data following the explanation is the sense. Action: Check if the file specified in TP_CMD parameter in your xcom.glb file exists and has execute permission.
0435I
Waiting for an available session. Reason: Unicenter CA-XCOM Data Transport is waiting for available sessions to start a transfer. Action: Wait until a session becomes available or increase the session limits in the xcom.ses file, restart xcomd, and retry the transfer.
Messages
B45
List of Messages
0436E
TP ended abnormally. Reason: The Unicenter CA-XCOM Data Transport daemon has detected a transaction program failure. Or, possible security problems. Action: Retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0437E
Record larger than input buffer. Reason: The length of a file record is greater than the length of the input buffer. Action: Check for correct file type. May also need to increase MAXRECLEN. Retry.
0438E
Record length greater than maxreclen, but truncation not allowed. Reason: The length of the received record is greater than maxreclen, but truncation is not allowed. Action: Make sure you are specifying the correct parameters for the file and retry. Note: On a receive operation, MAXRECLEN is set to whatever the LRECL value is on the initiating side.
0439E
Record exceeds maxreclen following compression Reason: The data in this record is already compressed. Action: Turn off compression for this transfer.
B46
User Guide
List of Messages
0440E
Internal buffer < maxreclen received. Reason: The internal buffer is smaller than the maxreclen received. Action: Retry the transfer. If the problem persists, run a trace and contact Computer Associates Customer Support.
0441I
Restart request IDs and group name do not match. Reason: A restart request was received from the remote side, but the request IDs do not match. Action: No action necessary; this is an informational message that indicates that the transaction program has encountered a problem during an attempted restart and must restart the transfer from the beginning.
0442I
Filename does not match on restart request. Reason: A restart request was received from the remote side, but the local filenames do not match. Action: Retry the transfer. If the problem persists, run a trace and contact Computer Associates Customer Support.
Messages
B47
List of Messages
0443I
Group name does not match on restart request Reason: A restart request was received from the remote side, but the remote group names do not match. Action: No action necessary; this is an informational message that indicates that the transaction program has encountered a problem during an attempted restart and must restart the transfer from the beginning.
0448E
Type of record packing not supported. Reason: An unsupported type of record packing was specified in the header. Action: Check that the remote system is generating a packing type that corresponds to a Unicenter CA-XCOM Data Transport supported packing type: YES, NO, MPACK or XPACK. For AT&T or NCR systems, the value of the mode definition code set field must be set to A for ASCII. If PACK=LENGTH is specified, RECSEP=NO must also be specified.
0450E
xcomd unknown state Reason: The XCOM API program may have been compiled with a different version of Unicenter CA-XCOM Data Transport than what is running. Action: Make sure the XCOM API program was compiled at the level of Unicenter CA-XCOM Data Transport that you are running.
B48
User Guide
List of Messages
0451E
Invocation mode undefined. Reason: This is an internal error. Action: Try the transfer again and if the error persists, contact Computer Associates Customer Support.
0454E
Invalid starting date format. Reason: The transfer was not scheduled because the starting date cannot be parsed. Action: Repair the date format and retry the transfer.
0455E
Invalid starting time format. Reason: The transfer was not scheduled because the starting time cannot be parsed. Action: Repair the time format and retry the transfer.
0456E
Cannot open EBCDIC-ASCII translation file. Reason: Global parameter INTERNAL_CONVERSION_TABLES is set to NO and the specified EBCDIC-ASCII translation file cannot be opened. Action: Check that the EBCDIC to ASCII conversion table file specified in the global variable ETOA_FILENAME exists and is readable.
Messages
B49
List of Messages
0457E
Cannot open ASCII-EBCDIC translation file. Reason: Global parameter INTERNAL_CONVERSION_TABLES is set to NO and the specified ASCII-EBCDIC translation file cannot be opened. Action: Check that the ASCII to EBCDIC conversion table file specified in the global variable ATOE_FILENAME exists and is readable.
0458E
Cannot open ASCII-EBCDIC translation file. Reason: An error was encountered while trying to parse the EBCDIC-ASCII translation file. Action: Check the EBCDIC to ASCII file. It must be 256 lines long and contain a single integer per line specified according to C conventions: a leading 0 indicates an octal number, a leading 0x indicates a hexadecimal; anything else is decimal.
0459E
Cannot open ASCII-EBCDIC translation file. Reason: An error was encountered while trying to parse the ASCII-EBCDIC translation file. Action: Check the ASCII to EBCDIC file. It must be 256 lines long and contain a single integer per line specified according to C conventions: a leading 0 indicates an octal number, a leading 0x indicates a hexadecimal; anything else is decimal.
B50
User Guide
List of Messages
0460E
Unable to Queue: Reason. Reason: Unicenter CA-XCOM Data Transport is unable to perform an enqueue function. The reason follows. Action: This message may appear for a number of reasons. If the reason is queue is full, remove some unnecessary entries from the queue, wait for them to be removed automatically, or increase MAX_QUEUE_ENTRIES and/or decrease EXPIRATION_TIME and restart xcomd. If the reason is cannot close data file, then the file system is full. Issue a df -v command to list file systems and check to see which file system is full, and then clear disk space as needed. If the problem persists, contact Computer Associates Customer Support.
0461E
Cannot get shared memory. Reason: The Unicenter CA-XCOM Data Transport queue manager cannot get shared memory. Action: Increase shared memory. Retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0463E
Cannot allocate shared memory. Reason: The Unicenter CA-XCOM Data Transport queue manager cannot allocate shared memory. Action: Retry the transfer. If the problem persists, contact Computer Associates Customer Support.
Messages
B51
List of Messages
0464E
Cannot create shared memory. Reason: The Unicenter CA-XCOM Data Transport queue manager cannot create shared memory. Action: Retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0465E
Check of xcom.glb pathnames failed. Reason: You must specify full paths to XLPCMD, TP_CMD, TRACE_PATH, and QUEUE_PATH in your xcom.glb file. Action: Check the xcom.glb file to be sure that pathnames have been specified for each of the variables listed in the Explanation. Restart the daemon after you fix any problems.
0466E
Unable to create an index file for queue. Reason: Unable to create an index file for the queue. Action: Check the permissions on the directory specified in the QUEUE_PATH variable in xcom.glb. Restart the daemon after you have repaired the problem.
0467E
Queue entry passed to xcomtp is NULL. Reason: This is an internal error. The queue entry passed to xcomtp is NULL. Action: Retry the operation. If the problem persists, contact Computer Associates Customer Support.
B52
User Guide
List of Messages
0468E
Cannot allocate memory. Reason: Cannot allocate memory. Action: Retry the operation. If the problem persists, contact Computer Associates Customer Support.
0469E
xcomd is not running or not compatible. Reason: The Unicenter CA-XCOM Data Transport scheduler, xcomd, is not running, or the version of its running copy is not compatible to the version of the Unicenter CA-XCOM Data Transport package you are using. Action: Try to start the Unicenter CA-XCOM Data Transport daemon. If it does not start, use xcomd -cy to clean up. If it still does not start, make sure that you have installed the right version of xcomd. Reinstall the Unicenter CA-XCOM Data Transport package, if necessary.
0470E
Invalid number of parameters passed to xcomtp. Reason: An invalid number of parameters has been passed to xcomtp. Action: Retry the transfer. If the problem persists, contact Computer Associates Customer Support.
Messages
B53
List of Messages
0471E
Invocation mode undefined. Reason: This is an internal error. The invocation mode is undefined. Action: Retry the operation. If the problem persists, contact Computer Associates Customer Support.
0472E
Current mode undefined. Reason: This is an internal error. The current mode is undefined. Action: Retry the operation. If the problem persists, contact Computer Associates Customer Support.
0473E
Error(s) parsing xcom.glb; xcomd cannot start. Reason: Error(s) found in parsing /usr/spool/xcom.glb; xcomd cannot start. Possible problem with the /usr/spool/xcom/config/xcom.tid file. Action: Check the xcom.glb file and fix any syntax errors you find there. Make sure the xcom.tid contains a non-zero six-digit number, the next transfer ID number. Edit and correct if necessary. Restart the Unicenter CA-XCOM Data Transport daemon.
0474E
xcomd is already running. Multiple instances not supported. Reason: xcomd is already running. Multiple instances are not supported. Action: If xcomd is running, stop it with xcomd -cy and restart.
B54
User Guide
List of Messages
0475E
xcomd index file 000025.IDX is bigger than allowed for maximum number of queue entries (xx bytes). Reason: The xcomd index file 000025.IDX is bigger than allowed for maximum number of queue entries (xx bytes). The MAX_QUEUE_ENTRIES parameter in xcom.glb may have been reduced. Action: Increase the MAX_QUEUE_ENTRIES parameter in xcom.glb and restart xcomd. If the error persists remove all files in the Q directory and restart xcomd.
0476E
Error reading xcomd index file 000025.IDX, records read xx. Reason: When reading records from the 000025.IDX file an error occurred at record number xx. Action: Try restarting xcomd. If the error persists, remove all files in the Q directory and restart xcomd.
0477E
xcomd index file 000025.IDX size (xx bytes) not a multiple of record size. Reason: The xcomd index file 000025.IDX size must be a multiple of the record size, otherwise a corrupt file is assumed. Action: Remove all files in the Q directory and restart xcomd.
Messages
B55
List of Messages
0478E
xcomd index file 000025.IDX contains a corrupt TID at index record xx. Reason: TID must be six digits. The index record contains something other than digits. The 000025.IDX file got corrupted. Action: Remove all files in the Q directory and restart xcomd.
0483E
Error: unable to fork. Reason: Either the system or the user process limit has been reached and no additional processes can be created. Action: Stop some processes, or raise process limits, and retry the operation.
0486E
Error writing configuration. Reason: An error was encountered while writing the Unicenter CA-XCOM Data Transport configuration file. Action: Check the free space in the file system. If free space is not the problem, check the permissions on the configuration file that is being written. Repair the problem and retry the operation.
0488E
Input file not specified, but stdin cannot be used. Reason: When the local input file is not specified, Unicenter CA-XCOM Data Transport normally uses console input stream (stdin). This message indicates that stdin cannot be used for this transfer. Action: Specify an input file and retry.
B56
User Guide
List of Messages
0489E
Output file not specified: stdout cannot be used. Reason: When the local output file is not specified, Unicenter CA-XCOM Data Transport normally uses console output stream (stdout). This message indicates that stdout cannot be used for this transfer. Action: Specify an output file and retry. If doing a receive, LOCAL_FILE_RF must be specified.
0491E
Versions of different Unicenter CA-XCOM Data Transport components are not compatible. Reason: The versions of the Unicenter CA-XCOM Data Transport modules are not compatible. Action: Contact Computer Associates Customer Support.
0492E
MAXRECLEN exceeds 2048 bytes limit for record packing. Reason: Since the maximum block size for packing is 2048 bytes, MAXRECLEN should not exceed this limit if record packing is turned on. Action: Change MAXRECLEN so that it is not greater than 2048 bytes or turn off record packing.
Messages
B57
List of Messages
0493E
Cannot generate internal transaction id Reason: This is an internal error. Action: Reduce the EXPIRATION_TIME and increase MAX_QUEUE_ENTRIES, then stop and restart the Unicenter CA-XCOM Data Transport scheduler, xcomd.
0494E
Duplicate transfer request number Reason: This is an internal error. Action: Retry the operation. If the problem persists, contact Computer Associates Customer Support.
0495E
Compaction not supported Reason: SNA compression with dynamic compaction is not supported. Action: Turn off dynamic compaction.
0497E
Cant open display Reason: Cannot open the display when bringing up XCOMTOOL. Action: Check with your administrator or Computer Associates Customer Support.
B58
User Guide
List of Messages
0500E
Attempting to write to a directory as a regular file Reason: Unicenter CA-XCOM Data Transport is attempting to write a file, but directory exists with the same name. Action: Change the name of the file or delete directory.
0501E
Problems starting xwait. Retrying... Reason: For SUNAPPC and BRIXTON. Either XNODESPEC or XLUNAME is incorrect in xcom.glb or the APPC is down. xcomd will come up and will schedule requests in the queue, but no transfers will go. Unicenter CA-XCOM Data Transport tries to start xwait every 3 seconds. Action: Check that the SNA APPC is up. Verify that XNODESPEC and XLUNAME are set correctly in xcom.glb.
0503E Invalid compressed data Reason: Unable to compress or decompress the data sent or received. Action: Retry the transfer. If the error persists, contact Computer Associates Customer Support.
Messages
B59
List of Messages
0505E
Received a signal from (communications) Reason: An interrupt signal has been received from APPC (for SNA) or TCP/IP (for TCP/IP) and transmission has been interrupted. Action: Retry the transfer. If the problem persists, contact Computer Associates Customer Support.
0506E
Invalid pack header data Reason: While unpacking data an error occurred. This can be due to incorrect data coming from the remote system. Action: Retry the operation. If the problem persists, contact Computer Associates Customer Support.
0507E
Unable to rename temporary file Reason: Unicenter CA-XCOM Data Transport was unable to rename the temporary file to the permanent file name. Action: Retry the transfer and if the error persists, contact Computer Associates Customer Support.
0508E
VLR/VLR2 are for binary data only Reason: CARRIAGE_FLAG=VLR or VLR2 is supported for binary files only. Action: Specify CODE_FLAG=BINARY or change CARRIAGE_FLAG to other than VLR or VLR2.
B60
User Guide
List of Messages
0509E
Big packing not supported by partner Reason: The remote system does not support the big packing type. Action: Retry the transfer using record packing type Y, M, or N.
0510E
Big packing not supported in version 1 transfers Reason: Version 1 transfers are supported for compatibility with old releases of Unicenter CA-XCOM Data Transport. Big packing was not supported in these old releases. Action: Specify version 2 to use big packing. If the remote partner does not support version 2, retry the transfer using record packing type Y, M, or N.
0511E
rc=xxx sense=yyyy Reason: Applies only to AIX RS/6000 systems. This error can occur when a TP is not available or because of a resource failure. Action: The transfer is retried automatically for queued transfers, depending on your configuration. If the problem persists, it may be an RS/6000 SNA configuration problem involving hardware or software.
Messages
B61
List of Messages
0512E
Maximum remote tcp sessions reached Reason: The maximum number of remote TCP/IP transfer requests as specified in the parameter MAX_REMOTE_TCP in xcom.glb has been reached and the transfer is rejected. Action: Either increase the value of MAX_REMOTE_TCP and recycle xcomd or run less concurrent remote TCP/IP transfers.
0514E
Destination too big Reason: An indirect transfer was submitted and the DESTINATION parameter is too long. The DESTINATION cannot exceed 16 characters for an indirect transfer. Action: Specify a DESTINATION of 16 characters or less.
0515E
Error occurred attempting to assume super-user privileges Reason: Unicenter CA-XCOM Data Transport needs system privileges (root) to be able to set the next owner, group, and file ownership and permissions correctly. Action: Try the transfer again. If the error persists, contact Computer Associates Customer Support.
0600E
Transfer is not active Reason: The operation which caused this message is applicable to active transfers only. Action: Wait until the transfer becomes active or try another operation.
B62
User Guide
List of Messages
0601E
Permission denied Reason: You do not have security rights necessary to perform the operation which caused this message. Action: None
0602E
General error in queue function; rc=n Reason: Unicenter CA-XCOM Data Transport is unable to perform an enqueue function. The reason follows. Action: If the reason is cannot write/open, check to see if your file system is full. If the reason is queue is full, remove some unnecessary entries from the queue, wait for them to be removed automatically, or increase QUEUE-SIZE and restart xcomd. If the reason is cannot generate TID, contact Computer Associates Customer Support. Other reasons may also be displayed. Try the operation again. If you cannot resolve the error, contact Computer Associates Customer Support.
0603E
The TP state is invalid Reason: The operation that caused this message requires that TP be in some particular state. The current TP state is invalid for this operation. Action: Wait for TP to enter the proper state or try different operation.
Messages
B63
List of Messages
0604E
The maximum number of clients for this server is exceeded Reason: No client was available. Action: Log off some of the clients or wait for clients to log off.
0605E
The client is already connected to this server Reason: A client with the same XPE name is already logged onto the server. Action: Try again. If the problem persists, contact Computer Associates Customer Support.
0606E
The xxxxx request is unknown to this server Reason: A client submitted a request that is not supported by the server. The server will ignore this request. Action: A server upgrade may be required. Try the transfer again. If the error persists, contact Computer Associates Customer Support.
0609E
Timeout waiting for SEND_COMPLETE event; removing client Reason: Server removed client from the list of logged clients because of timeout waiting for SEND_COMPLETE event. Action: Check the client for possible problems. Check with your administrator.
B64
User Guide
List of Messages
0611E
Timeout waiting for POLL_COMPLETE event; removing client Reason: The client did not respond. Action: Logout from the server and connect to it again.
0612E
Transport error - please reconnect Reason: Communication error. Action: Reconnect to the server.
0613E
The file record in not in a VLR format. Reason: VLR transfers can only be done on VLR format files. Action: Be sure that the input file is in the right formatthat it was received specifying the CARRIAGE_FLAG=VLR/VLR2 parameter.
0785I
Starting TCP/IP Connection Reason: A TCP/IP connection is being started to a remote partner. Action: None
Messages
B65
List of Messages
0786I
TCP/IP Connection Established Reason: A TCP/IP connection was successfully made to a remote partner. Action: None
0793I
Remote TCP/IP Connection Established Reason: A TCP/IP remote connection was successfully established from a remote partner. Action: None
0805I
0811I
Starting Secure TCP/IP Connection Reason: A Secure TCP/IP connection is being started to a remote partner. Action: None
B66
User Guide
List of Messages
0812I
Remote Secure TCP/IP Connection Requested Reason: A request for a Secure TCP/IP remote connection was received from a remote partner. Action: None
0813I
Secure TCP/IP Handshake Complete Reason: Secure Socket (SSL) negotiation for the connection successfully completed. The connection is now a Secure TCP/IP connection. Action: None
0814I
Secure TCP/IP Connection Requested Reason: A request for a Secure TCP/IP connection was sent to the remote partner. Action: None
0818I
Secure TCP/IP Connection Ended Reason: A Secure TCP/IP connection completed. Action: None
Messages
B67
Appendix
C1
Logical units (LUs) Physical units (PUs) System services control points (SSCPs)
LU Sessions
The logical connection between two NAUs is a session. Although several types of sessions exist, the end-user is aware of only one type, which is LU-to-LU. Sessions are established when one LU sends another LU an SNA request known as a BIND.
Session Identifier
A PCID is also known as a session identifier (SID) in VTAM displays. For each session, VTAM prompts you to note the primary or secondary node and displays the Session ID (SID) in hex. This SID is the PCID. If a trace of the BIND is taken, the PCID vector is towards the end. The following VTAM operator command lists all sessions generated for that LU:
DISPLAY NET, ID=XXX,E
C2
User Guide
2 3
4 6.1
6.2
C3
It utilizes LU 6.2. It works on top of PU 2.1. It can be a primary logical unit and therefore can send a BIND. It supports an extended BIND (one that contains a Procedure Correlation Identifier [PCID]) and works with the new NCP PU 2.1 support.
z/OS VM (all versions) AS/400 IBM PC OS/2 EE Most minicomputers and UNIX or Linux workstations that support PU 2.1 Windows NT, 2000, XP
C4
User Guide
PU Type
When using ILUs with VTAM and Netview displays, VTAM shows the PU type in its status display (PU Type 2 or PU Type 2.1). All PUs originally appear as PU 2.0. Once they become active, they display as PU 2.1.
C5
Appendix
Using xcomtool
xcomtool is the MOTIF-based Graphical User Interface (GUI) that allows you to do the following:
Specify transfer type Initiate transfers Control SNA (on applicable systems) Specify protocols for SNA or TCP/IP transfers Monitor the log and trace functions Update the status of active and pending transfers Edit Unicenter CA-XCOM Data Transport configuration files
This appendix contains information about using xcomtool and procedures for performing transfers.
Using xcomtool
D1
Starting xcomtool
Starting xcomtool
xcomtool is started from the shell prompt. All operations performed from the command line interface can be performed with xcomtool. Note: xcomd must be up and running to start xcomtool. To start xcomtool, enter the following at the shell prompt:
xcomtool [-d display] &
where -d display invokes xcomtool using the display defined in the display parameter. The About xcomtool banner displays, and then the xcomtool Main window displays:
D2
User Guide
Directory and File list display Toggle and Process Action Buttons Drag and Drop processing Unicenter CA-XCOM Data Transport Status window SNA information (on RS/6000 AIX SNA Server systems) Unicenter CA-XCOM Data Transport Control Windows About Xcomtool window
Four distinct control windows (one for each transfer type) can be accessed from the Main window menu to initiate the following types of transfer:
By using the Main window Menu Bar By using the Drag and Drop processing method
For information about using Drag and Drop Processing, see Drag and Drop Processing in this appendix.
Using xcomtool
D3
The Window pull-down list displays. 2. Click CA-XCOM Control or CA-XCOM Status. The applicable window displays. For more information, see the appropriate procedure in this appendix.
D4
User Guide
Using xcomtool
D5
The Main window displays a list of directories and files, along with function buttons at the right of the window. You can select a file by clicking and dragging it to a button and dropping it to perform a transfer operation. Before you use the Drag and Drop feature you should read the rest of this appendix. Refer to the control window sections for information you need to know to perform transfers.
D6
User Guide
Directory and File Lists The Main window displays directories and files. When there are more files than can be displayed in the window, vertical scroll bars appear. You can click on the scroll bars to scroll up or down in the displayed list. Selection Directory List File List Option Double-click in this list of directories to change to a different directory. Select and drag on a configuration file with the middle mouse button to perform a transfer or to edit the file. (If you use a system with only two mouse buttons, hold down both buttons at the same time.) Double-clicking on a file will result in a File Info Window.
Submit
Using xcomtool
D7
The options and screens used to edit configuration files are discussed in each control window section. For information about fields and options that appear on the screens, see Using Control Windows in this appendix.
D8
User Guide
3. 4.
Using xcomtool
D9
To edit an xcomtool configuration file, follow these steps: 1. From the menu bar on a Unicenter CA-XCOM Data Transport Control Window click File. The File pull-down list displays. 2. Click Open, highlight the configuration file you want to edit, and press OK. The following window displays:
3. 4. 5. 6.
Click Filter and enter the name of a directory to filter from. The directory is highlighted. Click Directories to select a directory from the pull-down list to filter from. The directory is highlighted and displayed in both Filter and Selection. Click Files, select a file from the pull-down list to edit. The file is highlighted. Click the OK pushbutton. The file displays on the Unicenter CA-XCOM Data Transport Control Window.
D10
User Guide
Continue with the applicable procedure: If you want to... Send a file Send a report Send a job Receive a file See the topic Sending a File Using a Control Window Sending a Report Using a Control Window Sending a Job Using a Control Window Receiving a File Using a Control Window
Using xcomtool
D11
The following options can be selected: Selection Send File Send Job Send Report Receive File Function Open Control Window-Send File. Open Control Window-Send Job. Open Control Window-Send Report. Open Control Window-Receive File.
Options
The following options can be selected: Selection Directories/ Commands Notify User User Code Conversion Miscellaneous Secure Socket Function Open the Directories/Commands window. Open Notify User window. Open Conversion window. Open Miscellaneous window. Open Secure Socket window.
D12
User Guide
Fields
See the following table for explanations of the fields found on the Control Windows. Many of these fields are common to the different types of transfer operations. Some differences in the fields displayed depend on the platform you are running. Note: If you type trailing spaces after a parameter, they will be included as part of the parameter. Field Destination System Definition
For performing transfers using SNA, this is the Remote LU. (On RS/6000 AIX systems, this is the Side Information Profile Name.) For performing transfers using TCP/IP, this can be the IP address, host name, or domain name of the remote system.
Local SNA LU Local file Target System UNIT (system specific) VOLUME (system specific) RECFM (system specific) DATACLAS DSNTYPE MGMTCLAS STORCLAS LCLNTFYL RMTNTFYL
Specifies the name of the local SNA LU. Not used for TCP/IP transfers. (Does not appear on RS/6000.) Specifies the name of the local file. Specifies the name of the remote system that receives files, jobs, reports, and sends messages. Specifies the unit for the remote file. Specifies the volume for the remote file. Specifies the record format for the remote file. See RECORD_FORMAT in this appendix. Specifies the name of the data class to use when allocating a new SMS-managed data set. Specifies the data set definition. Specifies the name of the management class to use when allocating a new SMS-managed data set. Specifies the name of the storage class for a new SMSmanaged data set. Specifies the local user notification level. Specifies the remote user notification level when sending data to a remote system.
Using xcomtool
D13
Definition Specifies the actual or maximum length, in bytes, of a logical record for the remote file. This parameter corresponds to the JCL LRECL subparameter. If the format is Variable Blocked Record then the maximum length of a logical record must be equal to the Maximum record length plus 4. If the format is Fixed or Fixed Block Record then the maximum length of a logical record must be equal to the constant record length.
Specifies the block size for the remote file. If the format is Fixed or Fixed Block Record then the block size must be a multiple of the record length. If the format is Variable Record then the block size must be 4 bytes larger than the record length. If the format is undefined then the block size must be larger than the largest record length. Specifies the unit of storage allocation for the remote file. Values are as follows:
CYL = Cylinders TRK = Tracks BLK = Blocks Primary allocation space for the remote file Secondary allocation for the remote file Directory blocks for the remote file.
Specify by:
Specifies the number of copies to be printed. Specifies the FCB JCL parameter when sending the report to an IBM mainframe. Specifies the print class to be assigned to this report on the remote system. If the remote system is an IBM mainframe, this field designates the JES SYSOUT class. In this case, type B. Specifies to the remote user the type of form that this report is to be printed on. When sending to a VAX computer, leave this field blank. Specifies what the remote system should do with the report after it is printed. Not used if the remote system is an IBM mainframe.
D14
User Guide
Field CONTROL
Definition Specifies the type of printer carriage control codes, if any, included in the report file. Values are:
ASA = ASA control codes in column 1 IBM = IBM machine characters (IBM mainframe only) OTHER = No carriage control codes
SPOOL
Specifies whether to spool the report to disk or to print it directly. If the remote system is an IBM mainframe, setting this field has no effect on the transfer. Specifies whether this transferred report is to be placed on hold on the remote system or printed immediately. Values are:
HOLD
DELETE = delete after printing KEEP = keep after printing HOLD = Hold after printing
Truncate Records Allows you to specify if a record exceeding the maximum record length should be truncated Max Record Length For UNIX/Linux systems, the locally initiating Unicenter CA-XCOM Data Transport system determines the values for MAXRECLEN, TRUNCATION, and LRECL, for send and receive operations. When the local Unicenter CA-XCOM Data Transport system initiates a transfer of a text file, the value in this field designates the length, in bytes, of the largest record that can be transferred. If a record length is longer than this value, Unicenter CA-XCOM Data Transport uses the value in the TRUNCATION parameter on the initiating side to determine whether to terminate the transfer or to truncate the record and continue the transfer. When Unicenter CA-XCOM Data Transport transfers binary files, this value indicates the length of the records that are transferred. On a receive operation, MAXRECLEN is set to whatever the LRECL value is on the initiating side.
Using xcomtool
D15
RECORD_FORMAT
This parameter specifies the record format of a dataset created on an IBM mainframe. This corresponds to the JCL RECFM subparameter. This field is unique to the Control Window-Send File. Option F FA Definition Fixed unblocked Fixed unblocked ANSI Fixed blocked Record Length The same length as the data set The same length as the Contains data set ISO/ANSI/FIPS control characters. Fixed Fixed record length with multiple records per block. Multiple records per block where these records contain ISO/ANSI/FIPS control characters. Multiple records per block written as standard blocks. Comment
FB
FBA
Fixed
FBS
Fixed
FM FS
The same length as the Contains machine code data set control characters. The same length as the Written as standard data set blocks where these records do not contain any truncated blocks or unfilled tracks. Undefined Variable Variable Contains ISO/ANSI/FIPS control characters. Multiple records per block.
U V VA
VB
Variable
D16
User Guide
Option VBA
Comment Multiple records per block where these records contain ISO/ANSI/FIPS control characters. Multiple records per block where these records contain machine code control characters. May have multiple records per block where these records can span more than one block. Contains machine code control characters. A record can span more than one block.
VBM
Variable
VBS
Variable
VM
Variable
VS
Variable
Encoding Method
Using xcomtool
D17
Option
Description ASCII (pack) Binary Binary (VLR) EBCDIC EBCDIC (text) EBCDIC (pack) ASCII Binary Binary EBCDIC EBCDIC EBCDIC XPACK No VLR No Yes XPACK
Allows you to specify the maximum record length. Allows you to specify the intermediate destination. Allows you to specify the remote user ID, remote password, remote domain name, and whether the transfer is a trusted transfer. Allows you to specify the start date and start time.
Schedule Request
Note: Binary (VLR2) is not shown as an option but can be specified on the command line by setting CODE_FLAG=BINARY and CARRIAGE_FLAG=VLR2.
D18
User Guide
Access this window from the Main window menu bar or through drag and drop. Some of the fields will contain the default values defined in the configuration file. Before completing this window, you must know the following:
Destination system Local file Remote file File action Remote system type Maximum record length
Note: In the Local file, Unicenter CA-XCOM Data Transport r11 can use wildcard characters to:
Receive multiple PDS members from a z/OS system, with each member saved as a separate file Transfer multiple directory members to another r11 system or PDS members on a z/OS system
Using xcomtool
D19
Note: If the remote system is running a Version 1 protocol then the Partner Version 2 is not selected from the Miscellaneous window. If the remote system is using a Version 2 protocol, then the Miscellaneous window must be chosen from the Options pull-down and Partner Version 2 must be selected. Obtain this information before completing the following procedure.
Procedure
To complete this window, follow these steps: Note: For more information, see Using Control Windows in this appendix. 1. Click Destination System, type the name of the destination system, and click Local File. The cursor is positioned in Local File field. 2. 3. 4. 5. 6. 7. Enter the name of the local file and click Target System. The Target System pull-down list is displayed. Select Other, Midrange, VSE, or Host from the list. Selection appears and some additional fields may be displayed. Enter File Options. The File Options pull-down list is displayed. Select Create, Replace, or Append from the list. Selection is made and some additional fields may be displayed. Click Remote File. The cursor is positioned in the Remote File field. Enter the name of the remote file. The window is complete. Select options and complete fields from the right side of this screen, as appropriate. 8. After all entries are complete, click the Send File pushbutton. The request to send a file transfer is processed.
D20
User Guide
Access this window from the Main window menu bar or through drag and drop. Some of the fields will contain the default values defined in the configuration file. Before completing this window, you must know the following:
Note: If the remote system is running a Version 1 protocol then the Partner Version 2 is not selected from the Miscellaneous window. If the remote system is using a Version 2 protocol, choose the Miscellaneous window from the Options pull-down and select Partner Version 2. Obtain this information before completing the following procedure.
Using xcomtool
D21
Procedure
To complete this window, follow these steps: Note: For more information, see Using Control Windows in this appendix. 1. Click Destination System, type the name of the destination system, and click Dest. Printer. The cursor is positioned in Destination Printer field. 2. 3. 4. 5. Enter the name of the printer on the remote system and click Local File. The cursor is positioned in the Local File field. Enter the name of the Local File and click Report Title. The cursor is positioned in the Report Title field. Enter a name for the report and click Copies. The cursor is positioned in Copies field. Enter information the Copies field and all remaining fields as required for the printer on the remote system. For information about specific requirements for each remote system, see the chapter Remote System Information. Select options and complete fields from the right side of this screen, as appropriate. After all entries are complete, click the Send Report pushbutton. The request to send a report is processed.
6. 7.
D22
User Guide
Access this window from the Main window menu bar or through drag and drop. Some of the fields will contain the default values defined in the configuration file. Before completing this window, you must know the following:
Note: If the remote system is running a Version 1 protocol then the Partner Version 2 is not selected from the Miscellaneous window. If the remote system is using a Version 2 protocol, then the Miscellaneous window must be chosen from the Options pull-down and Partner Version 2 must be selected. Obtain this information before completing the following procedure.
Using xcomtool
D23
Procedure
To complete this window, follow these steps: Note: For more information, see Using Control Windows in this appendix. 1. Click Destination System, enter the name of the destination system and click Local File. The cursor is positioned in Local File field. 2. 3. 4. Enter the name of the local file. The name of a local file is displayed. Select options and complete fields from the right side of this screen, as appropriate. After all entries are complete, click the Send Job pushbutton. The request to send a job is processed.
Access this window from the Main window menu bar or through drag and drop. Some of the fields will contain the default values defined in the configuration file.
D24
User Guide
Destination system Local file Remote file File action Remote system type Maximum record length
Note: In the Local file Unicenter CA-XCOM Data Transport r11 can use wildcard characters to:
Receive multiple PDS members from a z/OS system, with each member saved as a separate file Transfer multiple directory members to another r11 system or PDS members on a z/OS system
Note: If the remote system is running a Version 1 protocol then the Partner Version 2 is not selected from the Miscellaneous window. If the remote system is using a Version 2 protocol, then the Miscellaneous window must be chosen from the Options pull-down and Partner Version 2 must be selected. Obtain this information before completing the following procedure.
Procedure
To complete this window, follow these steps: Note: For more information, see Using Control Windows in this appendix. 1. Click Destination System, type the name of the destination system and click Target System. The Target System pull-down list is displayed. 2. 3. 4. 5. Select Other, Midrange, VSE, or Host from the list. Selection appears and some additional fields may be displayed. Click Remote File. The cursor is positioned in the Remote File field. Enter the name of the remote file. Entry is displayed. Click File Options. The File Options pull-down list is displayed.
Using xcomtool
D25
6. 7. 8.
Select Create, Replace, or Append from the list. Selection is made and some additional fields may be displayed. Click Local File. The cursor is positioned in the Local File field. Enter the name of the local file. The window is complete. Select options and complete fields from the right side of this screen, as appropriate.
9.
After all entries are complete, click the Receive File pushbutton. The parameters to receive a file are specified.
Access this window by clicking on the Options menu bar selection and selecting Directories/Commands from any Control Window. You can specify any or all of the following:
Log File Name Local Notify Command Post processing Directory Local Print Command Queue Directory
D26
User Guide
These directories and commands have default values that can be modified.
Procedure
Before completing this window, you must know the directories and commands necessary for completing this window. To complete this window, follow these steps: 1. 2. Click Log File Name. The Log File Name field is highlighted. Accept the default by pressing Enter or type the name of the log file and click Local Notify Command. The Local Notify Command field is highlighted. 3. Accept the default by pressing Enter or type the name of the local notify command and click Postproc. Directory. The Postproc. Directory field is highlighted. 4. Accept the default by pressing Enter or type the name of the directory to be used for post processing and click Local Print Command. The Local Print Command field is highlighted. 5. Accept the default by pressing Enter or type the name of the print command to be used on the local system and click Queue Directory. The Queue Directory field is highlighted. 6. Accept the default by pressing Enter or type the name of the queue directory and click Trace Directory. The Trace Directory field is highlighted. 7. Accept the default by pressing Enter or type the name of the trace directory and click Local TP Command. The Local TP Command field is highlighted. 8. After all entries are complete, click the OK pushbutton. The directories/commands are updated. A Unicenter CA-XCOM Data Transport Control Window is displayed.
Using xcomtool
D27
Fields
The following fields are associated with the Directories/Commands window: Field Log File Name Local Notify Command Postproc. Directory Local Print Command Queue Directory Trace Directory Local TP Command Definition Name of the directory string where log files are saved. Name of the directory where local notify commands are saved. Name of the directory string where post processing files are saved. Name of the directory string where local print commands are saved. Name of the directory string where transfers are queued. Name of the directory string where trace files are saved. Name of the directory string where local transaction processing commands are saved.
Pushbuttons
The following pushbuttons are located at the bottom of this window: Button OK Cancel Function Accept the specified directories/commands. The Unicenter CA-XCOM Data Transport Control Window is displayed. Exit this window without accepting any specified directories/commands. Default values are used. The Unicenter CA-XCOM Data Transport Control Window is displayed.
D28
User Guide
Access this dialog by clicking on the Options menu bar selection and selecting Notify User from any Control Window. Use this dialog to specify the local and remote users who are to be notified that the transfer has been sent or received. You can also use this dialog to specify how the local and remote users will be notified and the level of notification.
Procedure
To complete the Notify User dialog, follow these steps: Note: Pull-down menu, field, and pushbutton explanations are described after this procedure. 1. 2. 3. 4. 5. 6. Click Local Notify. The Local User field and a pull-down list is displayed. Click on the Local Notify pull-down list. Methods by which to notify the local user are displayed. Select a method from the list and click Local User. Selection is made and the cursor is positioned in the Local User field. Enter the name of the local user and click Remote Notify. Selection is displayed. The Remote User field and pull-down list display. Click on the Remote Notify pull-down list. Methods by which to notify the remote user are displayed. Select a level and a method from the list and click Remote User. Selection is made and the cursor is positioned in the Remote User field.
Using xcomtool
D29
7. 8.
Enter the name of the remote user. Selection is displayed in the Remote User field. After all entries are complete, click the OK pushbutton. A Unicenter CA-XCOM Data Transport Control Window is displayed.
Pull-Down Menus
The following options are available on the pull-down menu associated with the Notify User window: Option Function
Local Notify The local user notification flag. Options from this menu are: Option ALL WARN ERROR Remote Notify Function NOTIFY on transfer completion. NOTIFY only if the transfer received a warning or error. NOTIFY only if the transfer received an error.
The remote user notification flag. Options from this menu are: Option ALL WARN ERROR Function NOTIFY on transfer completion. NOTIFY only if the transfer received a warning or error. NOTIFY only if the transfer received an error.
Fields
The following fields are associated with the Notify User window: Field Local User Remote User Definition The user on the local system who is to be notified when Unicenter CA-XCOM Data Transport completes a transfer. The user on the remote system who is to be notified when Unicenter CA-XCOM Data Transport completes a transfer.
D30
User Guide
Pushbuttons
The following pushbuttons are located at the bottom of this window: Button OK Cancel Function Accept the specified parameters. A Unicenter CA-XCOM Data Transport Control Window is displayed. Exit this window without accepting any specified parameters. A Unicenter CA-XCOM Data Transport Control Window is displayed.
Access the Conversion dialog by clicking on the Options menu bar selection and selecting User Code Conversion from any Control Window. Use the Conversion dialog to specify a one- to three- character prefix to the file names, atoe.tab and etoa.tab, that contains the external ASCII-to-EBCDIC and EBCDIC-to-ASCII custom character conversion tables for user data conversion procedures for transfers.
Procedure
Before completing this window, make sure you know the one- to three- character prefix for the user-defined ASCII-to-EBCDIC and EBCDIC-to-ASCII conversion table names that reside in the Unicenter CA-XCOM Data Transport convtab directory that will be used for the transfer.
Using xcomtool
D31
To complete the Conversion dialog, follow these steps: Note: Pull-down menu, field, and pushbutton explanations are described after this procedure. 1. 2. Type in the prefix name of the user-defined code tables. Selection is displayed in the CODETABL field. Click the OK pushbutton. A Unicenter CA-XCOM Data Transport Control Window is displayed. Fields The following fields are associated with the Conversion dialog: Field CODETABL Definition The prefix to the file names, atoe.tab and etoa.tab, containing the external ASCII-to-EBCDIC and EBCDIC-to-ASCII custom character conversion tables that determine which external translation tables will be used by the transfer.
Pushbuttons The following pushbuttons are located at the bottom of the Conversion dialog: Button OK Cancel Function Accept the specified parameter. A Unicenter CA-XCOM Data Transport Control Window is displayed. Exit this window without accepting the specified parameter. Default parameters are used. A Unicenter CA-XCOM Data Transport Control Window is displayed.
D32
User Guide
Access this window by clicking on the Options menu bar selection and selecting Miscellaneous from any Control Window. Use this window to set the following parameters:
Using xcomtool
D33
Procedure
Before completing this window, check with your system administrator to determine the settings for each parameter. To complete this window, follow these steps: Note: Pull-down menu, field, and pushbutton explanations are described after this procedure. 1. 2. Click Compression to activate/deactivate compression. The Compression field is highlighted. Strip Blanks is activated. If you are not using Brixton or SunLink APPCs, skip this step. If you are using Brixton or SunLink APPCs, click in Gateways Hostname and type in the appropriate name. (See the Fields list that follows.) 3. 4. If you are using SNA, click SNA Log Mode. The SNA Log Mode field is highlighted. If you are using SNA, accept the default by pressing ENTER or type the name of the SNA log mode command and click Trace to activate/deactivate tracing. Selection is made and the cursor is positioned in the Trace Level pull-down menu. 5. 6. Click on the Trace Level pull-down list. Levels by which to set tracing are displayed. Select a trace level from the list and click Partner Version 2 to activate/deactivate Unicenter CA-XCOM Data Transport version 2. Selection is made and the cursor is positioned in the Checkpoint Interval field. 7. Type in a checkpoint interval and click Automatic Retries to activate/deactivate automatic restart of failed transfers. Selection is made and the cursor is positioned in the Retry Interval field. 8. 9. Type in a retry interval and click Number of Retries. Selection is made and the cursor is positioned in the Number of Retries field. Type in the number of retries. Selection is made and the Number of Retries field is highlighted. 10. After all entries are complete, click the OK pushbutton. A Control Window is displayed.
D34
User Guide
Pull-down Menu
The following options are available on the pull-down menu associated with the Miscellaneous window: Option Trace Level Function The following trace levels can be selected: 1 - 10. For more information, see the description of the XTRACE parameter in the appendix Parameters.
Fields
The following fields are associated with the Miscellaneous window: Field Gateways Hostname Definition Required for Brixton and SunLink APPCs. For Brixton, it indicates the name of the node that specifies the gateway to use for the transfer. For SunLink, it indicates the name of the gateway, as defined in the /etc/appcs file. For SNA only. Mode table entry. Defines how often (based on record count) the sending system requests a checkpoint to be taken. The value 0 indicates no checkpointing. Indicates the maximum number of retries before a transfer is logged as failed and taken out of the transfer queue. The number of seconds between retries of unsuccessful transfers. If the value is 0, no retries are attempted.
Retry Interval
Number of Retries
Using xcomtool
D35
Pushbuttons
The following pushbuttons are located at the bottom of this window: Button OK Cancel Function Accept the specified parameters. A Unicenter CA-XCOM Data Transport Control Window is displayed. Exit this window without accepting any specified parameters. Default parameters are used. A Unicenter CA-XCOM Data Transport Control Window is displayed.
D36
User Guide
Procedure
Use the following procedure to complete the Secure Socket window: 1. Select the Secure Socket option for a PROTOCOL=TCP/IP transfer using Secure Sockets or select the Non Secure Sockets option for a PROTOCOL=TCP/IP transfer using Non Secure Sockets. The Secure Socket option is specified. 2. Type the full path and file name of the Unicenter CA-XCOM Data Transport secure socket configuration file (configssl.cnf). The Secure Socket File path and name is specified. 3. Click OK. The options are specified and the Edit Transfer window displays.
Pushbuttons
The following pushbuttons are available in the Secure Socket window: Button OK Cancel Function Accepts the specified parameters. The Edit Transfer window displays. Exits this window without accepting any specified parameters. The Edit Transfer window displays.
Using xcomtool
D37
Access this window by clicking Window on the Main window menu bar and selecting CA-XCOM Status. This window can be used while the transfer is in progress or after it has been completed. The window allows you to perform several functions on the queued transfers, such as putting a transfer on hold or deleting it. This window is also the beginning point to access the following Unicenter CA-XCOM Data Transport status windows:
Procedure
To maintain transfers listed on the Status window, highlight a transfer and select an option on the right side of this window. The appropriate window for the selected option is displayed.
Fields
The following fields are associated with the Status window: Field TID Condition Initiate Status Message Definition Transfer ID. Result of a transfer, for example, failed, succeeded. Indicate whether transfer was initiated by local or remote system. Transfer status, for example, started, active, done. Explanation of informational or error message relating to a particular transfer.
D38
User Guide
Pushbuttons
The following pushbuttons are located on the right side of this window: Button Suspend Resume Hold/Release Terminate Remove Entry TP Info Log/Trace Close Window Function Allows you to suspend an active transfer. Allows you to resume with a suspended transfer. Allows you to put on hold a scheduled transfer or allows you to release a held transfer. Allows you to kill an active transfer. Allows you to delete selected transfer. Opens Xcomtp Status window for selected transfer. Opens Xcomlog window for the selected transfer. Closes this window. The xcomtool Main window is displayed.
Access this window by clicking the TP Info pushbutton on the Unicenter CA-XCOM Data Transport Status Window, or by double-clicking on an entry in the Status window list. This window displays information such as the Transaction ID of the transfer and the Start Time. The State field at the bottom of the window indicates the current status of the transfer.
Using xcomtool
D39
Procedure
To view the Xcomtp Status window, select a transfer on the Unicenter CAXCOM Data Transport Status window and click the TP Info pushbutton. The Xcomtp window displays the progress of the selected transfer.
Fields
See the following table for Xcomtp Status window field names and descriptions. These fields are informational and cannot be updated. Field Transaction ID Remote LU Request File Start Time State TP PID Owner UID Records Bytes Displays Transaction ID associated with a specific transfer. The name of the system that receives or sends a file. Type of transfer requested. Name of file. The time at which the request started. Result of a transfer, for example, failed, succeeded. Process ID of the transaction program. User ID. The number of records per second since beginning of the transfer. The number of bytes per second since the beginning of the transfer.
Pushbutton
The following pushbutton is located at the bottom of this window: Button Close Function Closes this window. The Unicenter CA-XCOM Data Transport Status window is displayed.
D40
User Guide
Access this window by clicking the Log/Trace pushbutton on the Unicenter CA-XCOM Data Transport Status window.
Procedure
To view the Xcomlog window, select a transfer on the Unicenter CA-XCOM Data Transport Status window and click the TP Info pushbutton. The Xcomtp window displays the progress of the selected transfer.
Pushbuttons
The following pushbuttons are located at the top of this window: Button More Save Trace Function Allows you to view the next page of information. Allows you to save the results of the trace to a file.
Using xcomtool
D41
Button Close VI
Function Closes this window. The Unicenter CA-XCOM Data Transport Status window is displayed. Activates the command:
xterm -e vi /usr/spool/xcom/trace/000013.tra
Note: If the vi screen does not come up, you will have to add the path to xterm in the PATH environment variable.
D42
User Guide
Appendix
Problem Determination
With each implementation, the problem determination procedures vary slightly. This appendix is focused towards help desk personnel or a designated Unicenter CA-XCOM Data Transport troubleshooter with knowledge of the following:
The operational characteristics of Unicenter CA-XCOM Data Transport for UNIX and Linux For transfers that use SNA, some knowledge of the structure and components of an SNA networking environment, including an understanding of the nature of SNA LUs, PUs, sessions, and conversations
When you have a problem, you should review the messages displayed on the screen as well as those recorded in this file. In many cases, you will be able to determine the cause of the problem from the messages. For more information about the log file, see Setting Up Log Files in the chapter The Command Line Interface. For more information about Unicenter CA-XCOM Data Transport for UNIX and Linux messages, see the appendix Messages.
Problem Determination
E1
General Procedures
General Procedures
This section contains a general test procedure to use for documenting problems. Most problems encountered by users are the result of the following:
The purpose of the procedures and worksheet in this Appendix is to help you to isolate the cause of problems and to correct them in an efficient and timely manner or to gather enough information for Unicenter CA-XCOM Data Transport Customer Support to help you as quickly as possible.
Test Procedure
To be effective, you must follow these procedures in order and document the results of every test carefully. It is good practice to run through the tests at least twice to ensure that the results are consistent. Follow these steps: 1. Document the precise actions that were performed immediately prior to the appearance of the problem. Note: The description of the actions performed should be detailed enough to allow for you to recreate the problem at some future time if necessary. 2. Document the symptoms of the problem. This includes:
Wherever possible, record any error messages that appear on the screen. 3. If a data file has been corrupted, save the data file in a safe place for later analysis by Unicenter CA-XCOM Data Transport Customer Support. Any information that appears even remotely relevant may prove vital in achieving a quick resolution to the problem. Retry the operation, isolating and eliminating as many extraneous factors as possible.
4.
E2
User Guide
General Procedures
5.
Use the following table to determine your next step. Did the Problem Then... Reoccur? No Record as much as you can from the problems first occurrence (log files, and so forth) so that if you ever see it again, you will have additional evidence. Continue with Step 6.
Yes 6.
Is an error message issued? Answer Yes Action Look up the error message in the appropriate Unicenter CA-XCOM Data Transport manual and follow the instructions. If no error message was issued and the operation does not complete (for example, hangs), the problem may be related to a system malfunction (for example, remote system response time problems, and so forth). Leave the function in the hung state for at least 10 minutes. If the problem persists, contact a person who can verify the current status of the system and backbone network. If the system or the network is not operating normally, retry the transfer at some later time.
No
7.
Problem Determination
E3
General Information
Use the following table to provide general customer information. Information Date of Incident Incident Number (to be supplied by Unicenter CA-XCOM Data Transport Customer Support) Customer Name Site ID Customer Address Customer Telephone Number Customer email Address Unicenter CA-XCOM Data Transport Platform, Version, Release, and Maintenance Customer Support Contact (to be supplied by Unicenter CA-XCOM Data Transport Customer Support) Your Response
E4
User Guide
Environment Information
Use the following table to inventory information about your environment. Use additional sheets as necessary. Information Type Platform Operating System Communications Subsystem Security Subsystem For SNA/APPC (Version/ Release/ Maintenance) Have there been any hardware or software changes (for example, hardware upgrades, operating system, Unicenter CA-XCOM Data Transport or communications type changes) Initiating System Receiving System (Receiving System) Intermediary System
Transfer Type
Please Check the box that applies to the file transfer: Send File Send Job Send Report Retrieve File
Problem Determination
E5
Problem Description
What is the customer attempting to perform or accomplish?
Use the following table to answer the questions below: Question Is the problem reproducible? Is this an immediate transfer (Foreground, TYPE=EXECUTE) or a scheduled transfer (Background, TYPE=SCHEDULE)? Has there been any hardware or software changes (for example, hardware upgrades, operating system, Unicenter CA-XCOM Data Transport or communications type changes) If YES, please explain in detail. YES NO
E6
User Guide
Problem History
Use the following section to provide a description of the problem history. Yes Is this the first occurrence of the problem? If No, please explain. No
Error Messages
Please provide a list of error messages include the message ID and all of the text.
Problem Determination
E7
z/OS VM VSE AS/400 VAX Stratus Tandem HP/9000 Linux RS/6000 Sun Solaris OS/2
E8
User Guide
Initiating Platform
____________________________
Check the column that applies to the file transfer: Send File This is a Send Job Send Report Receive File
Documentation
The following is a starting point for various error conditions on various platforms. More documentation may be required to resolve the error condition: Conditions Abend Platforms z/OS Documentation
Full Dump JES2 or JES3 log Xcom log, Batch job stream or ISPF parameters GCS Dump Virtual machine Console log Dest Table Default File Unicenter CA-XCOM Data Transport parameter file Partition DUMP,POWER log Unicenter CA-XCOM Data Transport log Batch Job stream Dest and Default Tables
VM
VSE
Problem Determination
E9
Conditions
Platforms Tandem
Documentation
Abend message What was being attempted Transfer parameters VPROC of XCOM62 JES2 or JES3 log Unicenter CA-XCOM Data Transport log Batch Job Stream or ISPF parameters Xcomcntl and default file VTAM Buffer/IO trace VTAM Buffer/IO trace Virtual Machine Console log Rexx exec or Clist Dest and default file POWER Log Unicenter CA-XCOM Data Transport log Batch Job Stream VTAM Buffer/IO trace Dest and default tables Error message received Sense codes Job logs Comm. Manager Trace (APPC only) Unicenter CA-XCOM Data Transport log Unicenter CA-XCOM Data Transport parameter file Tptrace Unicenter CA-XCOM Data Transport log Unicenter CA-XCOM Data Transport parameter file
Error in Transfer
z/OS
VM
VSE
AS/400
OS/2
DOS
E10
User Guide
Conditions
Platforms Tandem
Documentation
SNA Trace Unicenter CA-XCOM Data Transport Config Parameters used for transfer Local initiator log Remote initiator log SNA Trace Unicenter CA-XCOM Data Transport Config Parameters used for transfer Local initiator log Remote initiator log Syserr_log messages Network definitions on both sides of the connection Monitor_SDLC log Status of station, link, line, LU and session Syserr_log messages Network definitions on both sides of the connection Monitor_SDLC log Status of station, link, line, LU and session
VAX
Stratus
NetWare
Other
Problem Determination
E11
E12
User Guide
Index
#
#!ENCRYPT, 3-54
B
BLKSIZE, A-4 mainframe file creation parameter, 3-26 blksize, API, 4-7 Brixton, 3-18, A-45 API, 4-35
A
AGE_TIME, 2-7, A-3 ALLOCATION_TYPE, A-4 mainframe file creation parameter, 3-25 allocation_type, API, 4-7 API accessing the queue, 2-20 xcomqm, 2-20 options, 2-20 syntax, 2-20 API example, 4-40 API return values, 4-3 apitest.c file, API, 4-40 APPC Brixton, 3-18, A-45 SunLink, 3-18, A-45 AS/400, 5-2 ASCII/EBCDIC conversion, 3-44 ATOE_FILENAME, 2-7, A-4
C
C structures, API, 4-6 CA certificate for SSL, 6-2 expiration, 6-2 CARRIAGE_CONTROL_CHARACTERS, A-5 send report parameter, 3-35 carriage_control_characters, API, 4-8 CARRIAGE_FLAG, A-5 file type conversion parameter, 3-46 carriage_flag, API, 4-8 CA-XCOM network levels, 1-12 CA-XCOM parameters, 2-2 changing encrypted parameter values, 3-55 character conversion, 3-45, 3-47 ASCII to EBCDIC example, 3-48 EBCDIC to ASCII example, 3-48 hexadecimal numbers, 3-48 EBCDIC to ASCII, 3-48 checkpoint and restart, 3-62 performance issues, 3-62 xcom62 command, 3-62 xcomtcp command, 3-63
Index1
checkpoint parameters CHECKPOINT_COUNT, 3-63 NUMBER_OF_RETRIES, 3-63 CHECKPOINT_COUNT, A-6 checkpoint/restart parameter, 3-63 checkpoint_count, API, 4-9 CLASS, A-6 send report parameter, 3-36 class, API, 4-9 CLEANLOG, 2-21 example, 2-22 syntax, 2-22 client certificate for SSL, 6-3 CODE_FLAG, A-6 file type conversion parameter, 3-46 code_flag, API, 4-9 CODETABL, 3-12, A-7 codetabl, API, 4-10 command line interface, Retrieve File command, 3-21 communications parameters DESTINATION_TYPE, 3-14 REMOTE_SYSTEM, 3-15 REMOTE_SYSTEM_RF, 3-15 REMOTE_SYSTEM_SJ, 3-16 REMOTE_SYSTEM_SR, 3-16 setting, 3-12 XLUNAME, 3-17 XMODE, 3-17 XNODESPEC, 3-18 COMPRESS, 3-13, A-7 compress, API, 4-10 configuration files, 3-1 creating, 3-2 opening and editing in xcomtool, D-9 xcom.cnf, 3-12 xcom.glb, 2-7 xcom.ses, 2-18 configuring Unicenter CA-XCOM Data Transport SSL client, 6-5 SSL server, 6-4 connection_profile, 2-19 transfers using SNA, 2-19 transfers using TCP/IP, 2-19
CONTROL, A-8 control block structure, API, 4-3 Control Windows Receive File, D-24 Send File, D-19 Send Job, D-23 Send Report, D-21 xcomtool, D-9, D-11 drag and drop procedure, D-8 conventions in this guide, 1-21 conversion dialog, D-31 using xcomtool, D-31 CONVERT_CLASSES, 2-7, A-8 convert_classes, API, 4-11 COPIES, 2-31, A-8 Send Report parameter, 3-36 copies, API, 4-11 CREATE_DIR, 3-19, A-9 creating configuration files, 3-2 custom character sets, stored, 3-47 Customer Support, E-12 customizing notification, 2-32
D
daemon, 3-1 process, 2-5 data transfer parameters CODETABL, 3-12 COMPRESS, 3-13 MAXRECLEN, 3-14 TRUNCATION, 3-17 DATACLAS, A-9 mainframe file creation parameter, 3-26 dataclas, API, 4-11 debug_flag, API, 4-12, A-9 debugging scripts, 2-26 DEC, 5-7 DEN, A-10 den, API, 4-12
Index2
User Guide
DESTINATION, A-10 Send Report parameter, 3-36 destination system, xcomtool, D-13 destination, API, 4-12 DESTINATION_TYPE, A-10 configuration parameter, 3-14 directories, 2-1 xcomtool, D-26 Directories/Commands Window, D-26 DISPLAY_PASSWORD_IN_TRACE, 2-8, A-10 DISPOSITION, A-11 Send Report parameter, 3-37 disposition, API, 4-13 DOMAIN, A-11 domain, API, 4-13 drag and drop processing menu, xcomtool, D-6 Drop Me icon, D-8 DSNTYPE, A-11 mainframe file creation parameter, 3-26 dsntype, API, 4-13
F
fcb, API, 4-14 FCB, Send Report parameter, 3-37, A-13 file conversion custom character sets, 3-47, 3-50 default character sets, 3-49 file conversion parameters CARRIAGE_FLAG, 3-46 CODE_FLAG, 3-46 file type conversion, 3-44 FILE_OPTION, 3-19, 3-25, A-13 file_option, API, 4-14 FILE_OPTION_RF, 3-22, A-14 FORM, A-15 Send Report parameter, 3-37 form, API, 4-15 fully qualified domain name, 3-9
E
EBCDIC conversion, 3-44 using xcom62 command, 3-45 using xcomtcp command, 3-45 Edit button, xcomtool, D-7 Edit Transfer Window common options, D-11 common uses, D-11 edit xcomtool Main Window, D-11 encrypted parameter values, 3-55 EOL_CLASSES, 2-8, A-12 eol_classes, API, 4-14 error messages, system identifier, B-1 ETOA_FILENAME, 2-8, A-12 EXPDT, A-12 expdt, API, 4-14
G
global parameters, 2-6 AGE_TIME, 2-7, A-3 ATOE_FILENAME, 2-7 CONVERT_CLASSES, 2-7 DISPLAY_PASSWORD_IN_TRACE, 2-8, A-10 EOL_CLASSES, 2-8 ETOA_FILENAME, 2-8 EXPIRATION_TIME, 2-9 INTERNAL_CONVERSION_TABLES, 2-9 MAX_QUEUE_ENTRIES, 2-9 MAX_REMOTE_TCP, 2-10, 3-15, A-20 MAX_SESSIONS_ENTRIES, 2-10 METACODE_CLASSES, 2-10 PROTOCOL, 2-10 QUEUE_PATH, 2-11 SAVE_PASSWORD_IN_CNF, 2-11, A-31 SESSIONS_FILE, 2-11 SHELL_CMD, 2-12 SOCK_DELAY, 2-12 SOCK_RCV_BUF_SIZE, 2-12 SOCK_SEND_BUF_SIZE, 2-13
Index3
STAT_FREQUENCY, 2-13 TCP_CMD, 2-13 TEMPDIR, 2-13 TP_CMD, 2-14 TRACE_PATH, 2-14 TRUSTED_PATH, 2-14 TXPI_BUF_SIZE, 2-14 TXPI_SEND_CHECK_FREQ, 2-15 TXPI_TERM_TIMEOUT, 2-15 UMASK, 2-15 using, 2-6 XCOM_PASSWORD, 2-15 XCOM_USERID, 2-16 XCOMPRE_LOCAL, 2-16 XENDCMD, 2-16 XLPCMD, 2-17 XNOTIFYCMD, 2-17 XPPCMD, 2-17 XPRECMD, 2-18 XTRACE, 2-18 graphical user interface, D-1
IBM mainframe, creating a file on, 3-25 indirect transfer, 3-51 INTERNAL_CONVERSION_TABLES, A-15 global parameter, 2-9
L
LABEL, A-16 label, API, 4-16 LABELNUM, A-16 labelnum, API, 4-16 lclntfy, API, 4-16 LCLNTFYL, A-17 notification parameter, 3-59 link libraries, API SNA, 4-2 TCP/IP, 4-2 Linux, 5-16 Local Notify, xcomtool, D-26, D-29
H
hold, API, 4-15 HOLDFLAG, A-15 Send Report parameter, 3-37
local SNA LU, xcomtool, D-13 LOCAL_FILE, A-17 send file parameter, 3-20 local_file, API, 4-17
I
IBM mainframe file creation parameters ALLOCATION_TYPE, 3-25 BLKSIZE, 3-26 DATACLAS, 3-26 DSNTYPE, 3-26 LRECL, 3-27 MGMTCLAS, 3-27 NUM_OF_DIR_BLOCKS, 3-27 PRIMARY_ALLOC, 3-27 RECORD_FORMAT, 3-28 SECONDARY_ALLOC, 3-29 SECURE_SOCKET, 3-30, A-32 STORCLAS, 3-30 UNIT, 3-30 UNIT_RF, 3-24 VOLUME, 3-30, 3-31 VOLUME_RF, 3-24 XCOM_CONFIG_SSL, 3-31 XCOM_SHOW_CIPHER, 3-31
LOCAL_FILE_RF, A-18 Retrieve File parameter, 3-22, 4-17 local_file_rf, API, 4-17 LOCAL_FILE_SJ, A-18 Send Job parameter, 3-41 local_file_sj, API, 4-18 LOCAL_FILE_SR, A-18 Send Report parameter, 3-38 local_file_sr, API, 4-18 LOCAL_NOTIFY, A-19 notification parameter, 3-59 LOCAL_RECEIVE, 4-3 LOCAL_SEND, 4-3 locally initiated transfers, 3-56 localnotify, API, 4-18
Index4
User Guide
Log Browser, using status window, xcomtool, D-37 log files, 3-43 using xcom62 command, 3-43 using xcomtcp command, 3-44 logging, 3-43 logging parameter, XLOGFILE, 3-44 logical units, C-3 dependent logical units direct sessions with, C-5 independent logical units (ILUs), C-4 direct sessions with dependent logical units, C-5 LU 6.2 independent implementations, C-5 PU type, C-5 software version support for LU 6.2, C-4 LU type 0, C-3 LU type 1, C-3 LU type 2, C-3 LU type 3, C-3 LU type 4, C-3 LU type 6.1, C-3 LU type 6.2, C-3 LU type 7, C-3 LRECL, 3-27, A-19 lrecl, API, 4-19 LU. See logical units LU 6.2 benefits, improved throughput, 1-15 independent implementations, C-5
MAX_QUEUE_ENTRIES, A-19 global parameter, 2-9 MAX_REMOTE_TCP, A-20 global parameter, 2-10, 3-15 MAX_SESSIONS_ENTRIES, 2-18, A-20 global parameter, 2-10 MAXRECLEN, A-20 configuration parameter, 3-14 maxreclen, API, 4-19 member names, API, 4-6 METACODE_CLASSES, 2-10, A-20 metacode_classes, API, 4-19 MGMTCLAS, A-21 mainframe file creation parameter, 3-27 mgmtclas, API, 4-20 Miscellaneous window, xcomtool, D-33 modifying post processing parameters, xcompp, 2-26 modifying post transfer script, xcomend, 2-28 modifying printing processes, 2-31 xcomlp, 2-31 MOTIF, D-1 multiple transfers, 3-4, A-8 using semicolons, 3-4 MVS, 5-4
M
machine code characters, reports, 2-36 mailx, 2-32 Main window menu xcomtool, D-3 directories, D-7 drag and drop, D-6 editing toggle buttons, D-7 file lists, D-7 menu bar, D-5 submitting toggle buttons, D-7 mainframe file creation, 3-25 managing queue, 2-20
N
network levels diagram, 1-14 end user level, 1-12 general explanation, 1-12 logical level, 1-13 physical level, 1-13 send file flowchart, 1-20 successful send file transfer over SNA network, 1-19 network term definitions logical and physical components, C-1, C-2 LU, C-1 procedure correlation identifier (PCID), C-2 session, C-2 NEWXFER, A-8
Index5
notification parameters LCLNTFYL, 3-59 LOCAL_NOTIFY, 3-59 NOTIFY_NAME, 3-60 NOTIFY_TERM, 3-60 NOTIFYL, 3-60 NOTIFYR, 3-61 RMLNTFYL, 3-61 using, 3-58 xcom62 command, 3-58 xcomtcp command, 3-59 notification script, xcomntfy, sample, 2-32 Notify User window, D-26, D-29 NOTIFY_NAME, A-21 notification parameter, 3-60 notify_name, API, 4-20 NOTIFY_TERM, A-22 notification parameter, 3-60 NOTIFY_TERM, API, 4-21 notifying of transfer completion, 3-58 xcomtool, D-29 NOTIFYL, A-21 notification parameter, 3-60 notifyl, API, 4-20 NOTIFYR, A-22 notification parameter, 3-61 notifyr, API, 4-21 Novell NetWare, 5-6 NUM_OF_DIR_BLOCKS, 3-27, A-23 num_of_dir_blocks, API, 4-22 NUMBER_OF_RETRIES, A-22 checkpoint/restart parameter, 3-63 number_of_retries, API, 4-21
P
parameter format, 2-3 parameter values, A-1 parameters, encrypting, 3-54 PASSWORD, A-23 security parameter, 3-53 password, API, 4-22 path considerations, 2-1 PCID (procedure correlation ID), C-2 performing file transfers, 3-3 command prompt, 3-7, 3-8 performing Secure Socket transfers, D-36 permissions, 2-5, 2-15, A-40 port in xcomtool, D-17 remote system, in xcomtool, D-17 PORT, A-23 and xcomtcp, 3-10 port, API, 4-22 post processing scripts, 2-25 post transfer script, 2-28 pre-allocation exit, xcompre, 2-22 prerequisites, 1-1 PRIMARY_ALLOC, 3-27, A-23 primary_alloc, API, 4-22 printing, script, 2-31 xcomlp sample, 2-31 PRIORITY, 3-57, A-24 problem tracing, 3-41 xcom62 command, 3-42 xcomtcp command, 3-42 PROTOCOL, 3-3, A-24 and xcomtcp, 3-10 protocol, API, 4-23 protocol, in xcomtool, D-17 protocols, 2-2
O
OpenSSL, 1-4 OpenVMS, 5-7 OpenVMS Alpha, 5-7 OpenVMS VAX, 5-7 OS/2, 5-10
Index6
User Guide
REMOTE_FILE, A-27 send file parameter, 4-26 Send File parameter, 3-20 remote_file, API, 4-26
Q
QUEUE, 3-57, A-24 queue corruption, 2-5 queue manager (xcomqm), 2-20 queue parameters QUEUE, 3-57 START_DATE, 3-58 START_TIME, 3-58 using, 3-56 xcom62 command, 3-56 xcomtcp command, 3-56 queue status, using status window, D-37 queue, API, 4-23 QUEUE_PATH, A-25 global parameter, 2-11
REMOTE_FILE_RF, A-28 retrieve file parameter, 3-23, 4-26 remote_file_rf, API, 4-26 REMOTE_SYSTEM, A-28 configuration parameter, 3-15 remote_system, API, 4-27 REMOTE_SYSTEM_RF, A-29 configuration parameter, 3-15, 3-24 REMOTE_SYSTEM_SJ, 3-16, 3-41, A-29 REMOTE_SYSTEM_SR, A-29 configuration parameter, 3-16, 3-38 REMOVE_TRAIL_BLANKS, A-30 global parameter, 2-11 remove_trail_blanks, API, 4-27 REPORT_TITLE, A-30 Send Report parameter, 3-38 report_title, API, 4-28 reports, machine code characters, 2-36
R
receiving files, 3-21 using a Control Window, D-24 RECORD_FORMAT, 3-28, A-26 xcomtool, D-16 record_format, API, 4-24 Remote Notify, xcomtool, D-30 remote systems, 3-9 AS/400, 5-2 Linux, 5-16 MVS, 5-4 Novell NetWare, 5-6 OpenVMS, 5-7 OpenVMS Alpha, 5-7 OpenVMS VAX, 5-7 OS/2, 5-10 Stratus/System 88, 5-12 Tandem, 5-14 UNIX/Linux, 5-16 VM, 5-17 VSE, 5-19 Windows, 5-25 Windows NT, 5-27
resolving symbolic names, TCP/IP, 3-10 restart parameters RESTART_SUPPORTED, 3-63 RETRY_TIME, 3-64 RESTART_SUPPORTED, A-31 checkpoint/restart parameter, 3-63 restart_supported, API, 4-28 restarting transfers, 3-62 RETPD, A-31 retpd, API, 4-28 Retrieve File command, 3-21 parameters, 3-22 xcom62, 3-21 xcomtcp, 3-21 Retrieve File parameters FILE_OPTION_RF, 3-22 LOCAL_FILE_RF, 3-22, 4-17 REMOTE_FILE_RF, 3-23, 4-26
Index7
RETRY_TIME, A-31 checkpoint/restart parameter, 3-64 return codes, system restrictions, 3-42 return values, 4-3 RMLNTFYL, A-25 notification parameter, 3-61 rmtmtful, API, 4-24
Send Job command, 3-40 parameters, 3-41 xcom62, 3-40 xcomtcp, 3-40 Send Job parameter LOCAL_FILE_SJ, 3-41 Send Report command, 3-35 parameters, 3-35 support, IBM machine code characters, 3-39 xcom62, 3-35 xcomtcp, 3-35 Send Report parameters CARRIAGE_CONTROL_CHARACTERS, 3-35 CLASS, 3-36 COPIES, 3-36 DESTINATION, 3-36 DISPOSITION, 3-37 FCB, 3-37 FORM, 3-37 HOLDFLAG, 3-37 LOCAL_FILE_SR, 3-38 REPORT_TITLE, 3-38 SPOOL_FLAG, 3-39 sending files, 3-18 using a control window, D-19 jobs, using a Control Window, D-23 reports, using a Control Window, D-21 server certificate for SSL, 6-3 session control, 2-18 session ID (SID), C-2 SESSIONS_FILE, A-32 global parameter, 2-11 setting communications parameters, 3-12 session control parameters, 2-18 SHELL_CMD, 2-12, A-33 shell_cmd, API, 4-29 shells and script changes, 2-25 SID (session ID), C-2 SNA/APPC performing transfers using, 3-4, 3-7 protocols, 3-7 xcom62 example, 3-7
S
sample API program, 4-40 SAVE_PASSWORD_IN_CNF global parameter, 2-11, A-31 script changes and shell, 2-25 scripts, 2-26 post processing, 2-25 SECONDARY_ALLOC, 3-29, A-32 secondary_alloc, API, 4-29 Secure Socket Layer (SSL), 1-4 Secure Socket transfers, performing, D-36 Secure Socket window, D-36 SECURE_SOCKET global parameter, A-32 mainframe file creation parameter, 3-30 secure_socket, API, 4-29 security parameters PASSWORD, 3-53 TRUSTED, 3-53 USERID, 3-53 using, 3-52 xcom62 command, 3-52 xcomtcp command, 3-52 Send File command, 3-18 parameters, 3-19 xcom62, 3-18 xcomtcp, 3-18 Send File parameters FILE_OPTION, 3-19 LOCAL_FILE, 3-20 REMOTE_FILE, 3-20, 4-26
Index8
User Guide
SOCK_DELAY, 2-12, A-33 SOCK_RCV_BUF_SIZE, 2-12, A-33 SOCK_SEND_BUF_SIZE, 2-13, A-34 specify protocol, in xcomtool, D-17 specifying directories and commands, xcomtool, D-26 prefix to custom character conversion tables, D-31 remote system, 3-9 SPOOL_FLAG, A-34 send report parameter, 3-39 spool_flag, API, 4-29 SSL CA certificate, 6-2 expiration, 6-2 client certificate, 6-3 configuring, 6-5 mode, 6-1 server certificate, 6-3 configuring, 6-4 standard features choice of interfaces, 1-6 initiation by either computer (any-to-any), 1-6 low maintenance, 1-6 standard functions ASCII/EBCDIC translation, 1-6 checkpoint/restart, 1-7 compression, 1-6 remote spooling, 1-7 store-and-forward, 1-7 START_DATE, 3-58, A-34 start_date, API, 4-30 start_time, API, 4-30 START_TIME, queue parameter, 3-58, A-34 starting xcomd, 2-6 xcomtool, D-2 starting states, API, 4-3 STAT_FREQUENCY, 2-13, A-35 stat_frequency, API, 4-30
Status Window, xcomtool, D-37 STORCLAS, A-35 mainframe file creation parameter, 3-30 storclas, API, 4-30 store and forward, 5-6 store and forward parameter using, 3-51 xcom62 command, 3-51 xcomtcp command, 3-51 XIDEST, 3-52 Stratus/System 88, 5-12 structure of API, 4-6 Submit button, xcomtool, D-7 SunLink, 3-18, A-45 API, 4-35 SYSTEM_USER_DATA, A-35
T
Tandem, 5-14 TAPE, A-35 tape, API, 4-30 TCP/IP, 1-3, 1-16 name resolution, 3-10 performing transfers using, 3-4, 3-8 port, A-23 in xcomtool, D-17 protocol stack, 1-16 protocols, 3-8 TCP_CMD, 2-13, A-36 TEMPDIR, 2-13, 3-16, A-36 tempdir, API, 4-31 TP_CMD, 2-14, A-36 TRACE_PATH, A-36 global parameter, 2-14 tracing, 3-41 return codes, 3-42 tracing parameter, XTRACE, 3-43 transfer protocols, 2-2
Index9
transfer types answering remote requests files, 1-9 jobs, 1-9 reports, 1-9 retrieving files, 1-9 sending batch jobs for execution, 1-9 sending files, 1-9 sending reports, 1-9 TRANSFER_NAME, A-37 TRANSFER_TYPE, A-37 TRANSFER_USER_DATA, A-38 transferring files, 3-3 transfers, performing in xcomtool, D-11 troubleshooting, general procedures purpose of procedures, E-2 test procedure, E-2 TRUNCATION, 3-17, A-38 truncation, API, 4-31 TRUSTED, A-38 security parameter, 3-53 trusted, API, 4-31 TRUSTED_PATH, A-38 global parameter, 2-14 TXPI_BUF_SIZE, 2-14, A-39 TXPI_RECEIVE_TIMEOUT, A-39 TXPI_SEND_CHECK_FREQ, 2-15, A-39 TXPI_TERM_TIMEOUT, 2-15, A-39
features, 1-1 data link types, 1-6 high capacity and performance, 1-7 management, 1-8 modular support of most systems, 1-5 security, 1-8 standard, 1-6 standard functions, 1-6 file transfer types, 1-2 invoking, 1-10 menu interface, 1-10 programming interface, 1-10 standard features simple installation, 1-6 unified solution, 1-2 user interfaces, 1-2 uses, 1-2 UNIT, 3-30, A-40 unit, API, 4-31 UNIT_RF, 3-24, A-40 UNITCT, A-40 unitct, API, 4-32 UNIX/Linux, 5-16 USE_TP_SECURITY, A-40 USERID, A-41 security parameter, 3-53 userid, API, 4-32 using configuration files, 3-1
V
VAX, 5-7 VERSION, 3-17, A-41
U
UMASK, 2-15, A-40 Unicenter CA-XCOM Data Transport applications report distribution, 1-4 RJE/NJE replacement, 1-4 type 2.1 support, 1-3 benefits of LU 6.2 (APPC), 1-14 connectivity, 1-11
version, API, 4-32 viewing log information, xcomtool, D-41 VM, 5-17 VOLCT, A-41 volct, API, 4-32 VOLSQ, A-42 volsq, API, 4-32
Index10
User Guide
VOLUME, 3-30, A-41 volume, API, 4-33 VOLUME_RF, 3-24, A-41 VSE, 5-19
XCOM_USERID, global parameter, 2-16, A-43 xcom62, 3-3 SNA/APPC protocol example, 3-7 syntax, 3-5 xcom62, options, 3-5 XCOMAPI, 4-3
W
wildcard characters, 3-4 xcom62 syntax, 3-5 xcomtcp syntax, 3-5 wildcard transfers FILE_OPTION, 3-19, 3-22, A-14 LOCAL_FILE, 3-20, 4-17, A-17 LOCAL_FILE_RF, 3-22, 4-17, A-18 REMOTE_FILE, 3-21, 4-26, A-27 REMOTE_FILE_RF, 3-23, 4-26, A-28 Windows, 5-25 Windows NT, 5-27
XCOMAPI return values, 4-3 XcomAPI structure, 4-6 xcomapi.h, 4-3, 4-40 xcomd, 2-4 options, 2-5 xcomd command, 2-4 XCOMENCR, 3-54 xcomend, 2-28 sample script, 2-28 Xcomlog window, D-37, D-41 xcomlp, 2-25, 2-31 XcomnQAPI, 2-20
X
xbuffsize, API, 4-33 xcom.cnf, 3-1, 3-12 xcom.glb, 3-1 xcom.ses, 2-18 example, 2-19 xcom.trusted file entries, 2-34 sample file, 2-36 trusted transfers, 2-34 xcom.trusted.all, 2-35 xcom_config_ssl, 4-33 XCOM_CONFIG_SSL, 3-31 global parameter, A-42 XCOM_PASSWORD, global parameter, 2-15, A-42 xcom_show_cipher, 4-33 XCOM_SHOW_CIPHER global parameter, A-42 mainframe file creation parameter, 3-31 XCOM_TRUSTED_OVR, 2-35 global parameter, 2-16, A-43
xcomntfy, 2-25, 2-32 xcompp, 2-25 post processing parameters example, 2-28 modifying, 2-26 sample script, 2-27 xcompre, 2-22 example, 2-25 options, 2-24 sample, 2-24 XCOMPRE_LOCAL, 2-16 global parameter, A-43 XcomQAPI, return codes, 4-46 xcomqm, 2-20 xcomqm command line syntax, 2-20 XCOMSEND, 2-31 xcomtcp, 3-3 example, 3-11 performing transfers using, 3-8 port and protocol, 3-10 syntax, 3-5 xcomtcp, options, 3-5 xcomtool drag and drop, specifying local files, D-9
Index11
Xcomtp Status Window, D-39 XENDCMD, 2-16, A-43 xendcmd, API, 4-34 XIDEST, A-44 store and forward parameter, 3-52 xidest, API, 4-34 XLOGFILE, A-44 logging parameter, 3-44 xlogfile, API, 4-34 XLPCMD, A-44 global parameter, 2-17 xlpcmd, API, 4-35 XLUNAME, 3-17, A-45 xluname, API, 4-35
XMODE, 3-17, A-45 xmode, API, 4-35 XNODESPEC, A-45 configuration parameter, 3-18 xnodespec, API, 4-35 XNOTIFYCMD, A-45 global parameter, 2-17 xnotifycmd, API, 4-36, 4-37 XPPCMD, 2-17, A-46 xppcmd, API, 4-36 XPRECMD, 2-18, 2-22, A-46 xprecmd, API, 4-37 XTRACE, 2-18 performance, 3-43 testing and tracing parameter, 3-43, A-46
Index12
User Guide