LongEx Mainframe Quarterly - February 2022
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 FilesTSO 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:
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:
Note: no VSAM. Creating an XMI FileSo, 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 FileOK, 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 FilesSuppose 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. ConclusionAlthough 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. |
