File Transfer

Introduction#

UPSTREAM includes an optional file transfer facility that can be used to transfer files between the z/OS Storage Server and the Client workstation/server, referred to in this chapter as “host” and “client” respectively. The transfer request can be initiated from either the z/OS Storage Server or the Client.

Only one file can be transferred at a time. If it is a text (printable) file, UPSTREAM includes ASCII-EBCDIC translation and automatic record conversion. You may also transfer binary files.

One example use of this very flexible yet simple file transfer facility is the transmission of UPSTREAM log files from the Client to the z/OS Storage Server, from where they can be centrally analyzed and printed or archived. Another example may be a simple “file distribution” system, where an Client file is transmitted to the z/OS Storage Server and then re-transmitted back to numerous other Clients.

The UPSTREAM file transfer facility has many other practical uses and can usually be employed whenever you need to transfer files from host-to-client, or vice versa.

Implementation#

The file transfer facility is very easy to implement. It requires no additional software or communication configuration, because it uses the same client-to-host connection as a normal backup. If you already have a Client configured for UPSTREAM, you can do file transfers simply by defining an appropriate file transfer profile.

File Transfer Profiles#

One or more special profiles are required to support the file transfer facility. These profiles are fully described in UPSTREAM Profiles”, but in summary:

• A file transfer profile has the TRANSFER attribute specified
  
• The DASD attribute is required if client-to-host transfers will go directly to z/OS disk
  
• The TAPE attribute is required if client-to-host transfers will go directly to z/OS tape
  
• The DASDPREF and TAPEPREF attributes can be used to supply name of the z/OS output data set on client-to-host transfers
  

Although file transfer profiles share similar attributes to normal backup profiles, they cannot be used for anything other than file transfers.

Client-to- Host Transfers#

UPSTREAM Client Input File

The name of the UPSTREAM Client input file to be transferred to the z/OS Storage Server is specified at execution time, as described in Initiating File Transfers.

If it is a text file, an ASCII-to-EBCDIC translation will take place by default.

If you are transmitting a non-text (binary) file, you should turn off the “Translation to EBCDIC” and “Each line is a separate record” options. Unless you have detailed knowledge of the format of the binary file, the transferred file will be of use only if you later transfer it back to the same (or other) Clients, perhaps as part of a simple “file distribution” system.

UPSTREAM z/OS Storage Server Output File

The name and location of the z/OS Storage Server output file can be controlled either through the special file transfer profile (as described earlier), or this information can be supplied at execution time.

• If the z/OS Storage Server output file is to be a sequential disk/tape data set it will be allocated as a new data set and cataloged by UPSTREAM.
  
• If it is to be the next generation of a GDG, you must specify “(+1)” at the end of the name, e.g., “A.B.C(+1)”.
  
• If it is a member of an existing PDS, you must specify a member name, e.g., “A.B.C(MEMBER1)”. The PDS must be pre-allocated and it must have the proper DCB characteristics (see below). UPSTREAM never allocates a new PDS.
  

The z/OS Storage Server output file will have the following DCB characteristics:

• RECFM: Since Client files may have variable-length records, the z/OS Storage Server output data set will be in variable blocked format (RECFM=VB)
  
• LRECL: This will be the USERECORDSIZE specified at the Client when the transfer is initiated (+4 for the variable format length fields)
  
• BLKSIZE: This will be the value of DASDBLK in the associated file transfer profile, which must be at least USERECORDSIZE+8.
  

The size of the individual records written to the z/OS Storage Server output file depends on various options.

Since text files are usually broken into records delimited by a CR/LF (just LF on UNIX systems), by default UPSTREAM will scan for those delimiters and transmit the individual records (with the delimiters removed). This results in an z/OS file with the same number and size of records as the Client file.

This option can be overridden, in which case the transmitted file is considered to be a continuous set of data bytes and delimiters, which are not removed. Since z/OS requires that data sets consist of individual records, UPSTREAM breaks the transmitted data in records of the size specified by USERECORDSIZE. For example, if USERECORDSIZE is 6000, the z/OS data set consists of variable length records, all of which are 6000 bytes in length (except the last one).

Host-to-Client Transfers#

UPSTREAM z/OS Storage Server Input File

If it is a text file, an EBCDIC to ASCII translation will take place by default. Since Client text files are usually broken into records delimited by a CR/LF (just LF on UNIX systems), UPSTREAM defaults to transmitting the individual records from the z/OS Storage Server data set with the appropriate delimiters inserted. This results in a Client output file with the same records as the z/OS Storage Server input file.

If you are transmitting a non-text binary file, you must turn off the “Translation to EBCDIC” and “Each line is a separate record” options so that the z/OS Storage Server file is transmitted back to the Client without translation and without delimiters inserted.

The name of the z/OS Storage Server input file to be transmitted to the Client would normally be specified at execution time. UPSTREAM automatically allocates the specified input data set using the z/OS catalog; you do not need to specify its location on disk or tape.

If the z/OS Storage Server input file is omitted at execution time, UPSTREAM chooses the file that was last transmitted to z/OS under the same the profile name. This file is then transmitted back to the specified Client, which may be either the same Client from where it came, or (in the case of a simple “file distribution” system) back to a different Client.

This option of omitting the z/OS Storage Server input filename at execution time only works, however, if UPSTREAM is recording your file transfer operations (see Maintaining Records of Your Client-to-Host Transfers). If it is not, then you must specify the z/OS Storage Server input file name.

UPSTREAM Client Output File

The name of the Client output file is specified at execution time. See Initiating File Transfersfor more details.

Maintaining Records of Your Client-to-Host Transfers#

On client-to-host file transfers only, UPSTREAM can optionally record information about each file transfer operation in the CATALOG repository data set. This information is logged under the file transfer profile name and allows you to query and report on client-to-host file transfer activity. See the “Record on Host” option in Step 3: File Transfer Specification and also the HOSTRECORD= option.

Deleting the Input File#

On file transfers in either direction, you can opt to delete the input file after the transfer has taken place. This is controlled by the “Delete local file after transfer” option.

z/OS Security

If SECLVL=1 or more is specified in the UPSTREAM configuration (see Configure the MAIN Options), a userid and password must be associated with the file transfer request.

Access to z/OS Storage Server data sets are verified under that userid, as follows:

• On client-to-host transfers, the userid must have CREATE authority to the z/OS output data set.
  
• On host-to-client transfers, the userid must have READ authority to the z/OS input data set.
  

Initiating File Transfers#

File transfers in either direction can be initiated in several ways:

• From the Client, using the GUI or Director panels (see the UPSTREAM Client Guide for details)
  
• From the z/OS Storage Server, using USTBATCH.
  

The remainder of this chapter shows how to use the UPSTREAM TSO/ISPF dialogs to generate a USTBATCH batch job to initiate a file transfer. USTBATCH JCL can also be constructed manually, if desired, although this is not recommended. See “z/OS Initiation with USTBATCH for more information on USTBATCH.

Step 1: Select USTBATCH - z/OS Storage Server Initiated Services

Enter the UPSTREAM TSO/ISPF dialog via your installation defined method (see Make the UPSTREAM ISPF Dialogs Easily Available). From the main menu, specify option number 1, (“USTBATCH”), and press ENTER.

The next menu to appear allows for the specification of the USTBATCH parameters required to initiate the file transfer. The parameters of most interest are explained below. Note that we are selecting an Action of 4 “File Transfer”.

The parameters specified in the panel above are explained here. For a full description of all parameters, see z/OS Initiation with USTBATCH.

Beginning with UPSTREAM z/OS 3.9.1, the UPSTREAM started task and USTBATCH may now use TCP/IP to initiate requests. The SNA parameters described further below are no longer required but may still be used. They are required for users of UPSTREAM z/OS 3.9.0 and earlier and are listed here for their reference.

USTBATCH to Started Task TCP/IP Parameters (Preferred):

HOSTDNS

The DNS name of the LPAR hosting your UPSTREAM started task. Mutually exclusive with the HOSTIP parameter.

HOSTIP

The IP address of the TCP/IP stack on the LPAR hosting your UPSTREAM started task. Mutually exclusive with the HOSTDNS parameter.

HOSTPORT

The IP port number of the UPSTREAM started task. If omitted, the default is 1972. This parameter may be used with either the HOSTDNS or HOSTIP parameters.

USTBATCH to Started Task VTAM SNA Parameters (UPSTREAM version 3.9.0 and prior):

APPLPREF

The 5-character prefix of the VTAM APPLID to be used by USTBATCH for its communications with the UPSTREAM started task.

USAPPL

The VTAM APPLID of the UPSTREAM started task.

TPNAME

The Transaction Program Name to be used during LU 6.2 communications.

LOGMODE

The VTAM LOGMODE to be used for communicating with the UPSTREAM started task.

Additional Parameters. (These parameters are used with any version of UPSTREAM and may be used with either TCP/IP or SNA USTBATCH to Started Task communication.):

CONV

This controls whether or not the USTBATCH job should wait for the completion of the request submitted to the started task, or end immediately after the request is accepted.

WTOCOMP

Allows a WTO completion message to be issued to the z/OS system operator when the request finishes.

Started Task to Client Target System parameters:

TCP/IP ADDR

The IP address of the Client that will participate in this file transfer. Note that this parameter is mutually exclusive with the TARGNAME, DNSNAME, and TARGLU keywords.

TCP/IP PORT

The TCP port number of the Client that will participate in this file transfer.

ACTION

Controls which UPSTREAM function is to be performed by this set of generated statements. In our preceding example, ACTION=4 specifies a file transfer request.

Step 3: File Transfer Specification#

The next menu to appear allows you to provide details of the file transfer, including the name of the special profile that will control the operation and the direction of the intended file transfer (“send to host” or “receive from host”).

It is in this panel that you also provide the name of the Client file that acts as either the input file (on client-to-host transfers) or the output file (on host-to-client transfers). You can also use this panel to provide the name and location (disk or tape) of the z/OS Storage Server file, overriding the options setup in the profile. At the bottom of the panel you find the other options mentioned earlier in this chapter, such as “Translate to EBCDIC”, “Record on host” and “Delete local file after transfer”.

On completion of the preceding menu, press the ENTER key, then press the PF3 key to return to the USTBATCH Specification menu previously seen in Step 2 : USTBATCH Specification. We can now generate the z/OS JCL that is used to invoke the USTBATCH utility program that submits the request to the UPSTREAM started task for processing. You do this by specifying “GEN” on the command line and pressing the ENTER key.

The menu below then allows you to tailor the USTBATCH JCL to match your installation's requirements. As a minimum, you should alter the JCL to provide a valid mainframe JOBCARD. You will also need to include a STEPLIB to point to the UPSTREAM load library if it is not in the Linklist. If you use the DNSNAME= option to address the Client, you may also need a SYSTCPD DD statement.

Select option “2” on the command line of the preceding menu (then press ENTER) to review and optionally edit the generated USTBATCH JCL and parameters via a standard ISPF Edit scree

Step 7: Submitting and Monitoring the USTBATCH Job

The USTBATCH job can then be submitted for batch processing, either immediately, or it can be saved to a member in a PDS for later submission (manually, or through your job scheduling system).

Once it has been initiated, the executing request can then be monitored via the UPSTREAM ISPF STATUS panel (Option #2), or via the UPSTREAM STATUS operator command (UPSTREAM Operation).