A while ago I started writing a series of blogs talking about the theory of how to make your own toolkit and make it easily portable to any system you use. Of course work got in the way and I never finished writing the blogs, but I did finish writing the toolkit.
So rather than writing more about the theory, I’ve put the finished toolkit in the FILES section of this community, and here’s how you can use it to help you port all your useful stuff around between your own z/OS systems.
Getting the toolkit on your system
The core theory of the toolkit is that is uses the TSO TRANSMIT command to convert libraries into binary sequential files, which has the great advantage of avoiding many codepage issues when you transfer between different systems.
To DEV.PORTABLE.REXX.XMIT is a transmit file that you must send to your system, by whatever means you choose, as a binary transfer with a fixed record length of 80.
Once you have it on your system you can receive it with the TSO RECEIVE command
e.g. tso receive indsn('dev.portable.rexx.xmit')
You will then be prompted to supply the name to receive into –
INMR901I Dataset DEV.PORTABLE.REXX from ZUSRDH1 on S0W1
INMR154I The incoming data set is a 'DATA LIBRARY'.
INMR906A Enter restore parameters or 'DELETE' or 'END' +
Then provide the name that you want to call the received PDS -
And the dataset will unfold on your system -
IEBCOPY MESSAGES AND CONTROL STATEMENT
S PAGE 1
IEB1135I IEBCOPY FMID HDZ2210 SERVICE LEVEL UA83949 DATED 20170202 DFSMS 02.
02.00 z/OS 02.02.00 HBB77A0 CPU 1090
IEB1035I ZUSRDH1 TSOWS930 TSOWS930 15:44:34 WED 03 JAN 2018 PARM=''
IEB1013I COPYING FROM PDSU INDD=SYS00040 VOL=ZSWRKA DSN=SYS18003.T154434.RA000
IEB1014I TO PDSE OUTDD=SYS00039 VOL=ZSDEVA DSN=DEV.PORTABLE.REXX
IGW01551I MEMBER HOOKIN HAS BEEN LOADED
IGW01551I MEMBER REALLOC HAS BEEN LOADED
IGW01551I MEMBER TEMPNAME HAS BEEN LOADED
IGW01551I MEMBER UNHOOK HAS BEEN LOADED
IGW01551I MEMBER XMIN HAS BEEN LOADED
IGW01551I MEMBER XMOUT HAS BEEN LOADED
IGW01551I MEMBER ZPACK HAS BEEN LOADED
IGW01551I MEMBER ZPACKCNF HAS BEEN LOADED
IGW01551I MEMBER ZPACKINC HAS BEEN LOADED
IGW01551I MEMBER ZUNPACK HAS BEEN LOADED
IGW01550I 10 OF 10 MEMBERS WERE LOADED
IEB147I END OF JOB - 0 WAS HIGHEST SEVERITY CODE
INMR001I Restore successful to dataset 'DEV.PORTABLE.REXX'
So you now have the toolbox on your system, but what is it?
What’s in the Portable Pocket Rexx?
If you look inside you’ll see a few members in there, we’ll go into detail on each later, but for now, here’s the high-level view.
- HOOKIN – Gets the toolkit added to your SYSPROC concatenation so you can run the commands within the kit easily
- ISPFENV – Creates an ISPF environment for your toolkit.
- REALLOC – A comprehensive tool to reallocate TSO DDs to ADD, REMOVE or REPLACE files in any available concatenation.
- TEMPNAME – Allows you to EX against the dataset name in PDF 3.4, which will then add the toolkit to your SYSPROC concatenation so you can run the commands within the kit easily
- UNHOOK - Removes the toolkit from your SYSPROC concatenation
- XMIN – Provides a line command to PDF 3.4 to easily receive an XMIT file
- XMOUT – Provides a line command to PDF 3.4 to easily create an XMIT file from and existing sequential file or PDS.
- ZPACK – Creates a single XMIT dataset that packs several datasets into one portable file
- ZPACKCNF – A member to allow you to configure a few bits for your environment
- ZPACKINC – A member to allow you to say which extras you pack in your toolbox
- ZUNPACK – Unpacks a dataset created by ZPACK into multiple files once more
Getting the tools hooked in
Of course a toolkit is no good, if you can’t use them, and to use REXX tools on a system they need to be somewhere in one of the REXX/CLIST concatenations in the TSO search path. I’m a traditionalist so I go with SYSPROC, so I could include the odd CLIST if the mood took me, but there’s nothing to stop you using any of the other options.
The toolkit comes with a very easy way to get it hooked in. You can type EX as a line command next to the received dataset in PDF 3.4, and it will add that dataset to the top of the SYSPROC concatenation for you. Equally if you are in the member list from PDF 3.4, then you can type EX next to the HOOKIN member, which will do the same.
Once you are done and want to free up the toolkit, you can do that by entering EX next to member UNHOOK in the member list.
This all works by using the REALLOC REXX program which can ADD, REMOVE or REPLACE libraries from any accessible concatenation within your TSO session.
To run REALLOC from PDF 6 the syntax is as follows –
REALLOC ADD|REMOVE|REPLACE TOP|BOTTOM|n|dsname ddname [dsname]
The first parameter determines whether a dataset is being added, removed or replaced in a concatenation.
The second parameter says where –
- TOP will introduce the new dataset at the top, or remove/replace the first dataset
- BOTTOM will introduce the new dataset at the bottom, or remove/replace the last dataset
- Specifying a number will introduce the new dataset after that position in the concatenation, or remove/replace the dataset at that position
- Specifying a dataset will introduce the new dataset after that dataset in the concatenation, or remove/replace that dataset
The third parameter says which concatenation to update. Note that if this concatenation is open by a program, e.g. ISPF, then it will not be possible to reallocate it.
The fourth parameter names the dataset to add, or the dataset to replace an existing dataset with in the concatenation. The fourth parameter is ignored for REMOVE.
Transmitting and receiving
Transmitting to a dataset is a bit of a fiddly syntax, since you need to know a user and node name, and receiving a dataset still required a bit of typing. This is where XMOUT and XMIN are useful.
Enter XMOUT next to an existing sequential dataset or library as a line command in PDF 3.4 and it will do all the hard work for you. It will take the existing dataset name and create a new transmitted form, with XMIT tacked on the end. If one exists already it will prompt you before overwriting.
Enter XMOUT next to an existing TRANSMIT file as a line command in PDF 3.4 and it will receive it for you. If your TRANSMIT dataset had .XMIT or .BIN on the end, then the received dataset name will be the same minus that low level qualifier. Otherwise it will just add RCVD onto the end of the created dataset. Again it will prompt you before overwriting.
This makes moving files between systems much simpler, as you can download these XMIT files as binary transfers, and then transfer them by whatever means you like, even as email attachments.
Packing and unpacking
XMOUT and XMIN are good if you only want to move one dataset but if you have a set of datasets to move around, time to get packing. Typically this works well for transporting a set of ISPF tools, which as well as a REXX library also has panel, message, table and skeleton libraries to translate as well.
The ZPACK tool will look for all none VSAM datasets with a specified set of prefix qualifiers, and TRANSMIT them to members in a new ZPACK library. It will also copy into that same library some key members from the Portable Pocket Rexx, to aid in the unpacking at the other end. Finally it will convert the ZPACK library into a ZPACKXMT library, by transmitting it to a file, that can be sent anywhere just like any XMIT file.
The ZPACK file will be created using the prefix you specified, plus a Date and Time qualifier, before appending ZPACK on the end.
For example TSO ZPACK DEV.PACKTEST will pack every library it finds with the high level qualifiers of DEV.PACKTEST (ignoring any ZPACK or ZPACKXMT files it finds) and create a packed file using the format DEV.PACKTEST.Dyymmdd.Thhmmss.ZPACKXMT.
You can decide whether to include Date and or Time in the ZPACK file name by specifying a second argument –
- DT = Include date and time (supplied as the default – which you can change)
- D = Include only the date
- - = Do not include date or time (minus sign)
e.g. TSO ZPACK DEV.PACKTEST –
It will also ask if you want to delete the original datasets when you pack them, so you can use the ZPACK tool to archive old collections of datasets into single files.
Then when you transfer the ZPACKXMT file somewhere else, if you already have the ZUNPACK command on that system you can simply enter ZUNPACK as a line command against the ZPACKXMT file and it will extract all the files you packed onto the new system. It will use the prefix you created the ZPACKXMT file with on the new system to create all the new files it unpacks, regardless of what they were called on the old system.
If the ZUNPACK command isn’t already on the new system, then RECEIVE the ZPACKXMT file into a dataset, replacing the ZPACKXMT qualifier with ZPACK. You can then EX the ZUNPACK member from within the ZPACK dataset, which will unpack the contents for you. Alternatively if ZUNPACK is not installed on the new system, but XMIN is, the you could use that to RECEIVE the ZPACKXMT dataset into the ZPACK dataset.
Because of the Dyymmdd.Thhmmss qualifiers in the ZPACK dataset name, this means that every time you use ZPACK it creates a new file containing the contents of the target files at that point. So as well as using ZPACK to transfer datasets to new systems, it can be used to create simple backups of your dataset collections. Simply renaming the high level qualifier of one of the backups would allow you to restore a copy of each dataset to new names.
When copying the ZPACKXMT file to another system you can drop the Thhmmss or both the Dyymmdd and Thhmmss qualifiers from the dataset name, and the process will still work out the prefix, as long as you are using the relevant ZPACK or ZPACKXMT low level qualifiers.
A portable ISPF environment
The ISPFENV REXX is a quick way of setting up a portable ISPF environment.
You can decide what libraries you want to allocate, what ISPF menu or command to run and whether to start a new ISPF application.
By default it expects that whatever prefix you have used for ZPACK, then you will have a REXX, ISPMLIB, ISPPLIB, ISPSLIB and ISPTLIB library with that same prefix.
You can decide which library types you do want by editing variable LIB.TYPES
e.g. LIB.TYPES = “MLIB PLIB REXX” means you only want to use messages, panels and REXX in your environment.
Which libraries you use for each type can also be customised, by default each type is the prefix and the relevant low level qualifier e.g. LIB.MLIB = “*.ISPMLIB” expect your message library to simply be your ZPACK prefix with ISPMLIB on the end. But you can also hard code full datasets names, use ? for userid, and even create a list.
e.g. MLIB.TLIB = “?.ISPTLIB *.ISPTLIB” would create a table library concatenation of the user’s own ISPTLIB followed by the ZPACK ISPTLIB.
You chose the panel or command you want to run by editing variable LIB.CMD and if you want to set an ISPF application you set LIB.APPL e.g. LIB.APPL = “” will set no ISPF application.
Once you have tweaked your ISPFENV and used ZPACK to pack your collection of libraries, when you ZUNPACK at the other end, entering EX next to the ISPFENV member should start your ISPF environment for you.
Making tweaks to the Portable Pocket REXX
Some of these tools expect certain low level qualifiers, but what if your system administrator would rather that you use different values for some of these things? Well that’s what the ZPACKCNF member is for. This sets up some variables that XMIN, XMOUT, ZPACK and ZUNPACK use to determine what values to use for certain things. You can customise these values to suit your site.
The following variables are used by ZPACKCNF, adjust them as you see fit.
- PDS_LLQ (default ZPACK) – Sets the low level qualifier that the ZPACK command creates its PDS with.
- XMIT_LLQ (default ZPACKXMT) – Sets the low level qualifier for the XMIT version of the ZPACK library.
- TEMP_DD (default ZPACKTMP) – Sets the temporary DD name that these processes use.
- RECEIVED_LLQ (default RCVD) – Sets the low level qualifier to append to files received by XMIN, if the low level qualifier is one not recognised by XMIN as an XMIT file.
- XMIT_LLQS (default XMIT XMT BIN) – Provides the list of recognised low level qualifiers that the XMIN process will simply remove to create the received version of the dataset name. The first word in this list is the low level qualifier that XMOUT will append to any dataset names it creates an XMIT version of.
The ZPACK process, as well as packing the set of datasets you request, will also package a few useful REXX routines into the base ZPACK file to ensure that you can use the packed file when it gets to its destination. You can however add your own tools to this list by modifying the ZPACKINC member. Which by default it looks like this –
/* REXX */
RETURN "DSN=DEV.PORTABLE.REXX" ,
The module simply returns a space separated list of entries. The list MUST start with the name of the dataset containing the modules, and must be prefixed with DSN=. The following entries on the list will be the member names you want to copy.
If you want to include members from more than one source then add another DSN= entry into the list and any members following that entry will be copied from a different library.
/* REXX */
RETURN "DSN=DEV.PORTABLE.REXX" ,
If the include datasets or members don’t exist, then warnings will be issued, but the packing process will continue.
In ZPACK itself there are also a few variables you can tweak at the top –
- trktotal = The number of tracks to add to the calculated size of the ZPACK file. The process works out what you are going to pack, but cannot estimate what you are going to include, this variable allows you to add some breathing space.
- arg_Name_Default = The default second argument for ZPACK which can be DT, T or –
Finally the last thing you might want to tweak is in ZPACK and ZUNPACK, there is a little bit of code that deletes your LOG.MISC dataset. This is a system generated dataset that logs each TRANSMIT you do, which might sound a good idea, but it’s a small dataset, and if you start using these functions a lot it will soon fill up, and cause your XMITs to fail. But if you’d sooner manage that yourself feel free to remove that bit of code.
A final thought
When defining any tools like this, you can soon find out that they work great for you, but not so well on other people’s systems. So you may need to do the odd tweak here or there, or perhaps add some new features yourself.
I’d love to hear about them and perhaps incorporate them into the Portable Pocket REXX.