technical: How to Use TSO Transmit to Package Mainframe Datasets

If you're using the IBM Security Identity Adapters, you'll need to upload an adapter package to z/OS. This adapter package is file of a type called XMI. If you want to grab free tools on the CBT Tape website, you'll find that most of them are also in this XMI format. And Broadcom's CA Test Data Manager packages their mainframe data in, you guessed it, XMI format.

But XMI was never designed for this: it was designed for transferring files between TSO users. So, let's look at XMI files, and see why they're used, and how to use them.

XMI Files

TSO has for decades provided a feature for sending messages and data between TSO users: the Interactive Data Transmission Facility (let's call it the IDTF). Even TSO users on different z/OS systems can communicate using IDTF.

But sending z/OS datasets is difficult: because there's a lot of different types:

• Fixed and variable length (RECFM=F vs RECFM=V)
• Blocked and unblocked (RECFM=F vs RECFM=FB)
• Undefined record format (RECFM=F / RECFM=V vs RECFM=U)
• Sequential and PDS (DSORG=PS vs DSORG=PO)

To resolve this, IDTF created features to 'package' these files into a single sequential dataset that IDTF could easily transmit: the XMI format. Over the years, people have found it very useful to package up datasets into such a 'simple' format. For example, if you have some load modules you want to make available on the internet.

XMI format is sometimes called NETDATA format: as on z/VM, the CMS NETDATA command is used to work with them. Yes, this can also be used to transmit files between z/OS and z/VM.

Now, XMI isn't really documented: there's no single page with all the information. However, it's designed to package most 'traditional' z/OS datasets into a LRECL=80, RECFM=FB, DSORG=PS dataset. By traditional, we're talking about:

• RECFM=F, FB, V, VB, FBS, VBS, U
• DSORG=PO, PS (including PDSE and extended format sequential)

Note: no VSAM.

Creating an XMI File

So, let's create an XMI file. Suppose we have a PDS called DZS.LOAD. Here's a TSO command to create an XMI dataset:

TSO TRANSMIT (SVSCJES2.DZS) DATASET('DZS.LOAD') OUTDSNAME('DZS.LOAD.XMI')

We're packing up DZS.LOAD into an XMI dataset on z/OS called DZS.LOAD.XMI. Here's the output we see from this command:

                                       IEBCOPY MESSAGES AND CONTROL STATEMENTS
IEB1135I IEBCOPY FMID HDZ2240 SERVICE LEVEL UJ04425 DATED 20201117 DFSMS 02.04
IEB1035I DZS  ISKPROCE ISKPROCE 01:26:59 THU 23 DEC 2021 PARM='WORK=4M,SIZE=1M'
 COPY OUTDD=SYS00050,INDD=((SYS00046,R))
IEB1013I COPYING FROM PDS   INDD=SYS00046 VOL=VPMVSH DSN=DZS.LOAD
IEB1014I           TO PDSU OUTDD=SYS00050 VOL=       DSN=SYS21203.T012659.RA000
IEB167I FOLLOWING MEMBER(S) UNLOADED FROM INPUT DATA SET REFERENCED BY SYS00046
IEB154I CBRHADUX HAS BEEN SUCCESSFULLY UNLOADED
IEB154I COMPDS   HAS BEEN SUCCESSFULLY UNLOADED
IEB154I DZSC     HAS BEEN SUCCESSFULLY UNLOADED
IEB154I HELLO    HAS BEEN SUCCESSFULLY UNLOADED
IEB154I ISK001   HAS BEEN SUCCESSFULLY UNLOADED
IEB154I ISK002   HAS BEEN SUCCESSFULLY UNLOADED
IEB154I ISK003   HAS BEEN SUCCESSFULLY UNLOADED
IEB154I ISK004   HAS BEEN SUCCESSFULLY UNLOADED
IEB154I JUNK1    HAS BEEN SUCCESSFULLY UNLOADED
IEB154I NUMTEST2 HAS BEEN SUCCESSFULLY UNLOADED
IEB154I ZPRG03   HAS BEEN SUCCESSFULLY UNLOADED
IEB1098I 11 OF 11 MEMBERS UNLOADED FROM INPUT DATA SET REFERENCED BY SYS00046
IEB147I END OF JOB - 0 WAS HIGHEST SEVERITY CODE
0 message and 58 data records sent as 4323 records to SVSCJES2.DZS
Transmission occurred on 12/23/2021 at 01:26:59.

We've successfully packaged our DZS.LOAD PDS into the XMI file DZS.LOAD.XMI. Interestingly, DZS.LOAD is a load library: this is a great way of moving load libraries around. Let's look more closely at the command. We issue the TSO TRANSMIT command (also known as XMIT).

The next parameter is the addressee. We're actually not sending the file anywhere, but we still need to tell TRANSMIT a destination: us. This address is of the form "NODE.USER". NODE is the JES node name, and user is, well, our TSO username. In our example, we specified SVSCJES2.DZS. Our TSO userid is DZS, so the node name is SVSCJES2. But where do we get that from?

We need to find out our local JES node name. There's a couple of ways you can do this. The easiest is to use the SDSF NODE screen. Here's an example of the NODE screen:

If we look for a node with status of OWNNODE, we can see that it is SVSCJES2. Nice.

Some won't have access to this screen. So, what other options do we have? The z/OS console command $DNODE can also supply this information:

$DNODE,NAME,OWNNODE=YES
$HASP826 NODE(1)   NAME=SVSCJES2

Again, we're display the local node name (SVSCJES2). If this fails, then we can create a REXX to display the JES Node:

/* Rexx */
Say 'Node' SYSVAR('SYSNODE')

After all that, there's an excellent chance that you didn't need the node name. Just put any string as the node name, and there's a good chance that the command will work. For example:

TRANSMIT (X.DZS) DATASET('DZS.LOAD') OUTDSNAME('DZS.LOAD.XMI')

We've now got an XMI file that can be sent anywhere we want. The chances are that we will use FTP or IND$FILE to copy this XMI off the mainframe. If so, make sure that you transmit it as a binary file: no translation between EBCDIC and ASCII.

Extracting an XMI File

OK, so we've got an XMI file. How do we extract it?

First step, transmit it to z/OS (if it's not already there). Now, there's a couple of tricks when doing this. First, remember to transmit it as a binary file: no translation between ASCII and EBCDIC.

Secondly, the XMI on z/OS file must be a sequential file that has the following attributes: LRECL=80,DSORG=PS,RECFM=FB.

Tools like FTP or IND$FILE can be used to copy our XMI file to z/OS. However, by default these may not create a RECFM=FB, LRECL=80 dataset. The easiest way around this is to pre-allocate the file that will receive the XMI file. Let's step through an example. We have an XMI file on our Windows machine called awesome.xmi. We will use FTP to transmit it to z/OS.

First step: allocate an XMI file on z/OS. We'll use ISPF 3.2:

Second step, copy our XMI into this preformatted dataset. Here are the FTP commands:

ftp> bin
200 Representation type is Image
ftp> put awesome.xmi 'DZS.AWESOME.XMI'
200 Port request OK.
125 Storing data set DZS.AWESOME.XMI
250 Transfer completed successfully.
ftp: 345840 bytes sent in 2.40Seconds 144.10Kbytes/sec.
ftp>

OK, we now have our XMI file on z/OS. Next step: use the TSO RECEIVE command to extract our dataset:

TSO RECEIVE INDA('DZS.AWESOME.XMI')

Here's what we get:

Dataset DZS.LOAD from DZS on N1
 Enter restore parameters or 'DELETE' or 'END' +

Here we can enter parameters to control things. If just hit enter, then RECEIVE will extract the dataset with the same name as when it was created. This often won't work, and we need to use a new dataset name. So we tell RECEIVE a new name using the DSNAME parameter:

Dataset DZS.LOAD from DZS on N1
 Enter restore parameters or 'DELETE' or 'END' +
 DSNAME('DZS.AWESOME')

And RECEIVE now extracts our dataset:

                                       IEBCOPY MESSAGES AND CONTROL STATEMENTS
IEB1135I IEBCOPY FMID HDZ2240 SERVICE LEVEL UJ04425 DATED 20201117 DFSMS 02.04
IEB1035I DZS ISKPROCE ISKPROCE 02:16:31 THU 23 DEC 2021 PARM='WORK=4M,SIZE=1M'
 COPY INDD=((SYS00104,R)),OUTDD=SYS00103
IEB1013I COPYING FROM PDSU  INDD=SYS00104 VOL=       DSN=SYS21203.T021630.RA000
IEB1014I           TO PDS  OUTDD=SYS00103 VOL=VPMVSC DSN=DZS.AWESOME
IEB167I FOLLOWING MEMBER(S) LOADED FROM INPUT DATA SET REFERENCED BY SYS00104
IEB154I CBRHADUX HAS BEEN SUCCESSFULLY LOADED
IEB154I COMPDS   HAS BEEN SUCCESSFULLY LOADED
IEB154I DZSC     HAS BEEN SUCCESSFULLY LOADED
IEB154I HELLO    HAS BEEN SUCCESSFULLY LOADED
IEB154I ISK001   HAS BEEN SUCCESSFULLY LOADED
IEB154I ISK002   HAS BEEN SUCCESSFULLY LOADED
IEB154I ISK003   HAS BEEN SUCCESSFULLY LOADED
IEB154I ISK004   HAS BEEN SUCCESSFULLY LOADED
IEB154I JUNK1    HAS BEEN SUCCESSFULLY LOADED
IEB154I NUMTEST2 HAS BEEN SUCCESSFULLY LOADED
IEB154I ZPRG03   HAS BEEN SUCCESSFULLY LOADED
IEB1098I 11 OF 11 MEMBERS LOADED FROM INPUT DATA SET REFERENCED BY SYS00104
IEB144I THERE ARE 12 UNUSED TRACKS IN OUTPUT DATA SET REFERENCED BY SYS00103
IEB149I THERE ARE 5 UNUSED DIRECTORY BLOCKS IN OUTPUT DIRECTORY
IEB147I END OF JOB - 0 WAS HIGHEST SEVERITY CODE
Restore successful to dataset 'DZS.AWESOME'

Browsing XMI Files

Suppose we have an XMI on our Windows system. We may be access it from Windows, and see what's inside. This could be handy to confirm that the XMI file is valid. For this, you need a tool. The free XMIT Manager is great, and can be found on the CBT Tape website:

There are a few other free tools for viewing XMI files. You can also find them on the CBT Tape website.

Conclusion

Although not originally designed for the purpose, XMI files are a great way of moving around mainframe datasets via Windows, UNIX and other non-mainframe systems. In particular, if you want to make a z/OS dataset available on a web page, XMI files are excellent.

They can be a little fiddly to create and extract. But once you get used to them, they work really well.

David Stephens

LongEx Quarterly is a quarterly eZine produced by Longpela Expertise. It provides Mainframe articles for management and technical experts. It is published every November, February, May and August.

The opinions in this article are solely those of the author, and do not necessarily represent the opinions of any other person or organisation. All trademarks, trade names, service marks and logos referenced in these articles belong to their respective companies.

Although Longpela Expertise may be paid by organisations reprinting our articles, all articles are independent. Longpela Expertise has not been paid money by any vendor or company to write any articles appearing in our e-zine.