[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]
Communications Technical Reference, Volume 1

g32_fxfer Function

Purpose

Invokes a file transfer.

Libraries

HCON Library
File Transfer Library (libfxfer.a)
C (libg3270.a)
Pascal (libg3270p.a)
Fortran (libg3270f.a)

C Syntax

#include <g32_api.h>
#include <fxfer.h>
g32_fxfer (asxfer)
struct g32_api *as;
struct fxc *xfer;

Pascal Syntax

const
%include /usr/include/g32const.inc
%include /usr/include/g32fxconst.inc
type
%include /usr/include/g32types.inc
%include /usr/include/fxhfile.inc
function g32fxfer(var as : g32_api; var xfer : fxc) : integer; external;

FORTRAN Syntax

INTEGER G32FXFER, RC, AS(9)
EXTERNAL G32FXFER
CHARACTER*XX SRCF, DSTF, INPUTFLD, CODESET
INTEGER FLAGS,RECL,BLKSIZE,SPACE,INCR,UNIT
RC = G32FXFER(AS,SCRFDSTFFLAGSRECLBLKSIZESPACE,
   + INCRUNITINPUTFLDCODESET)

Description

The g32_fxfer function allows a file transfer to take place within an API program without the API program having to invoke a g32_close and relinquish the link. The file transfer is run in a programmatic fashion, meaning the user must set up the flag options, the source file name, and the destination file name using either the programmatic fxfer fxc structure for C and Pascal or the numerous variables for FORTRAN. The g32_fxfer function will detach from the session without terminating it, run the specified file transfer, and then reattach to the session.

If a g32_alloc function has been issued before invoking the g32_fxfer command, be sure that the corresponding g32_dealloc function is incorporated into the program before the g32_fxfer function is called.

The status of the file transfer can be checked by using the cfxfer file-transfer status check function after the g32_fxfer function has been invoked.

HCON application programs using the Pascal language interface must include and link both the C and Pascal libraries. Application programs using the FORTRAN language for the HCON API must include and link both the C and FORTRAN libraries.

C Parameters

as Specifies a pointer to the g32_api structure. Status is returned in this structure.
xfer Specifies a pointer to the fxc structure defined in the fxfer.h file.

Pascal Parameters

as Specifies a record of type g32_api.
xfer Specifies a record of type fxc within the fxfer.inc file.

FORTRAN Parameters

AS Specifies the g32_api equivalent structure as an array of integers.
SRCF Specifies a character array of XX length containing the source file name.
DSTF Specifies a character array of XX length containing the destination file name.
FLAGS Contains the option flags value, which is the sum of the desired option values listed below:
1 Upload
2 Download
4 Translate On
8 Translate Carriage Return Line Feed
16 Replace
32 Append
64 Queue. This option may be specified by the user, but it is blocked by the G32FXFER command.
128 Fixed Length Records
256 Variable Length Records
512 Undefined Length (TSO only)
1024 Host System TSO
2048 Host System CMS
4096 Host System CICS/VS
8192 Host System VSE/ESA
RECL Specifies the logical record length.
BLKSIZE Specifies the block size (TSO only).
SPACE Specifies the allocation space (TSO only).
INCR Specifies the allocation space increment (TSO only).
UNIT Specifies the unit of allocation (TSO only), which is:
-1 Number of TRACKS
-2 Number of CYLINDERS.
A positive number indicates the number of blocks to be allocated.
                         
INPUTFLD Specifies the host input table field.
CODESET Specifies an alternate code set to use for ASCII to EBCDIC and EBCDIC to ASCII translations. The following code sets are supported:
CHAR( 0) Uses current operating system ASCII code page.
IBM850 Uses IBM code page 850 for translation in a single byte code set (SBCS) environment.
IBM932 Uses IBM code page 932 for translation in a double byte code set (DBCS) environment.
ISO8859-1 Uses ISO 8859-1 Latin alphabet number 1 code page.
ISO8859-7 Uses ISO 8859-7 Greek alphabet.
ISO8859-9 Uses ISO 8859-9 Turkish alphabet.
IBMeucJP Uses IBM Extended UNIX Code for translation in the Japanese Language environment.
IBMeucKR Korean language.
IBMeucTW Traditional Chinese language.
Notes:
  1. All FORTRAN character array strings must be null-terminated. For
  2. example:
    SRCF = 'rtfile'//CHAR(0)
  3. The Host System VSE is not supported in the DBCS environment.
  4. The unique DBCS file transfer flags are not supported by this function.

Return Values

0 Indicates successful completion. The user may call the cfxfer function to get the status of the file transfer.
1 Indicates the file transfer did not complete successfully. The user may call the cfxfer function to get the status of the file transfer.
-1 Indicates the g32_fxfer command failed while accessing the link. The errcode field in the g32_api structure is set to an error code identifying the error. The xerrinfo field can be set to give more information about the error.

Examples

The following example fragment illustrates the use of the g32_fxfer function in an api_3270 mode program in C language:

#include <g32_api.h>  /* API include file */ 
#include <fxfer.h>    /* file transfer include file */
main()
{
  struct g32_api *as,asx;
  struct fxc *xfer;  struct fxs sxfer;
  int session_mode=MODE_3270;
  char *aixfile="/etc/motd";
  char *hostfile="test file a";
  char sessionname[30],uid[30],pw[30];
  int mlog=0,ret=0;
  as = &asx;
  sessionname = '\0';  /* We are assuming SNAME is set */
  .
  .
  ret=g32_open(as,mlog,uid,pw,sessionname);
  printf("The g32_open return code = %d\n",ret);
  .
  .
  /* Malloc space for the file transfer structure */
  xfer = (struct fxc *) malloc(2048);
  /* Set the file transfer flags to upload, 
     replace, translate and Host CMS */
  xfer->fxc_opts.f_flags = FXC_UP | FXC_REPL | FXC_TNL |
     FXC_CMS;
  xfer->fxc_opts.f_lrecl = 80; /* Set the Logical Record length
                                  to 80 */
   xfer->fxc_opts.f_inputfld = (char *)0;   /* Set Input Field
                                               to NULL        */
   xfer->fxc_opts.f_aix_codepg = (char *)0; /* Set Alternate
                                               Codepg to NULL */
   xfer->fxc_src = aixfile;     /* Set the Source file name to
                                   aixfile */
  xfer->fxc_dst = hostfile;   /* Set the Destination file name
                                   to hostfile */
   ret=g32_fxfer(as,xfer);
  printf("The g32_fxfer return code = %d\n",ret);
  /* If the file transfer completed then get the status code of
     the file transfer */
  if ((ret == 0) || (ret == 1)) {
     ret = cfxfer(&sxfer);
     if (ret == 0) {
        printf("Source file:      %s\n",sxfer.fxs_src);
        printf("Destination file:      %s\n", \
      sxfer.fxs_dst);
        printf("Byte Count:      %d\n",sxfer.fxs_bytcnt);
        printf("File transfer time:   %d\n",sxfer.fxs_ctime);
        printf("Status Message Number:   %d\n",sxfer.fxs_stat);
        printf("System Call error number:%d\n",sxfer.fxs_errno);
     }
  }
  .
  .
  .
  ret=g32_close(as);
  printf("The g32_close return code = %d\n",ret);
  return(0);
}

The following example fragment illustrates the use of the g32_fxfer function in an api_3270 mode program in Pascal language.

program test1(input,output);
const%include /usr/include/g32const.inc
%include /usr/include/fxconst.inc
type
%include /usr/include/g32hfile.inc
%include /usr/include/g32types.inc
%include /usr/include/fxhfile.inc
var
  as:g32_api;
  xfer:fxc;
  sxfer:fxs;
  ret,sess_mode,flag:integer;
  session,timeout,uid,pw:stringptr;
  source,destination:stringptr;
begin
  sess_mode = MODE_3270;
  flag := 0;
  { Initialize API stringptrs and create space }
  new(uid,8);
  uid@ := chr(0);
  new(pw,8);
  pw@ := chr(0);
  new(session,2);
  session@ := 'a'; { Open session a }
  new(timout,8);
  timeout := '60';
  { Call g32openx and open session a }
  ret := g32openx(as,flag,uid,pw,session,timeout);
  writeln('The g32openx return code = ',ret:4);
  .
  .
  .
  { Set up the file transfer options and file names  }
  new(source,1024);
   source := 'testfile';  { Source file, assumes testfile exists
            in the current directory }
   new(destination,1024);
   destination := 'testfile'; { Destination file, TSO file 
       testfile }
  { Set flags to Upload, Replace, Translate and Host TSO  }
  xfer.fxc_opts.f_flags := FXC_UP + FXC_TSO + FXC_REPL + \        FXC_TNL;
  xfer.fxc_src := source;
  xfer.fxc_dst := destination;
  {Call the g32_fxfer using the specified flags and file names}
  ret := g32fxfer(as,xfer);
  writeln('The g32fxfer return code = ',ret:4);
  { If g32_fxfer returned with 1 or 0 call the file transfer \        status check function }
  if (ret >= 0) then begin
     ret := pcfxfer(sxfer);
     if (ret = 0) then begin
        writeln('Source file:      ',sxfer.fxs_src@);
        writeln('Destination file:   ',sxfer.fxs_dst@);
        writeln('File Transfer Time:   ',sxfer.fxs_ctime@);
        writeln('Byte Count:      ',sxfer.fxs_bytcnt);
        writeln('Status Message Number:   ',sxfer.fxs_stat);
        writeln('System Call Error Number: ',sxfer.fxs_errno);
     end;
  end;
  .
  .
  .
  { Close the session using the g32close function }
  ret := g32close(as);
  writeln('The g32close return code = ',ret:4);
  end.

The following example fragment illustrates the use of the g32_fxfer function in an api_3270 mode program in FORTRAN language:

   INTEGER G32OPENX,G32FXFER,G32CLOSE,FCFXFER
   INTEGER RET,'AS(9)FLAG
   EXTERNAL G32OPENX
   EXTERNAL G32FXFER
   EXTERNAL G32CLOSE
   EXTERNAL FCFXFER
   CHARACTER*8 UID
   CHARACTER*8 PW
   CHARACTER*2 SESSION
   CHARACTER*8 TIMEOUT
   CHARACTER*256  SRCF
   CHARACTER*256  DSTF
   CHARACTER*256  SRC
   CHARACTER*256  DST
   CHARACTER*64   INPUTFLD
   CHARACTER*8    CODESET
   CHARACTER*40   TIME
   INTEGER BYTCNT,STAT,ERRNO,TIME
   INTEGER FLAGS,RECL,BLKSIZE,SPACE,INCR,UNIT
C   Set up all FORMAT statement
1   FORMAT("THE G32OPENX RETURN CODE = ",I4)
2   FORMAT("THE G32FXFER RETURN CODE = ",I4)
3   FORMAT("THE G32CLOSE RETURN CODE = ",I4)
4   FORMAT("THE FCFXFER  RETURN CODE = ",I4)
5   FORMAT("--------------------------------------")
10   FORMAT("SOURCE FILE: ",A)
11   FORMAT("DESTINATION FILE: ",A)
12   FORMAT("BYTE COUNT: ",I10)
13   FORMAT("TIME: ",A)
14   FORMAT("STATUS MESSAGE NUMBER: ",I10)
15   FORMAT("SYSTEM CALL ERROR NUMBER: ",I10)
C   Set up all character values for the G32OPENX command
   UID = CHAR(0)
   PW = CHAR(0)
   SESSION = 'z'//CHAR(0)
   TIMEOUT = '60'//CHAR(0)
   FLAG = 0
   SRCF = 'testcase1'//CHAR(0)
   DSTF = '/home/test.case1'//CHAR(0)
C   Source and Destination files for the fcfxfer status
C   check command
   SRC = CHAR(0)
   DST = CHAR(0)
C   Set Input Field to NULL
   INPUTFLD = CHAR(0)
C   Set Alternate AIX codeset to NULL
   CODESET = CHAR(0)
C   Set the G32FXFER file transfer flags and options
C   Take the defaults for Logical Record Length, Block Size,
C   and Space
   RECL = 0
   BLKSIZE = 0
   SPACE = 0
C   Set FLAGS to download (2), translate(4), and Host
TSO(1024)
   FLAGS = 1030
C   Call G32OPENX
   RET = G32OPENX(AS,FLAG,UID,PW,sessionname,TIMEOUT)
   WRITE(*,1) RET
   .
   .
   .
C   Call G32FXFER
   RET = G32FXFER(AS,SRCF,DSTF,FLAGS,RECL,BLKSIZE,SPACE
       +         INCR,UNIT,INPUTFLD,CODESET)
   WRITE(*,2) RET
   .
   .
   .
C   Call G32CLOSE
   RET = G32CLOSE(AS)
   WRITE(*,3) RET
C   Call FCFXFER for file transfer status output
   RET = FCFXFER(SRC,DST,BYTCNT,STAT,ERRNO,TIME)
   WRITE(*,4) RET
   WRITE(*,5)
   WRITE(*,10) SRC
   WRITE(*,11) DST
   WRITE(*,12) BYTCNT
   WRITE(*,13) TIME
   WRITE(*,14) STAT
   WRITE(*,15) ERRNO
   WRITE(*,5)
   STOP
   END

Implementation Specifics

The g32_fxfer function is part of the Host Connection Program (HCON).

The g32_fxfer function requires one or more adapters used to connect to a host.

This function requires that the Host-Supported File Transfer Program (IND$FILE or its equivalent) be installed on the host.

Files

/usr/include/fxfer.h Contains the file-transfer include file with structures and definitions for C.
/usr/include/fxconst.inc Contains the Pascal fxfer function constants.
/usr/include/fxhfile.inc Contains Pascal file-transfer invocation include file.
/usr/include/g32_api.h Contains data structures and associated symbol definitions.
/usr/include/g32const.inc Defines Pascal API constants.
/usr/include/g32hfile.inc Defines Pascal API external definitions.
/usr/include/g32types.inc Defines Pascal API data types.

[ Next Article | Previous Article | Book Contents | Library Home | Legal | Search ]