Technical Bulletin

Using File Transfer in RUMBA for the Mainframe

Product: Version #: RUMBA for the Mainframe RUMBA OFFICE Mainframe 4.1 OFFICE 2.0 Host: NIC: Interface: Oper. Sys.: Mainframe N/A N/A Microsoft Windows 3.X

NetManage, Inc. www.netmanage.com

Technical Bulletin

Summary
With the RUMBA for the Mainframe file transfer feature, you can copy files from a PC to an IBM mainframe or from an IBM mainframe to a PC. RUMBA software works transparently with standard mainframe operating systems. This allows an application on one platform to access and use data on another platform. RUMBA software simplifies the file transfer setup process by using typical Windows menus and dialog boxes. It also reads and lists PC and host files, and lets you transfer files in the background. You can perform file transfers using the configurable tool bar. This technical bulletin provides information about using RUMBA for the Mainframe File Transfer, including background information and troubleshooting tips.

Overview
RUMBA for the Mainframe provides a robust file transfer program between a PC and an IBM host. While on the surface an upload or download are usually simple tasks, file transfers can be complex. You have to consider not only differences between the IBM host and PC operating systems and file structures, but also variables like transfer type, character translation, and data transfer rates. To start a transfer, RUMBA software will submit a command to a host file transfer program. The most common host program used is called IND$FILE. Despite the fact that IBM has kept the specifics of this interface proprietary, RUMBA software provides abundant functionality, like support for ASCII or binary transfers, Write Structured Field or Buffered data streams, EBCDIC-to-ASCII translation, and data compression. RUMBA for the Mainframe also supports DOS-based, batch, and drag-and-drop file transfer features.

Getting Help
RUMBA software includes on-line documentation, context-sensitive help, a readme file, and the Help Manager utility. In addition, an Administrator Guide is available. There is also a wealth of information available from our support web site http://supportweb.entmanage.com.

3222.DOC

Page 2

Technical Bulletin

On-line documentation is accessible from the Help menu or can be searched by clicking the question mark icon . Context-sensitive help is accessible by clicking the icon that and clicking on the field on which you want looks like an arrow and a question mark help. You can also use the CTRL-H command to invoke context-sensitive Help. The Administrator Guide includes information that a system administrator may need to configure a LAN installation and optimize the customizable features built in to the software.

Using the Demo Host to Demo File Transfer

NetManage includes a Demo host interface in RUMBA software. The demo host allows you to simulate a file transfer and it illustrates how TSO file names show up in the File Transfer dialog box. To connect to the demo host and configure a file transfer, do the following: 1. Open an untitled RUMBA display session. 2. Select Options/Interface, select the Demo host, and click OK. 3. Select Session/Session Connect. At the Enter System ID prompt, type TSOQ. 4. Press Enter until a Ready prompt appears. You are now in a demo TSO session. 5. To view the file transfer information, select Transfer/Configure and select the TSO host environment (this is the default). Make sure that Verify Host Screen and List Host Files are checked. 6. Select Transfer/Receive. The Copy from TSO Host to PC dialog box will appear and will fill the Data Sets dialog box. 7. Click on a Data Set and see how the Host File text boxes are filled. Note the PC file name for the Data Set you selected. You may, if you want, initiate a "dummy" transfer and write a zero byte file to the PC hard drive.

Transferring a File
NOTE: Before sending a file to or receiving a file from a host, the active session

window must be connected with the host.

To Transfer Files Between Your PC and the Host

1. Log on to the desired host environment (TSO, CMS, or CICS). After you get the ready prompt (prompts vary, depending on the environment used), you can begin the file transfer process.

3222.DOC

Page 3

Technical Bulletin

2. From the Transfer menu, click Configure. The File Transfer Setup dialog box appears.

Figure 1. The File Transfer Setup dialog box.

3. Specify the host environment, and any other parameters you want to specify, then click OK. 4. To send a file to the host: From the Transfer menu, click Send. 5. To receive a file from the host: From the Transfer menu, click Receive. 6. Specify transfer options when the Copy from Host to PC or Copy from PC to Host dialog box appears (the dialog box that appears depends on whether you chose Send or Receive). 7. After selecting the specifications necessary for the file transfer, select OK. 8. During the transfer, another dialog box appears that shows you the status of the transfer. If you are downloading a file to your PC, the dialog box will be titled Receive. If you are uploading a file to the host, the dialog box will be titled Send. The dialog box shows the direction of the transfer, the file names on the PC and the host, the status, and the time remaining.

3222.DOC

Page 4

Technical Bulletin

Figure 2. The File Transfer Send dialog box.

Other Ways to Transfer Files

NetManage continues to improve its software, and RUMBA for the Mainframe File Transfer functionality is no exception. Please check with your account representative or your support specialist to verify if you are running the latest version of RUMBA.

To Send Files by Dragging and Dropping

If your version of RUMBA software supports drag and drop file transfer, you will have an option in the File Transfer Setup dialog box called Enable Templates. To use a template, be sure the Enable Templates box is checked, then click the Templates button to open the File Transfer Information dialog box.

3222.DOC

Page 5

Technical Bulletin

Figure 3. The File Transfer Information dialog box lets you create templates that specify options for drag and drop file transfer.

Using a file transfer template, you can define the parameters of a drag and drop file transfer. For instance, if you would like to be able to transfer all files that have a TXT extension up to the host files that have an extension of TEXT, you can configure that in the File Transfer Information dialog box. After configuring your template, click Accept then Close. Click OK in the File Transfer Setup dialog box, then select File/Save to save your settings in a Mainframe display session. For more information about using templates, see the on-line documentation or press CTRL-H for context-sensitive Help. To perform a drag and drop transfer, select a file in the Windows File Manager and drop it into your host session window. The file is then automatically sent to the host.

3222.DOC

Page 6

Technical Bulletin

Before you use drag and drop to send a file, be sure that the session with the host is connected and that all file transfer options are correctly configured. Drag and drop is not possible on downloads, but you can configure the transfer options in the Templates dialog box. These options will be saved when you perform the Transfer/Receive command.

Using RUMBA Macros To Transfer Files

The RUMBA macro utility allows you to automate RUMBA functions, including file transfers. To create a file transfer macro, 1. Choose Macro/Editor to open the Macro Script Editor dialog box. 2. Give the macro a Key Name and Description, then double-click File Transfer in the Macro Command list box. You will be presented with the dialog boxes to configure the transfer. For more information, see the context-sensitive help. Note that multiple files can be transferred by including multiple File Transfer commands within the macro.

Batch File Transfers

If your version of RUMBA for the Mainframe has the menu option Transfer Batch you have the ability to transfer multiple files at once (batch file transfers). To do so, you add single file transfers into a list. These lists can be saved with the FTB extension. For more information about the Transfer Batch dialog parameters, see the context-sensitive help and on-line documentation.

DOS-based File Transfers

NetManage provides two files, RECEIVE.EXE and SEND.EXE that can be run in a DOS session to transfer files. For more information, see Technical Bulletin #3209.

Using File Transfer Applications

Many independent software companies have created file transfer programs that provide a different method for performing a file transfer. While many of these applications are proprietary, they do rely on RUMBA software for lower-level, connection-related, and EHLLAPI services. These companies have often tested their programs using RUMBA software and provide documentation for using their file transfer programs with RUMBA for the Mainframe. In addition, NetManage sells Tools for Visual Basic and Tools for HLLAPI that provide information about creating your own file transfer applications.

3222.DOC

Page 7

Technical Bulletin

File Transfer Concepts

To perform a file transfer between RUMBA for the Mainframe and a TSO or CMS host session, RUMBA software communicates with the host file transfer program called IND$FILE. To perform a transfer in a CICS session, RUMBA for the Mainframe communicates with the host program called DISOSS.

IND$FILE
When RUMBA software performs a file transfer, it sends commands to IND$FILE. The command for Receive:
IND$FILE GET HostFileName (options

The command for Send:

IND$FILE PUT HostFileName (options

The options depend on what is checked in the RUMBA File Transfer dialog box. The host then executes the program IND$FILE using the given parameters. IND$FILE then sends a data stream to RUMBA for the Mainframe containing the contents of the host file. The data stream will most likely be formatted into a File Transfer Write Structured Field. RUMBA software treats the IND$FILE data stream in the exact same manner as any other data stream. That is, RUMBA for the Mainframe: 1. Translates the information from EBCDIC to an internal table. 2. Translates the internal table to either ASCII or ANSI, depending on the version of RUMBA for the Mainframe and which option is chosen. 3. Writes the data that would normally be written to the screen to the file name specified in the dialog. IND$FILE will send the command in the data stream to indicate that the file transfer operation is complete and the host sends the next READY prompt. During this process, IND$FILE handles both reading the host file and writing to the host file. RUMBA software handles both reading the PC file and writing the PC file. RUMBA software handles the sending of the IND$FILE command with its parameters. If there is a problem, IND$FILE will produce what are known as TRANSXX messages (where XX equals a number). RUMBA software will pass on these errors in an on-screen Windows dialog box. See the section below, "File Transfer Does not Complete," for information about the most common IND$FILE errors.

3222.DOC

Page 8

Technical Bulletin

TSO File Transfer and Dataset Terminology

In TSO, data is organized on the Data Set Device (DASD) in blocks known as records. Records are either associated with a Sequential Data Set file or a member in a Partitioned Data Set (PDS). A Sequential Data Set file is a type of file that contains a specified number of records of a specific type and is commonly referred to as a flat file. Normally a Sequential Data Set file has text data in 80-byte records, but you can define other types of flat files of various sizes. In TSO, records are usually organized into members. Members are organized into a file type known as Partitioned Data Sets (PDS). When defining a PDS, users specify a number of directory blocks, in addition to the physical size of the file. It is also because of this directory structure and its associated structure that you cannot download a PDS as a single file through IND$FILE. A PDS can contain binary (program) data members as well as 'text' (80-character) records. For instance, the TSO editor, ISPF, will not allow you to edit the file unless it is 80 characters or less. As with an SDS file, you define a PDS file to contain certain types of data in specified record length. Each member contains a common structure as defined by the PDS and the number of records must not exceed the room set aside for the PDS file. Usually a PDS will contain many members that contain related information, however members could contain totally unique information that by chance has the data structure (file with in a file). For example, in a PDS that contains source code for a program, each member would contain lines of code that make up one procedure or module of code. Or, each member could contain a different version of the source code for one procedure. The following diagram illustrates how data is organized in TSO.

3222.DOC

Page 9

Technical Bulletin

User Library | |---- Library | | | |----- SDS | | | | | |---- Record | | | : (User data, such as text.) | | | : | | |---- Record | | | | | |----- PDS | | | | | |----- (Member) | | | | | | | | ----- Record | | | | : (User data, such as lines of code, database | | | | : records, or lines of a document.) | | | | ----- Record | | | | | |----- (Member) | | | | | | | | ----- Record | | | | : (User data, such as lines of code, database | | | | : records, or lines of a document.) | | | | ----- Record Additional information on mainframe datasets (and the JCL that supports them), can be found in the book System 370 Job Control Language by Gary DeWard Brown (Wiley, 1977).

The Difference between Buffered and WSF Transfer Modes

Write Structured Field (WSF) transfer mode is a binary data mode that is typically much faster than Buffered. In addition, WSF is the recommended (and default) mode for file transfers. If the host does not support WSF, RUMBA software automatically switches to Buffered mode. If you choose Buffered mode, the file is broken into screen-equivalent blocks and converted into characters that can be displayed on your screen. The IND$FILE Buffered convention divides every byte into two 4-bit nibbles and adds a leading

3222.DOC

Page 10

Technical Bulletin

four bits to each nibble to make the resulting new byte an EBCDIC character that can be displayed. Using this mode for file transfers, you double the amount of data that is transferred between the PC and the host. In addition, an acknowledgment (ACK) is required after each screen-equivalent block is sent before another block is sent.

RUMBA.INI Settings that Can Be Used with File Transfers

NetManage has provided extra functionality in RUMBA software to help with file transfers. To verify if you have these settings in your version of RUMBA for the Mainframe, choose Help/Search, type in the name RUMBA.INI, and go to that topic. The help topic explains all the RUMBA.INI settings available for your version of RUMBA for the Mainframe.
Setting BlankScreen=ON Description By default, when the host-specific File Transfer Setup dialog is displayed, RUMBA software does not clear its display screen. When the Setup dialog is moved to reveal a different portion of the display, it is repainted. To disable this behavior, add the BlankScreen=ON key to the RUMBA.INI file. The CmdLineArgs setting changes the host name edit box* in the file transfer information dialog box so that it can be used as a command line. This removes the 8-character limitation, and allows you to enter IND$FILE commands, with additional parameters, directly into the edit box. *The name of the edit box varies, based on the host you are using: Host TSO CMS CICS IND_Timeout= # (in seconds. List_Timeout= # (in seconds) NoATTN=1 Edit Box Name (Host File) Data Set (Host File) Name Host Data Set

CmdLineArgs=1

With these two settings, you can specify the number of seconds RUMBA will wait before sending the time-out message to you. The settings for IND$FILE transfers and List Host Files may be set independently. For example: IND_Timeout=20 List_Timeout=50 By default, at the end of a CICS file transfer, RUMBA software sends an "Attention" message to the host. This automatic "Attention" may interfere with host applications such as TPX session manager. When the NoATTN=1 switch is set, it prevents the "Attention" from being sent at the end of a CICS file transfer. You can still use the ATTENTION key on the keyboard to manually send an attention. The default setting is NoATTN=0.

3222.DOC

Page 11

Technical Bulletin

NOPA1=1 NOPA1=2

The NOPA1 entry prevents RUMBA software from sending PA1 during a TSO file transfer. This allows you to use the verify host screen without RUMBA software using PA1 for screen synchronization. You may set this entry in either of two ways. To suppress PA1, set NOPA1=1 in the [FTX] section of your RUMBA.INI file. Note that this disables List Host files. To suppress PA1 without disabling List Host Files, set NOPA1=2. This entry causes RUMBA software to send an "Attention" message instead of a PA1 message, and does not disable List Host files. To restore normal PA1 control, remove the NOPA1 entry, or set the entry to NOPA1=0.

UnlockWithCD=1

The UnlockWithCD key is used to indicate whether to unlock the keyboard when a Change Direction Indicator (CDI) flag is received from the host. If your session is leaving the keyboard unlocked when it should be locked, this setting may help. Use a value of 0 to disable keyboard unlocking with the CDI flag. The default setting is 1.

For more information about RUMBA.INI settings with RUMBA software, see Technical Bulletin 3214, Understanding RUMBA.INI in RUMBA for the Mainframe.

General Troubleshooting
There are many variables to take into account when first performing a file transfer. Problems could be related to the host, network, or PC. Here are some general suggestions with questions you should ask to help identify where the problem exists. After reviewing these questions and you should have a much better idea about where the problem resides. 1. Identify the problem.

Does the file transfer just sit and do nothing? Does it show bytes being sent? Does it transfer small files but not larger files? Is there only one file having the problem or do multiple files have the problem? Do uploads fail while downloads work (or vice versa)? Are other users able to perform transfers? Are there IND$FILE TRANSXX errors?

3222.DOC

Page 12

Technical Bulletin

2. Find out the specifics of the transfer.

What kind of file is it? What is the host file name being entered into the RUMBA dialog box? What file transfer options are you choosing in RUMBA for the Mainframe? Have you tried WSF using various Block Sizes or Buffered Transfer Modes? Are you at a READY prompt on the host? Are you overwriting a host or PC file or creating a new one? File Transfer does not Complete Problematic File Transfers RUMBA File Transfer Features

3. Depending on the symptoms of the problem, see one of the following sections:

NOTE: Generally, when troubleshooting, it is best to find the least common

denominator to make the transfer work. For instance, if attempting to transfer a large file, try transferring a small file instead. If using WSF as the file transfer mode set with buffers of 32, attempt one with buffers set to incrementally lower amounts. If that still fails, then use the Buffered Transfer mode. If an upload fails, see if a download works. Once the problem can be isolated in this way, it will be easier to resolve.

Error Messages
File Transfer does not complete 0 bytes transferred . . .

Verify the file type. Is it a text or a binary file? Verify the direction of the transfer. Is this an upload or a download? Does the opposite transfer work okay? Can you transfer other files? Can other users transfer the file?

If the File Transfer Status dialog box appears to "hang", cancel it and return to the host screen. Check the screen for any host errors. If the transfer is a download, run checks on the local PC. For example, check to see that there is sufficient disk space for the file and look for a TEMP variable.

3222.DOC

Page 13

Technical Bulletin

Run a transfer using the demo host, as described in this document, and verify that it works. If the transfer is an upload, call your host system administrator to find out if there are problems on the host (lack of disk space, etc.). Timed out waiting for host screen If List Host Files and Verify Host Screen are selected under the Transfer/Configure menu option, then RUMBA software will attempt to list the host files when Transfer/Send or Transfer/Receive menu options are chosen. If for some reason RUMBA software is unable to do this, the above error message will echo on the screen. To get around this, choose Transfer/Configure, uncheck both options, and attempt the file transfer again. Also, since RUMBA software sends a command string to the host when performing a file transfer, it requires that you be at a screen where the command can be read. Often a user is not at the proper host screen and will get this error. Test by selecting Transfer/Configure in the RUMBA session and turn off Verify Host Screen and then see if the transfer will work.
NOTE: Under TSO, early versions of RUMBA software were unable to

perform a transfer when you were at a ISPF screen. Test the transfer when at a READY prompt and call NetManage Technical Support with the results. TRANS13 - Error writing file to host; file transfer canceled Sometimes you will see this message when attempting a WSF file transfer if the host does not support it. In that case, you can try using a WSF Block Size of 2K or choose Buffered as the Transfer Mode. In some cases, you need to change the NOPA1=1 setting in the RUMBA.INI file. See the RUMBA.INI settings section above. TRANS14 - Error reading file from host: file transfer canceled Verify that you can list the file on your host system. When RUMBA software cancels the transfer, you may see host commands or data on your mainframe screen. Write these down for later reference. Verify the prompt that is on the screen. RUMBA software may not provide an error message if the Verify Host Screen box is unchecked. If you are in TSO and are at an ISPF screen, test the transfer when at a READY prompt. Call NetManage Technical Support with the troubleshooting data.

3222.DOC

Page 14

Technical Bulletin

TRANS 17 - missing or incorrect TSO dataset - name file transfer canceled Verify the host file name by listing it on the host or opening it in a host file editor like ISPF. If you are using a fully qualified PDS, test it by putting single quotes around the file name. Try connecting with an untitled display session and check the syntax of the IND$FILE additional parms. You might also try setting UnlockWithCD=0 in the RUMBA.INI file. See the section of this document on RUMBA.INI settings. TRANS18 - incorrect option specified Verify the host file name by listing it on the host. If you are using a fully qualified PDS, test it by putting single quotes around the file name. Verify the syntax of any parameters you are adding in the Additional Parameters text box in the Transfer/Configure dialog box.

Problematic File Transfers

FTX Shows Bytes Sent But No File Is Showing Up

What kind of file is it (text or binary)? Is this an upload or a download? Does the opposite transfer work okay? Do other files work? What about other users?

If the transfer is a download, run checks on the local PC. For example, check to see that there is sufficient disk space for the file and look for a TEMP variable. If the transfer is an upload, call your host system administrator to find out if there are problems on the host (lack of disk space, etc.). Also see the section of this document titled, "RUMBA.INI Settings that Can Be Used with File Transfers" to solve possible problems. Sometimes IND$FILE will send an extra key at the end of a transfer which will prevent the transfer from completing.

3222.DOC

Page 15

Technical Bulletin

Slow File Transfers There are several variables to consider when troubleshooting slow file transfers. It helps to have a baseline to determine what slow really means. Some variables to consider when troubleshooting include: connection type, network traffic, WSF or structured files transfer, size of file, and PC processor speed. To get the fastest results, choose WSF file transfer with a block size of 32. Partial File Transfers

What is the size of the file? Is the file text or binary? Is it a particular file that fails; do other files work? Is it a PC related problem? Maybe the PC is running out of disk space. Call NetManage Technical Support with troubleshooting information.

Also see the section of this document titled, "RUMBA.INI Settings that Can Be Used with File Transfers" to solve possible problems. Sometimes the 3270 data stream will differ from what RUMBA for the Mainframe expects. One of the INI settings may remedy the problem. Corrupted File Transfers

What is the size of the file? Is it text or binary? Do other files work? Call NetManage Technical Support with troubleshooting information. If it is a text file are you choosing To ASCII (for a download) or To EBCIDC (for an upload)? If it is a binary file, are you unchecking CR/LF (Carriage Return/Line Feed)?

2004 NetManage, Inc., its subsidiaries, and its affiliates. NetManage, OnWeb, RUMBA, OneStep and the Chameleon logos are registered trademarks, registered service marks, trademarks or service marks of NetManage, Inc., its subsidiaries and its affiliates in the United States and/or other countries. IBM, AS/400, DOS, SNA, and PC are registered trademarks of International Business Machines Corporation. Novell and NetWare are registered trademarks of Novell, Inc. Microsoft, Windows and Windows NT are registered trademarks of Microsoft Corporation in the United States and/or other countries. Certain other marks are the property of their respective owners.

3222.DOC

Page 16

Technical Bulletin

The information in this technical bulletin is subject to change without notice. NetManage, Inc. provides this information as is without warranty of any kind, either expressed or implied, but not limited to the implied warranty of merchantability and fitness for a particular purpose. NetManage, Inc. may improve or change the product at any time without further notice. This document does not represent a commitment on the part of NetManage, Inc. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used only in accordance with the terms of the licensing agreement.

3222.DOC

Page 17