com.ibm.eNetwork.ECL
Class ECLXfer

java.lang.Object
  |
  +--com.ibm.eNetwork.ECL.ECLXfer

public class ECLXfer

extends java.lang.Object

ECLXfer allows the transfer of files to and from a 3270 or 5250 host, over an established session. ECLXfer supports the 3270 Host File Transfer Program IND$FILE (for SBCS) or APVUFILE (for DBCS) transfer protocols, which can be controlled by means of the standard IND$FILE or APVUFILE send and receive options. ECLXfer also supports 5250 File Transfer, which can be controlled by means of the send and receive options specific to OS/400.

Common Parameters (valid for send or receive)

ASCII

When used with SBCS session, it causes ASCII to EBCDIC translation on a send and EBCDIC to ASCII translation on a receive. When used with Taiwan or Korean DBCS session, it causes 1-byte code to 1-byte code and 2-byte code to 2-byte code translation according to host and PC code pages. It inserts SO/SI characters into the DBCS field on send and removes SO/SI on receive.

JISCII

This is valid for Japanese DBCS sessions only. Causes 1-byte code to EBCDIC and 2-byte code to IBM Kanji on a send and reverse translation on a receive. Inserts SO/SI characters into the DBCS field on send and removes SO/SI on receive.

CRLF

Strips carriage return/line feed characters on a send and adds carriage return/line feed to each record on a receive.

NOSO

This option is valid only for DBCS when used with the JISCII or ASCII option on send. It does not convert SO (hex 0E) and SI (hex 0F) before and after the DBCS field or RS (hex 1E) and US (hex 1F) to SO (hex 0E) and SI (hex 0F).

SO

This option is valid only for DBCS when used with the JISCII or ASCII option on receive. It converts SO (hex 0E) and SI (hex 0F) to RS (hex 1E) and US (hex 1F).

USER

This option is valid only for DBCS and only when used with ASCII (JISCII) and SO options on receive. If USER is specified, SO (x'0E') and SI (x'0F') will not be converted to RS(x'1E') and US (x'1F').

APPEND

The source file will be appended to the target file. If APPEND is not specified, the target file will be replaced. APPEND is not supported for members of an MVS partitioned data set.

NEW

The transfer will abort if the target file exists. This option may be used to protect against accidental erase of an existing target file.

Additional Send Parameters for MVS only

LRECL(n)

n is the logical record length of host file.

BLKSIZE(n)

n is the block size of the host file.

RECFM x

Recording mode for the host file. Values for x are F (fixed length), V (variable length), and U (undefined record type)

SPACE(quantity[,increment])

Amount of space to be allocated for a new TSO data set.

Quantity

Units of space to be allocated initially. This must be specified when the SPACE parameter is specified.

Increment

Units of space to be added each time new space is required.

The following parameters are only valid when the SPACE parameter is specified, and are mutually exclusive of each other.

AVBLOCK(n)

Average block length used as the unit size by the SPACE parameter. The (n) is block length in bytes.

TRACKS

Specifies that the unit of space is a track. Only valid with the SPACE parameter.

CYLINDERS

Specifies that the unit of space is a cylinder. Only valid with the SPACE parameter.

Additional Send Parameters for VM only

LRECL n

n is the logical record length of host file.

RECFM x

Recording mode for the host file. Values for x are F (fixed length) and V (variable length).

Additional Parameters for OS/400 only

DSTADDR(dstaddr)

This option specifies the destination address of the host to be used for the file transfer. The host name of the current session will be used as the default destination address. There is no need to specify this option when the host name is same as the actual final destination address of the host. Also, when you are using Proxy Server support, this option should specify the AS/400 name or the destination address reachable from the Proxy Server.

PROXYADDR(proxyaddr)

This option specifies the destination address of the Proxy Server to be used for the file transfer. This option needs to be specified, only if the user wants to use the Proxy Server support. The default port of the Proxy Server is 3470. However, this can be changed using the the option PROXYPORT(proxyport).

PROXYPORT(proxyport)

This option specifies the destination port of the Proxy Server to be used for the file transfer. The default port of the Proxy Server is 3470. This option needs to be specified, only if the user wants to use the Proxy Server support.

USERID(usr)

This option specifies the user ID to be used for the file transfer. There is no need to specify this option when it is invoked from the Host On Demand session. This option is provided for developing HACL applications without a GUI. Also, there is no need to specify it more than once per session.

PASSWORD(pwd)

This option specifies the password to be used for the file transfer. There is no need to specify this option when it is invoked from Host On Demand session. This option is provided for developing HACL applications without a GUI. Use this option along with the PASSWORD option.

UNICODE(encoding)

When used with an SBCS/DBCS session, it causes UNICODE to EBCDIC translation on a send and EBCDIC to UNICODE translation on a receive. You can specify either UCS2 or UTF8 as the encoding option; if neither is specified, UCS2 is the default encoding used for the transfer.

SRC

The option specifies the AS/400 file type to be used for the file send. If the host file does not exist, a new file is created with the file type "AS/400 Source physical file". This option is applicable only for files under the QSYS library-file system.

DTA

The option specifies the AS/400 file type to be used for the file send. If the host file does not exist, a new file is created with the file type "AS/400 Physical data file". This option is applicable only for files under the QSYS library-file system.

SAVF

The option specifies the AS/400 file type to be used for the file send. If the host file does not exist, a new file is created with the file type "AS/400 save file". If this option is specified, then the transfer mode must be BINARY. Also, this option is applicable only for files under the QSYS library-file system.

LRECL(n)

Logical record length. This option is applicable only for files under the QSYS library-file system.Valid values are as follows:

Any integer within the range 1 to 32766 for the filetype DTA

Any integer within the range 1 to 32754 for the filetype SRC

This option is ignored for the file type SAVF.

For OS/400, VM/CMS and CICS, the first option must be preceded by an open parenthesis '('.

Also, none of the aforesaid transfer options are mandatory. When the options are specified, the corresponding action is taken during the transfer.

The MVS host file name can be specified in any of the following formats:

dataSetName

dataSetName(memberName)

The VM/CMS host file name can be specified in any of the following formats:

fileName fileType

fileName fileType fileMode

The OS/400 host file name can be specified in any of the following formats:

LibraryName/FileName

LibraryName/FileName(MemberName)

/Dir1/.../DirX/FileName

This class cannot be constructed by the user, but an instance of it can be obtained through the ECLSession object.

Method Summary

void	Cancel() Cancels a file transfer which is in progress.
ECLXferBIDIServices	GetECLXferBIDIServices() Returns the ECLXferBIDIServices object associated with the ECLXfer instance.
int	GetMTUSize() Returns the current MTU Size used for file transfers.
ECLSession	GetParent() Get the parent of this ECLXfer which is an instance of ECLSession.
java.lang.String	GetPCCodePage() Returns the code page currently in use by file transfer.
int	GetTimeout() Returns the current time out value used for file transfers.
java.lang.Integer	getTraceLevel()
boolean	IsClear() Returns the clear flag which indicates whether a clear is sent to the host before a file transfer occurs.
java.lang.String[]	ListPCCodePages() Returns a list of valid code pages which can be used by file transfer.
void	ReceiveFile(java.lang.String srcName, java.lang.String targName, java.lang.String options) Receives a file from the host using the specified transfer options.
void	RegisterXferEvent(ECLXferListener listener) Registers an ECLXferListener for ECLXferEvents.
void	SendFile(java.lang.String srcName, java.lang.String targName, java.lang.String options) Sends a file to the host using the specified transfer options.
void	SetClear(boolean sendClear) Sets whether a clear is sent to the host before the file transfer is initiated.
void	SetMTUSize(int value) Sets the file transfer mtuSize to the specified value.
void	SetPCCodePage(java.lang.String codepage) Sets the file transfer code page to the specified code page.
void	SetTimeout(int value) Sets the file transfer time out to the specified value.
void	UnregisterXferEvent(ECLXferListener listener) Unregisters an ECLXferListener that was previously registered with the RegisterXferEvent() method.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

SendFile

public void SendFile(java.lang.String srcName,
                     java.lang.String targName,
                     java.lang.String options)
              throws ECLErr

Sends a file to the host using the specified transfer options.

Parameters:

srcName - Local file name

targName - Host file name

options - Send transfer options

The local file name will be automatically set in enclosing double quotes before it is passed to the operating system.

Throws:

ECLErr - Thrown if the file transfer is unsuccessful.

ReceiveFile

public void ReceiveFile(java.lang.String srcName,
                        java.lang.String targName,
                        java.lang.String options)
                 throws ECLErr

Receives a file from the host using the specified transfer options.

Parameters:

srcName - Host file name

targName - Local file name

options - Send transfer options

The local file name will be automatically set in enclosing double quotes before it is passed to the operating system.

Throws:

ECLErr - Thrown if the file transfer is unsuccessful.

Cancel

public void Cancel()

Cancels a file transfer which is in progress. If no transfers are in progress this method just returns.

RegisterXferEvent

public void RegisterXferEvent(ECLXferListener listener)

Registers an ECLXferListener for ECLXferEvents.

Parameters:

listener - ECLXferListener object which is notified when events occur.

See Also:

UnregisterXferEvent(com.ibm.eNetwork.ECL.event.ECLXferListener), ECLXferListener

UnregisterXferEvent

public void UnregisterXferEvent(ECLXferListener listener)

Unregisters an ECLXferListener that was previously registered with the RegisterXferEvent() method. If the listener is not currently registered, this method does nothing.

Parameters:

listener - ECLXferListener object which should be unregistered.

See Also:

RegisterXferEvent(com.ibm.eNetwork.ECL.event.ECLXferListener), ECLXferListener

getTraceLevel

public java.lang.Integer getTraceLevel()

SetPCCodePage

public void SetPCCodePage(java.lang.String codepage)

Sets the file transfer code page to the specified code page. The host code page in use by the session is not affected.

Parameters:

codepage - code page to be set. The value is ignored if it is not valid.

GetPCCodePage

public java.lang.String GetPCCodePage()

Returns the code page currently in use by file transfer.

Returns:

The code page currently in use by file transfer.

ListPCCodePages

public java.lang.String[] ListPCCodePages()

Returns a list of valid code pages which can be used by file transfer.

Returns:

String array of valid code pages.

SetTimeout

public void SetTimeout(int value)

Sets the file transfer time out to the specified value.

Parameters:

value - Timeout value used during transfers (seconds)

GetTimeout

public int GetTimeout()

Returns the current time out value used for file transfers.

Returns:

The time out value used during transfers (seconds)

SetMTUSize

public void SetMTUSize(int value)

Sets the file transfer mtuSize to the specified value. This call is valid only for 3270 File Transfer. The packet size is the maximum size that the client can use for inbound and outbound messages during host file transfer. The client notifies the host of this value. This value is also known as MTU file buffer size. In general a larger value will increase the speed of file transfers. However, if the host is configured to use a smaller packet size than the client, then increasing the client's packet size will not improve the speed of file transfers, unless the host's packet size is also increased. The valid range of values for packet size is 256 to 32767. The default is 2500. A value smaller than 256 will be changed to 256. A value larger than 32767 will be changed to 32767. An invalid value, such as a character string, will be changed to 2500.

Parameters:

value - MTU Size used during transfers

See Also:

GetMTUSize()

GetMTUSize

public int GetMTUSize()

Returns the current MTU Size used for file transfers. This applies to 3270 File transfer only. A value of 0 is returned if this is not a valid call.

Returns:

The MTU Size used during transfers

See Also:

SetMTUSize(int)

GetECLXferBIDIServices

public ECLXferBIDIServices GetECLXferBIDIServices()

Returns the ECLXferBIDIServices object associated with the ECLXfer instance. (Bi-directional sessions only)

Returns:

ECLXferBIDIServices instance for BIDI sessions, null otherwise.

SetClear

public void SetClear(boolean sendClear)

Sets whether a clear is sent to the host before the file transfer is initiated.

Parameters:

sendClear - Boolean to indicate whether to send a clear

IsClear

public boolean IsClear()

Returns the clear flag which indicates whether a clear is sent to the host before a file transfer occurs.

Returns:

Whether a clear is sent before file transfer

GetParent

public ECLSession GetParent()

Get the parent of this ECLXfer which is an instance of ECLSession.

Returns:

The parent ECLSession.