The z/OS Explorer Aqua release train brings together a number of different Eclipse tools¬†for administering or developing apps for z/OS subsystems and tools. ¬†These tools are hosted by IBM on the URL¬†http://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua/. ¬†This site can be thought of an ‘app store’. ¬†To obtain any of the tools you point your Eclipse Luna, or IBM Installation Manager, at the URL and from there can install tools, update tools (when IBM refreshes the content), and not have to worry about whether everything on the site installs side by side. ¬†The way this works is that IBM Explorer for z/OS points to our URL as an available update site, which then lists the tools that are available.

Screen Shot 2016-02-10 at 23.13.17

Here’s the problem. ¬†What if I am distributing the z/OS Explorer to PCs without internet access ?

This blog entry will cover the solution for the Eclipse standard installer (known as P2, and shown in the screen shot above).  Another blog post covers how to do this if you are using IBM Installation Manager and not p2 as your install technology.

Here’s one we prepared earlier

The contents of the update site required by the Eclipse p2 installer are available in a single zip file.   This is around 1.2 GB and contains all the 13 tools available as p2 packages.  The first step is to download this to your PC.

Aqua Update Site – Zip File

This contains all of the stand-alone downloads for z/OS Explorer and CICS Explorer, together with the p2 zip archive of the release train contents. ¬†Each time we refresh the contents of the release train with new software and push that to the aqua site, we create a new zip file that increments the number in the second segment of its name and we append the date and time to the .zip file. ¬†This allows users to identify which file is from which release – in our first incarnation we didn’t do this and users requested that we name the files uniquely.

Each time we refresh the site we create a new file with a unique name, so that it’s possible to distinguish the April 29th 2016 release from the September 28th¬†2016 release.¬† The file name contains the refresh number of the site, so currently we are the 10th refresh.

 

http://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua/direct/aqua.10.update.site-20161209.zip

If the link does not work then please visit the download instructions on https://developer.ibm.com/mainframe/products/downloads/ and select the button Aqua Update Site РZip File.  This will link to the latest archive of the update site.

Screen Shot 2017-01-18 at 11.53.45

If you need an older version of the file then please contact us via¬†https://developer.ibm.com/answers/questions/index.html¬†using the tag zosexplorer, ¬†or else add feedback to this article. ¬†We are aware that customers often like to re-retrieve a particular version of a file at a point in the past that they have standardized their desktop rollout on, however we currently aren’t keeping all of the previous archives on the site for space considerations and also to promote the concept that the release train is moving forward with fixes so it represents the latest and greatest codebase.

Once you have done this you can point your Eclipse installer directly at the aqua update site zip file.   The actions to do this are

1) Open the Eclipse install dialog

Pull down menu Help -> Install New Software…

Screen Shot 2016-02-11 at 12.14.43

2) Select Add… to open the Add Repository Dialog

Screen Shot 2016-02-11 at 13.26.09

3) on the Add Repository dialog select Archive…

Screen Shot 2016-02-11 at 13.29.15

There is a button Local… which is confusing, as I know folks who select this thinking “The file containing the repository of software is local and not remote”. ¬† We will use the local button later which actually is for pointing at a folder that has the software, however because we downloaded a .zip file, aka a zip archive, we need to use the Archive… button and navigate to where you downloaded the aqua update site zip file.

Screen Shot 2016-02-11 at 13.32.28

4) Select the tools you want to install from the list of update site contents in the zip file

Screen Shot 2016-02-11 at 13.35.09

From here you can click through the wizard to accept the licenses and use the installer no differently to whether the update site was on a remote internet URL hosted by IBM, or the update site is in the .zip file on your PC’s hard drive.

 

Pointing to the archive zip without so many dialogs

The URL for the update site that we use for the z/OS Explorer Aqua release contents is¬†http://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua. ¬†If you look at the Work with: combo on the Install dialog after you’ve pointed it at an archive file you can see the format it uses, such as:

jar:file:/Users/Joe/Downloads/aqua.n.update.site-yyyymmdd.zip!/

on a Windows PC this might be

jar:file:/C:/temp/aqua.n.update.site.-20160510.zip!/

Rather than opening the Add… and Archive… and navigating to the file, you can type the location directly using the format jar:/file:{path/aqua.n.update.site-yyyymmdd.zip}!/.

Screen Shot 2016-02-12 at 14.53.26

Using the steps above you should be able to get the .zip off the update site and use this to distribute the update site contents locally within your organization for folks to download and enjoy.

How can I get updates ?

One of the benefits of the update site is that it can be used not only to install new software, but to update software as well. ¬†When we – IBM – refresh any of the contents of the tools (with fixes or enhancements) we put the new stuff onto the same URL. ¬†Because z/OS Explorer has this site in its list of sites you can use Help -> Check for Updates… and Eclipse will dial up the sites it knows about, check to see whether there is new content, and give you the option to install the upgrade. It’s similar to when you download an app from an app store to your smart phone or tablet, and then later on you can check for updates and see the red visual tag that updates are available.

We have already done this – our first GA on December 11th was z/OS Explorer 3.0.0.0 and on December 18th when we released Rational Developer for System z 9.5.1 on the Aqua site we needed to spin z/OS Explorer to 3.0.0.1. ¬†If you have z/OS Explorer 3.0.0.0 (check the splash screen or Help -> About dialog) use Help -> Check for Updates … and the p2 installer will dial the aqua site, see there is a z/OS Explorer 3.0.0.1 available, giving you the opportunity to click through the upgrade.

3.0.1 Check for updates

If your z/OS Explorer can’t get at the URL with the content though it won’t be able to get updates.

One way you can overcome not having access to the Aqua URL is is to keep checking the download page to see when new content is available, get another stand-alone zip, add this as a repository archive.  There is an advantage to this which is that you might decide not to take a particular update and it puts you in control, however there is another solution which is where you can mirror the external internet update site through a command that you can run repeatedly, say once a week, that will refresh your internal mirror with the external contents.  You point your z/OS Explorer at the internal mirror and it behaves, to all intents, as though it was the external URL.

To mirror a site you run two special command line arguments against the zosexplorer.exe, or any other eclipse.exe that will open eclipse and show a splash screen, but rather than opening a workspace and showing the initial perspective, instead Eclipse is used as a headless server to run the application org.eclipse.equinox.p2.artifact.repository.mirrorApplication and then the application org.eclipse.equinox.p2.metadata.repository.mirrorApplication.

Each of these takes arguments -source for the site you want to mirror from and -destination to the location of the target site you want to create.

As an example, I have a downloaded Eclipse on my Windows PC in c:/zeus/eclipse mars jee.  In this folder is eclipse.exe.  Open a command prompt and navigate to the folder containing eclipse.exe to run the command.

The -source argument is the location of the p2 update site containing the software I want to copy from, which for z/OS Explorer Aqua is http://public.dht.ibm.com/imdbl/export/pub/software/htp/zos/tools/aqua

The -destination argument is the location of where I am going to download the update site contents to.  On my Windows PC this is C:/temp/aqua_site and the URL syntax for this is file:c:/temp/aqua_site.

-consoleLog traces any errors (such as incorrect syntax or connection timeouts occur) that get written to the .log file in the same location as the eclipse.exe.

-nosplash¬†is useful if you don’t want to see an Eclipse splash screen open. I prefer to see the splash screen as it indicates the mirror¬†hasn’t died, although the operating system will mark it as Not Respnding when it really is, because the user interface thread is not responsive while the mirror is hoovering up the source update site and copying it to the target.

The full command to mirror the repository files is

eclipse.exe -consoleLog – application org.eclipse.equinox.p2artifact.repository.mirrorApplication -source http://public.dht.ibm.com/imdbl/export/pub/software/htp/zos/tools/aqua -destination file:c:/temp/aqua_site.

p2 mirror

When the command has finished you need to run it a second time, this time replacing org.eclipse.equinox.p2.artifact.repository.mirrorApplication with org.eclipse.equinox.p2.metadata.repository.mirrorApplication.

The folder c:\temp\aqua_site will now be a mirror of the public site, and you can point an Eclipse to it using Add Repository… from the Install dialog, this time choosing Local (rather than archive).

Optimizing mirroring

The command takes a while to run depending on the speed of the network connection.   If the command stops for any reason, it can be re-run and it will pick up where it left off.  It is also possible to mirror the update site a tool at a time.  The file compositeContent.xml is an index file of the tools on the site and how they are laid out in the site.  You can open the file http://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua/compositeContent.xml directly in a browser to see its XML structure.

aqua composite content

From here you can see there is a subfolder/apa, which contains application performance analyzer, /cicsexplorer which contains the CICS Explorer, and so on.  If you know you only need to get the CICS Explorer you can mirror this by itself (rather then entire site) by using the p2 mirror command above, but using the -source as http://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua/cicsexplorer/update.site/ directly.

If you do mirror individual tools, you will always need to mirror the /eclipsesubset/update.site as well to the same -destination. ¬†The URL for this is¬†http://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua/eclipsesubset/update.site/. ¬† The reason for this is that there are a number of components that are not used by just one tool, and these shared pieces are held in the /eclipsesubset folder. ¬†This is actually one of the clever things about the Aqua site and how it brings together different tools in a compatible way – rather than having different tools deliver the same and potentially incompatible or colliding versions of software components, every component that is used by more than one tool is placed into¬†/eclipsesubset/update.site. ¬†This is a bit like the old saying that you shouldn’t wear two watches – what do you do if one shows a different time to the other ? ¬†Better to have just one watch that is always right.

If you do choose to do mirroring from our Aqua update site to a local site you could do this as part of a scheduled job, perhaps every week. ¬†Then you can always pick up the latest changes that we publish to the public internet site onto your internal mirror where you can make these available¬†to your z/OS Explorer Aqua users. ¬†It is also possible to add other products to the same internal site that aren’t part of the IBM z/OS Explorer Aqua release train, such as third party vendor plugins, or open source tools. ¬†You can do this just by running mirroring pointing -source at the vendor or open source update site and -target at the same time you’ve mirrored the Aqua site into. ¬†This could enable you to create an internal list of “approved” software that you could publish to end users that was made up of IBM as well as other tools.

Please give feedback for whether this works for you or not, as well as what improvements you’d like us to make to how we deliver new and updated software to enable you to get on with the task of developing, deploying, testing, running and administering your z/OS application and subsystem software.

Enjoy !!

9 comments on"Deploying IBM z/OS Explorer Aqua to users without internet access – JoeW/IBM"

  1. Hi, the download URL seems to be broken.

  2. JoeWinchester June 29, 2016

    Hi – we did have some problems with the download site and it is possible you tried it during a window when we were fixing things. Can you try again please and let you know which URL is causing problems and whether it’s a timeout problem, or an http404, or what the steps are you you’re doing so we can try to re-create it and see what’s broken ? Many thanks, Joe

  3. JoeWinchester July 12, 2016

    Hi, sorry about the 404. We create a new file name for each refresh of the release train contents, so the URL aqua.2.update-site-20160510 is for the 2nd update of the site software on May 10th. We are currently at .4 and the URL is http://public.dhe.ibm.com/ibmdl/export/pub/software/htp/zos/tools/aqua/direct/aqua.4.update.site-20160621.zip.
    I’ve changed the article – and also added a para that if the URL goes stale then the download site http://developer.ibm.com/mainframe/download always has a section “Aqua Update site – Zip File” that is a link that will take you to the latest file that we keep up to date. I’ll chat to the folks later today to see if there’s a better way we can have a redirect or symlink that we update so folks externally just see one URL maybe /latest that we redirect internally to the file name that varies with each release.

  4. Hi.
    I just downloaded
    The syntax is:
    jar:file:/C:/Temp/aqua.12.all.im.repo-20170217.zip!/

    And zosepxlorer says:
    jar:file:/C:/Temp/aqua.12.all.im.repo-20170217.zip!/
    ?!
    regards
    Jacques

    • JoeWinchester April 20, 2017

      Hi Jaques – sorry for only just seeing your message. Did you get everything working OK ?

  5. Antonio Lopez August 30, 2017

    would be nice to have the URL’s to download each plugin instead a whole package with components that I will not use at least in near term.

  6. Q3UD_Christopher_Hanks November 09, 2017

    Hi – I need a version of z/OS Connect EE API Editor Feature that is compatible with RDZ 2015.1.13.201342.
    I know version 2.0.403.201702170001 works.
    Can you provide a link to the zosexplorer aqua P2 file containing this version?

  7. This does not seem to work:

    zosexplorer.exe -consoleLog -application org.eclipse.equinox.p2artifact.repository.mirrorApplication….

    It always launches zosexplorer

Join The Discussion

Your email address will not be published. Required fields are marked *