[ Previous | Next | Contents | Search ]
3270 Host Connection Program 2.1 and 1.3.3 for AIX: Guide and Reference

RECEIVE FILE (91)

Purpose

Transfers a file from the host session to the workstation session.

Prerequisite Calls

When calling the RECEIVE FILE function, you must not currently:

Syntax

hllc (func, apistring, len, ret)
int *func;
char *apistring;
int *len;
int *ret;

Supplied Parameters

Supply the following parameters to invoke the RECEIVE FILE function:

func Specifies the number of the function called; must be 91 for the RECEIVE FILE function.
len Specifies the length, in number of bytes, of the data string. This parameter is overridden if in end of transmission (EOT) mode.
ret Does not apply to this function.
apistring Specifies the same RECEIVE parameters that are used for the fxfer command; must be between 1 and 255 bytes. The data string can contain:
Option Description
-a Appends the file designated by the SourceFile parameters of the fxfer command to that designated by the DestFile parameter if the destination file exists. This flag is ignored and the destination file is created if the file designated by the Destfile parameter does not exist.
-n Specifies short session name of a previously defined session. It is a single character in the range of a to z. Capital letters are treated as lowercase letters.
-r Specifies replacement of an existing file on the local system. This is done when the transfer is successful. If this option is specified and the file does not exist, a new file is created. Or, if this option is not specified and the file exists, an error condition has occurred.
-t Performs EBCDIC to ASCII translation for a file. The national language to be used is defined by the -X option. The -t option assumes the file is a text file. The new-line character is the line delimiter.
-F Specifies fixed-length records.
-H Specifies the type of host environment; the values can be CMS, TSO, CICS, and VSE.
-I Specifies file transfer options placed directly within the IND$FILE command. This option also allows user comments placed within the file transfer command to the host. For example: -I "FILE=TS) This is a comment"
-T Performs EBCDIC-to-ASCII translation for a file to be stored in DOS format.
-X Specifies the AIX code set support for EBCDIC-to-ASCII translation. If this option is not specified, the code set specified by the system locale is used. The supported code sets are IBM-850, IBM-932, ISO8859-1, ISO8859-7, ISO8859-9, IBMeucJP, IBM-eucKR, and IBM-eucTW.

Examples

The following are the examples of the data string used by the RECEIVE FILE function:

To download the user.test file from the TSO environment to the AIX operating system by using the HCON profile session a, enter:

-n a -H TSO -r user.test samplefile1

To download the VM file, test file a and append it to the local AIX operating system as mydir/samplefile file, enter:

-n a -H CMS -t -a test file a mydir/samplefile

Returned Parameters

ret The following codes are valid:
0 Specifies that the file transfer was complete.
2 Specifies that a parameter error occurred or you specified a data string length that is too short (0 bytes) or too long (more than 255 bytes) for the HLLAPI buffer; indicates that the file transfer was unsuccessful.
11 Specifies that a session already connected; the resource is not available.
200-368 Specifies file transfer errors. For a complete list of file transfer errors, refer to Appendix A.

Remarks

The RECEIVE FILE function transfers a file from the host session to the workstation session. The interface parameter is a subset of the fxfer command used in the AIX 3270 Host Connection Program (HCON). The file-transfer process runs in synchronous mode.

Two sets of options under the SET SESSION PARAMETERS (9) function are related to this function:

For more information, see session options 1 and 2 of the SET SESSION PARAMETERS (9) function.

If you are linked to the host session already, you receive a return code of 11. Therefore, if you are connected with the CONNECT PRESENTATION SPACE (1) function to the host session, you must disconnect using the DISCONNECT PRESENTATION SPACE (2) function.

Related Information

CONNECT PRESENTATION SPACE (1) function, DISCONNECT PRESENTATION SPACE (2) function and SET SESSION PARAMETERS (9) function.


[ Previous | Next | Contents | Search ]