Getting my MVS files into the RTC repository (and getting them back out again)

A little while back I was asked to deliver some education on zimport and zload. I decided not to let the fact that I knew neither zimport nor zload stop me from saying yes, and set out to educate myself via the usual means of reading, playing, and pestering the super smart people who have the misfortune of sitting around me. I learned some great secrets and troubleshooting tips that I’ll be sharing here today. The documentation for zimport and zload is thorough and complete as far as setup and options, so I will just give a brief introduction here and then focus on the good stuff.

Zimport, which you may also hear referred to as “mass import” or “the mass import tool,” is a one time tool for getting your existing MVS data sets into the RTC SCM. It is executed by a project administrator setting up the SCM, and requires a mapping file to specify the data sets to be imported. It creates zComponent projects, which are the type of project required to take advantage of all the various z capability in RTC. It creates Data Set Definitions based on the characteristics of the imported data sets, and optionally associates the imported files with Language Definitions.

Conversely, zload loads files from your repository workspace back out to your z/OS system. While zimport is JUST for importing from MVS, zload allows you to load to MVS, USS, or both.

So now that we know what we’re talking about, one of the main sources of difficulty and confusion is in the area of code pages and line delimiters. Files are typically stored in the Jazz repository in UTF-8; files on z/OS are typically stored in EBCDIC. When we zimport, we convert from EBCDIC to UTF-8. When we zload, we convert from UTF-8 to EBCDIC. Following is the logic taking place under the covers for zimport and zload:

  • If zimport specifies -b for binary, we set the line delimiter to none and do no conversion. Otherwise, we convert and set the line delimiter to platform. We determine which encoding to use for the conversion based on the ZLANG environment variable. If ZLANG is set, use it.If ZLANG is unset, use the system’s default encoding.
  • To determine which encoding to use when loading to MVS, we:
    • Check the mvsCodePage versionable property of the file.  If present and non-blank, it is used.
    • If no mvsCodePage, default to the value of the ZLANG environment variable, if ZLANG is set.
    • If the mvsCodePage property is not present, and ZLANG is unset, default to using the system’s default encoding.
  • To determine which encoding to use when loading to USS, we:
    • Check the mvsCodePage versionable property of the file.  If present, and non-blank, it is used.
    • If the mvsCodePage property is present but blank:
      • If ZLANG is set, use the value of ZLANG.
      • If ZLANG is unset, default to the system’s default encoding.
    • If the mvsCodePage property is not present, load the file as it is in the repository — no conversion is done.

Now let’s talk about some known issues, limitations, and other gotchas.

Q: So, now that I’ve done my zimport and zload, how can I check my MVS changes back into the repository?

A: You can’t. There is currently no scm command line support for MVS. There is an open story 139129: Command Line support for SCM for this where you can add your +1 if it’s important to you.

Q: So, I have FRED.JOE.COBOL and FRANK.BOB.COBOL, and I want to import them into a single zFolder with a single COBOL Data Set Definition. How do I specify a multi-segment HLQ for the zimport?

A: You can’t. We only consider the first segment to be the HLQ. But, if you take a peak at the status of work item 155055: Support multiple-segment HLQs in zimport you might find some upcoming good news in this department. 🙂 A couple details on this… If you try to import FRED.JOE.COBOL and FRED.FRANK.COBOL at the same time, it will fail with the error saying A zFolder can only contain zFiles imported from one PDS. But what you can do is import FRED.JOE.COBOL into a COBOL folder first. A JOE.COBOL data set definition will be created. You can then reuse your workspace (or any other workspace that flows to the stream where you’ve delivered FRED.JOE.COBOL) to zimport FRED.FRANK.COBOL into that same COBOL folder, which will continue to use the JOE.COBOL data set definition, rather than creating a FRANK.COBOL data set definition. You can always rename that data set definition when you’re done.

Q: What can I do to avoid so many Data Set Definitions being created by zimport?

A: If your data sets have the same name and all of the same attributes, zimport will use the same data set definition. If you end up with DSDs that you don’t want, you can always export all of your system definitions to capture the attributes of the DSDs you DO want, run the language definition generator to delete the data set definitions, and then run it again to recreate the good data set definitions and associate them with your zFolders.

Q: Daaaaaaang, this import is taking forevvvverrrrrrrr!! What should I do?

A: Go fix yourself a snack and keep waiting. If you kill it in the middle, you’re going to corrupt your metadata. To help speed things along, organize your data sets before the import such that you’re not processing through a ton of members to find the ones you want to import. The performance of the tool is a function of the number of files it looks through to decide what to import, more so than the number of members it actually ends up importing.

Q: My zimport is failing with this message: SEVERE: Error getting sharing descriptor. What do I do now?

A: Kick yourself for not listening to me above. Your metadata is corrupt. You probably killed a previous import while it was in the middle of working, or maybe it crashed in the middle (e.g. because you ran out of space). You could try changing the value of your SCM_WORK environment variable to another directory, or, if there’s nothing in your current SCM_WORK that you need to save, just delete that directory.

Q: What is up with this warning in my zimport?
CRHTC0632I Created the repository workspace zimport Feb 28, 2012 3:31:10 PM.
CRHTC0621E An error occurred while retrieving the members in PDS RYEHLE.SPF.ISPPROF. Its members will not be imported.
//’RYEHLE.SPF.ISPPROF’: fopen() failed – EDC5061I An error occurred when attempting to define a file to the system. errno=61 errno2=0xc00b0403 last_op=50

A: The tool is scanning every data set under the specified HLQ to figure out what to import. Check out work item 146123: Be smarter about scanning data sets for import to see how (and when!) we’ve gotten smarter.

This entry was posted in Enterprise Extensions, Rational Team Concert, System z. Bookmark the permalink.

2 Responses to Getting my MVS files into the RTC repository (and getting them back out again)

  1. Robin – Is the education you mention in the first line of this post different than the links you provide for zImport and zLoad. If so, would you be able to send me a copy of it? Thanks!

  2. ryehle says:

    Hi Sheri,
    The education was an internal session, and information shared in that session is captured either in the links or in the blog post.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s