z/VSE - Group home

How to transfer an AWS tape image via 3270 IND$FILE transfer to z/VSE

By Jens Remus posted Tue November 24, 2020 08:50 AM

  

In this post I am going to take you through the steps how to transfer a tape image in AWS-format via 3270 IND$FILE transfer into a VSAM ESDS file. From there the contents of the tape image can then for example be accessed using the z/VSE Virtual Tape function (VTAPE). This for instance allows to install additional components or products from the z/VSE extended base tape or z/VSE optional product tape images. The transfer is performed using a terminal emulator via the Host Transfer File (HTF).

The preferred method to transfer a tape image to z/VSE is of course the use of a TCP/IP stack and the FTP protocol. In conjunction with the z/VSE Virtual Tape Server the tape image could even be accessed from a remote server without prior transfer into a VSAM ESDS file. But without a networking device and connection as well as a TCP/IP stack at hand, the following instructions allow to access tape images in AWS-format.

By the way: A similar approach to transfer PTFs via 3270 IND$FILE transfer into the PTF file is described in the z/VSE System Upgrade and Service manual, appendix Apply PTFs from the Internet, section Transferring the PTF to Disk using 3270 IND$FILE Transfer.

In the following example I am going to transfer the z/VSE extended base tape VSE620XB.AWS into the default VSAM ESDS VTAPE file. As 3270 terminal emulator I am going to use IBM Personal Communications on Windows. If you use another terminal emulator you may need to adapt the 3270 file transfer instructions (step 4 below) accordingly.The same instructions may be used with:

  • the z/VSE base tape image to perform Fast Service Upgrade (FSU) (see z/VSE System Upgrade and Service manual) or to copy it onto a physical tape, e.g. using the DITTO/ESA function Tape to Tape TT (see DITTO/ESA User’s Guide and Reference manual, SH19-8221-02, available from the IBM Publications Center), to perform an installation on another system with the physical tape,
  • the z/VSE extended base tape image to e.g. install the z/VSE Generation Feature (see z/VSE Installation manual, chapter "Doing Optional Installation Tasks - in LPAR mode and under z/VM", section Overview of the Generation Feature),
  • the z/VSE extended base tape or z/VSE optional product tape images to install any optional products (see z/VSE Installation manual, chapter "Doing Optional Installation Tasks - in LPAR mode and under z/VM", sections Overview of Installing Additional Programs and Installing Additional VSE Programs), or
  • any tape image in AWS format to copy it onto physical tape, e.g. using the DITTO/ESA function Tape to Tape TT (see DITTO/ESA User’s Guide and Reference manual, SH19-8221-02, available from the IBM Publications Center).

Following is an outline of the steps to transfer an AWS tape image via 3270 IND$FILE transfer via the Host Transfer File (HTF) into a VSAM ESDS VTAPE file:

  1. Define additional space to the VSAM user catalog if necessary
  2. Create/Resize the Host Transfer File if necessary
  3. Create a VSAM ESDS VTAPE file if necessary
  4. Transfer the AWS tape image into the Host Transfer File
  5. Copy the AWS tape image from the Host Transfer File into the VSAM ESDS VTAPE file

The preparatory steps 1 to 3 show how to define the necessary resources in z/VSE. The steps 4 and 5 show how to perform the actual transfer of the tape image in AWS-format via the Host Transfer File (HTF) into a VSAM ESDS file for subsequent use with the z/VSE Virtual Tape function (VTAPE).

1. Define additional space to the VSAM user catalog if necessary

By default the VSAM user catalog VSESP.USER.CATALOG does not have enough space to hold the z/VSE base tape image, z/VSE extended base tape image, or z/VSE optional product tape image. Note that the tape image needs to be accommodated twice. One intermediate copy in the Host Transfer File (HTF) and another final copy in a VSAM ESDS VTAPE file. Therefore you may need to define additional space to your VSAM user catalog(s) that hold the Host Transfer File and the VSAM ESDS VTAPE file.

Note that it is also possible to use a (temporary) custom VSAM user catalog for both the Host Transfer File (HTF) as well as the VSAM ESDS VTAPE file.

For further details refer to the z/VSE Guide for Solving Problems manual, chapter Handling Resource Constraint Conditions, section "Full Conditions", subsection VSE/VSAM Space Full Condition, task Defining Additional VSE/VSAM Space. The process how to define additional space using the Interactive Interface dialogs is described in the z/VSE Administration manual, chapter Managing VSE/VSAM Files and Catalogs, section Displaying or Processing a VSE/VSAM Catalog or Space, subsection Define Space.

2. Create/Resize the Host Transfer File if necessary

Use the z/VSE provided job skeleton SKIWSTF from ICCF library 59 to (re-)define the Host Transfer File (HTF). Note that the following instructions will delete an existing Host Transfer File including any of its contents.

  1. Copy the job skeleton SKIWSTF from ICCF library 59 to your ICCF primary library.

  2. Edit the job skeleton to complete the job stream:

    • Change the -V001- variable. Specify the volume(s) which have free VSAM space available for the Host Transfer File in the respective VSAM user catalog.

    • Change the primary and secondary allocation to at least RECORDS (50000 50000). Otherwise storing the tape image causes the allowed maximum number of extents to be exceeded.

    • If you want to access the Host Transfer File from more than one CICS partition concurrently, change SHAREOPTIONS (2) to SHAREOPTIONS (4).

    • Optionally change the catalog VSESP.USER.CATALOG and its file label VSESPUC to the respective values of your own VSAM user catalog.

  3. Enter @DTRSEXIT into the ICCF editor command line to delete all descriptive text from the file, which are marked with the character C in column 71.

  4. Submit the completed job stream.

For further details refer to the VSE/ESA Programming and Workstation Guide manual, chapter "File Transfer To and From the Host Transfer File (HTF)", section "Creating the Host Transfer File (HTF)", subsection "Defining the HTF to VSAM".

3. Create a VSAM ESDS VTAPE file if necessary

Use the z/VSE provided job skeleton SKVTAPE from ICCF library 59 to create a VSAM ESDS file for use with the z/VSE Virtual Tape function (VTAPE). Note that the job skeleton by default adds the file label of the VSAM ESDS VTAPE file to the standard label area. This is required if you later intend to use the VSAM ESDS VTAPE file in the Interactive Interface dialogs to install additional components or products from the z/VSE extended base tape image or z/VSE optional product tape image.

  1. Copy the job skeleton SKVTAPE from ICCF library 59 to your ICCF primary library.

  2. Edit the job skeleton to complete the job stream:

    • Change the -V001- variable. Specify the volume(s) which have free VSAM space available for the VSAM ESDS VTAPE file in the respective VSAM user catalog.

    • Change the primary and secondary allocation to at least RECORDS (1500 1500). Otherwise storing the tape image may cause the allowed maximum number of extents to be exceeded.

    • Optionally change the catalog VSESP.USER.CATALOG and its file label VSESPUC to the respective values of your own VSAM user catalog.

  3. Enter @DTRSEXIT into the ICCF editor command line to delete all descriptive text from the file, which are marked with the character C in column 71.

  4. Submit the completed job stream.

For further details refer to the z/VSE Administration manual, chapter Implementing Virtual Tape Support, section Working with VSE/VSAM Virtual Tapes, subsection VSE/VSAM ESDS File Definition (Skeleton SKVTAPE).

4. Transfer the AWS tape image into the Host Transfer File

Open an Interactive Interface session using IBM Personal Communications. Either escape to CICS using PF6/PF9 or navigate to Operations, Personal Computer Move Utilities, PC File Transfer (fast path 3-8-6).

If you are using 3270 INW$FILE transfer for the first time, you should verify whether your host session is properly configured. For file transfer using IBM Personal Communications the Extended Data Stream (EXTDS) feature (also known as “query bit”) must be enabled, so that the session operates in DFT mode.
You can check the mode using the z/VSE provided CICS transaction INWQ. It responds by displaying either termid=DFT (DFT mode) or termid=CUT (CUT mode), with termid denoting the CICS terminal ID (e.g. A000).
If your host session is not configured in DFT mode you need to (re-)add the terminal as 24X80Q device. To do so navigate to the Interactive Interface dialog Resource Definition, Hardware Configuration and IPL, Configure Hardware (fast path 2-4-1). Optionally delete your terminal device(s). Press PF6 to add devices, fill in the device number(s), and enter a question mark in the DEVICE NAME field. In following dialog select 1 Local non SNA (Terminals/PCs) and then device 24X80Q (description “24x80 screen, Query e.g. PC-DFT”).
For further details on the Extended Data Stream (EXTDS) feature refer to the VSE/ESA Programming and Workstation Guide manual, chapter "Getting Ready for File Transfer", sections “Defining the Workstation to VSE/ESA” and "Preparing the Host Session for File Transfer".

Open a command prompt in the directory where your tape image in AWS-format is located and enter the appropriate IBM Personal Communications file transfer command.

Following is a sample command line to transfer a tape image in AWS-format using IBM Personal Communications via 3270 IND$FILE transfer into the Host Transfer File (HTF). The workstation file VSE620XB.AWS is transferred in binary without CR/LF translation via terminal session A into the HTF file with the name VTAPE1, type AWS, and the maximum record length of 32600.

SEND VSE620XB.AWS A: VTAPE1 AWS ( FILE=HTF BINARY LRECL=32600 NOCRLF

Note that it is crucial that the transfer is done in binary and without CR/LF translation. Depending on your terminal emulator you may need to specify those settings separately in the respective transfer options.

For further details refer to the VSE/ESA Programming and Workstation Guide manual, chapter "File Transfer To and From the Host Transfer File (HTF)", section "SEND/RECEIVE Command Syntax and Options", subsection "Command Syntax - SEND/RECEIVE (FILE=HTF".

If you are using the open source terminal emulator x3270 or its console version c3270 on Linux or macOS or wc3270 on Windows you can use the following workaround to specify the z/VSE specific IND$FILE transfer options. They can simply be injected into the HostFile option by enclosing them in brackets. The closing bracket causes any further trailing options automatically appended by x3270, c3270, or wc3270 to be treated as comments. This ensures your manually specified options take precedence and the automatically appended options are discarded.

c3270>Transfer(Direction=send, Host=cics, Mode=binary, LocalFile=VSE620XB.AWS, "HostFile=VTAPE1 AWS ( file=htf binary nocrlf )")

5. Copy the AWS tape image from the Host Transfer File into the VSAM ESDS VTAPE file

Following is a sample job to copy the tape image in AWS-format using the Batch HTF Utility (INWMUTIL) from the HTF file VTAPE1.AWS into the VSAM ESDS VTAPE file specified by the file label (DLBL) VTAPE1.

* $$ JOB JNM=HTF2ESDS,CLASS=0,DISP=D
// JOB HTF2ESDS - UNLOAD A HTF FILE INTO A VSAM ESDS FILE
* ------------------------------------------------------------------ *
* CLOSE THE HOST TRANSFER FILE IN CICS:
* CEMT SET FILE(INWFILE) CLOSE
* ------------------------------------------------------------------ *
// PAUSE - CLOSE THE HOST TRANSFER FILE IN CICS (SEE ABOVE)
// DLBL VTAPE1,'VSE.VTAPE.FILE',0,VSAM,CAT=VSESPUC
// EXEC INWMUTIL,SIZE=AUTO
UNLOAD,FILENAME=VTAPE1,FILETYPE=AWS,USERID=SYSA
/*
* ------------------------------------------------------------------ *
* OPEN THE HOST TRANSFER FILE IN CICS:
* CEMT SET FILE(INWFILE) OPEN
* ------------------------------------------------------------------ *
// PAUSE - OPEN THE HOST TRANSFER FILE IN CICS (SEE ABOVE)
/&
* $$ EOJ

The Batch Host Transfer File Utility (INWMUTIL) uses the first 7 characters of the HTF file name (specified via FILENAME) as file label (DLBL) for the VSAM ESDS file. The HTF file type (specified via FILETYPE) is only used to lookup the HTF file within the Host Transfer File.

If you added the file label of the VSAM ESDS VTAPE file to the standard label area, the DLBL is optional in the above sample job. This is true if you used the job skeleton SKVTAPE from ICCF library 59 to create the VSAM ESDS VTAPE file.

Note that you can close and later re-open the Host Transfer File in CICS when being prompted using the AR command MSG as follows:

MSG <syslog-id>,DATA=CEMT SET FILE(INWFILE) CLOSE
or
MSG <jobname>,DATA=CEMT SET FILE(INWFILE) CLOSE

[... copy of HTF file to VSAM ESDS file using INWMUTIL ...]

MSG <syslog-id>,DATA=CEMT SET FILE(INWFILE) OPEN
or
MSG <jobname>,DATA=CEMT SET FILE(INWFILE) OPEN

For further details on Batch Host Transfer File Utility (INWMUTIL) refer to the z/VSE System Utilities, chapter Batch Access to the z/VSE Host Transfer File.

Note that you could also use the Interactive Interface Move Utilities dialog instead of the Batch Host Transfer File Utility (INWMUTIL). For further details refer to the VSE/ESA Programming and Workstation Guide manual, chapter "File Transfer To and From the Host Transfer File (HTF)", section "Move Utilities Dialog for Host Access to the HTF".

I greatly appreciate your feedback via the z/VSE contact form.

Disclaimer: My posts and opinions are my own.