Receive File – Function 91

This function transfers a file from the Host to the PC running the Windows HLLAPI application. The file transfer can be synchronous (dedicated) or asynchronous (call-and-return). See the “Remarks” section for information on asynchronous file transfer.

Prerequisite functions

None.

Function call

WinHLLAPI(hWnd,RECEIVEFILE,lpbyString,lpwLength,lpwReturnnCode)

WinHLLAPIAsync(hWnd,RECEIVEFILE,lpbyString,lpwLength,lpwReturnnCode)

Call parameters

Parameter	Description
Data String	RECEIVE command parameters.
Data Length	Length of Data String. NA if session option EOT is specified.
PS Position	NA

Return code

Code	Description
WHLLOK	File transfer started successfully (asynchronous mode only).
WHLLNOTCONNECTED	Parameter error or Data Length is zero or greater than 128.
WHLLFTXCOMPLETE	The file transfer completed (synchronous mode only).
WHLLFTXSEGMENTED	Transfer completed with one or more segmented records (synchronous mode only).
WHLLSYSERROR	The function failed due to a system error.
WHLLTRANSABORTED	The file transfer aborted, either due to the user entering CTRL+BREAK or (if a timeout was set by Set Session Parameters, function 9) because the timeout period expired.
WHLLINVALIDFUNCTIONNUM	Invalid function number.
WHLLFILENOTFOUND	PC file not found.
WHLLACCESSDENIED	Access denied to PC file.
WHLLMEMORY	Insufficient memory.
WHLLINVALIDENVIRONMENT	Invalid environment.
WHLLINVALIDFORMAT	Invalid format.

Remarks

This function is affected by the session options STRLEN/STREOT, EOT=c, QUIET/NOQUIET, and TIMEOUT=0/TIMEOUT=c. See Set Session Parameters (function 9) for details.

You cannot use this function on 5250 sessions, 5250 printer sessions, and 3270 printer sessions. Only one file transfer operation is supported at a time, regardless of the number of Host sessions accessed by your Windows HLLAPI application.

Data String should contain the RECEIVE command parameters that you would normally enter at the DOS prompt. For example, to receive the file SALES.RPT on your PC from the CMS file SLS REPRT A on the Host session with the short name session ID of “E:”

•

Data String SALES.RPT E:SLS REPRT A (ASCII CRLF

•

Data Length 35

Asynchronous Mode

When asynchronous mode is enabled by calling WinHLLAPIAsync, this function initiates the file transfer and immediately returns control to your Windows HLLAPI application. This frees your application to perform other tasks while the file transfer is occurring.

Since asynchronous mode returns control immediately, you must use Windows version 3.x message notification to determine the completion status of the file transfer. Use the RegisterWindowsMessage( ) function to register the message “WinHLLAPIAsyncFileTransfer”. The message notification is in the format:

(wMsgID, wParm, lParm)

where

wMsgID	Is the message ID returned by RegisterWindowsMessage.
wParm	Is the status indicator: the high byte contains the short name session ID, the low byte contains the status. If the low byte is zero, the file transfer is still in progress. If the low byte is one, the file transfer has completed.
lParm	Depends upon the low byte value of wParm. If the low byte of wParm is zero (in progress), lParm is the number of bytes that have been transferred. If the low byte of wParm is one (completed), lParm is the two-digit Host TRANS code.