RKTools installation

RKTools (Rocket Tools for Model 204) is a set of application subsystems (aka APSYs) running inside a Model 204 Online that provide 3270 and web-based tools for programmers, database administrators, and system managers. RKTools was formerly known as UL/SPF.

Installing RKTools requires downloading the SIRIUS file from the Model 204 maintenance website, and restoring it to your environment, setting up some subsidiary Model 204 files, and verifying that the environment has the appropriate parameter settings.

Upgrades to RKTools can almost always be handled by restoring a fresh copy of the SIRIUS file.

Download the installation file

All RKTools code resides in the SIRIUS Model 204 file. You will need to download a dump version of this file from the Rocket Software Model 204 maintenance website.

To download from the Rocket website:

1. On the Rocket M204 Customer Care page, go to the "Downloads and Uploads" section and select the "Download SOUL files" link to access the "SOUL files for Rocket Software" page.
2. Log in, and download the latest version of the SIRIUS file (which is labeled "All RKTools products in one file" followed by a version number).

   A "Click here" link on this page provides help about downloading and uploading files, file sizing, and more.

Reinstalling RKTools (for example, simply picking up the latest SOUL updates) typically involves nothing more than downloading and restoring a new version of the SIRIUS file.

You can bypass any step of the installation that applies only to a RKTools module you are not installing.

System requirements

• RKTools operates in a Model 204 Online region of the same or higher release number as RKTools. In other words, version 7.5 of RKTools requires Model 204 version 7.5 or higher.
• Requirements for server sizes and parameter settings for each product are listed in RKTools server sizes.
• To verify the products for which your online is authorized, enter ROCKET at the Model 204 command line.
• The installing user must have:
  • update access to the JCL or EXECs that bring up the host Online
  • system manager privileges
  • access to the SUBSYSMGMT facility and the JCL or EXEC that runs the Online Model 204 region.
• If you are upgrading from a previous version or maintenance level, your site already has a SIRLOCAL file, which holds users' profiles and other local customizations. Your existing SIRLOCAL should be left intact and allocated to the Online, because the installation process uses SIRLOCAL information to determine which features should be upgraded.

Installing RKTools

Attention: If you are upgrading from a previous release, keep your old copies of SIRLOCAL and any application-specific data files, such as JANCAT, SIRLIBD, SIRFILED, or SIRSTATS. The installation process uses these files to determine whether to perform upgrade actions or new-installation actions.

1. Allocate the space required for the RKTools files.
   • If you are restoring into your existing SIRIUS file, note that the SIRIUS file has X'0221' privileges, which does not allow RESTORE. You will have to CREATE the file first (to wipe out existing content) before you execute the RESTORE. A sample command sequence is:

     CREATE FILE SIRIUS END CREATE OPEN FILE SIRIUS IN SIRIUS RESTORE 192 FROM dumpfile

   The following table shows the RKTools files and their sizes.

   File	Size	Allocation is required...
   SIRIUS	4200 pages	always
   SIRLOCAL	1200 pages	always
   SIRSTATS	4000 pages	only if installing SirMon
   SIRFILED	1200 pages	only if installing SirFile
   SIRLIBD	1200 pages	only if installing SirLib
   SIRLIBP	1200 pages	only if installing SirLib
   JANCAT	1200 pages	only if installing Janus OMNI
   JANSSL	1200 pages	only if installing Janus SSL

2. RESTORE SIRIUS from the downloaded DUMP file.
3. Update the Online JCL or EXEC:
   1. Add DD (MVS) cards or FILEDEFs (CMS) for the RKTools files. The following table lists the files for which DD cards or FILEDEFs might be needed:

      File	Allocation is required...
      SIRIUS	always
      SIRLOCAL	always
      SIRSTATS	only if installing SirMon and using the web interface
      SIRFILED	only if installing SirFile
      SIRLIBD, SIRLIBP	only if installing SirLib
      JANCAT	only if installing JANUS OMNI Access Module
      JANSSL	only if installing JANUS SSL Module

   2. Verify that the Online environment allows the use of file groups and APSY subsystems.
      • To use permanent file groups, the Online must have allocated an initialized CCAGRP file, and the SYSOPT parameter must contain the 2 bit.
      • To use APSYs, an Online must have allocated an initialized CCASYS file (with all fields defined), and the SYSOPT parameter must contain the 1 bit.
      For more information about APSYs and file groups, see File groups and System requirements for Application Subsystems.
4. Verify that the Online has a minimum of 10 Sdaemon threads allocated. Each of these threads is typically defined as IODEV15.
5. Modify the User 0 stream.

   Adjust these parameters:

   Parameter	Adjustment
   NFILES	Increase by the number of RKTools files.
   NDCBS	Increase by the number of RKTools files.
   NDIR	Increase by the number of RKTools files.
   NORQS	Verify that the setting is at least 5.

6. Issue OPEN FILE SIRIUS (no password is required), and execute the following command:

   INCLUDE RKTOOLS_INSTALL

   This procedure performs all installation functions for new users and all upgrade functions for reinstalling users. No user profiles or other site-specific customization will be lost. If any problems are encountered while running this procedure, correct the problems and re-execute.

   The procedure RKTOOLS_INSTALL also builds an APSY subsystem called RKINSTALL. If installations need to be re-run, the subsystem may be invoked rather than the procedure.

   During APSY execution, some error messages are not suppressed, which aids in diagnosing any installation problems. For example, you will be able to see if an installation failed because a file was enqueued in a different Online, and so on.
7. Use SUBSYSMGMT to add users to the appropriate SCLASSes for any private or semi-public RKTools APSYs.

   The installing user is automatically added to the administration SCLASS in all RKTools APSYs.

8. Review the RKTools server size section for specific requirements of individual APSY components of RKTools.

Note: CCATEMP usage might increase with RKTools. CCATEMP should be monitored (VIEW TEMPSIZE, VIEW TEMPMAX) to ensure that sufficient space is allocated to accommodate the additional activity.

RKTools server sizes

The minimum RKTools server size requirements are listed below. The actual server size requirements might vary slightly because of table settings in the local Online Model 204 regions, and because of slight differences between UTABLE requirements in different versions of Model 204.

Subsystem name	Minimum server size
SIRSCAN	250K
SIRDBA	180K
SIRFILE	230K
SIRPRO	750K
SIRLIB	135K
SIRADMIN	150K
SIRMON	220K
RKTools	135K

UTABLE and parms

Initial problems with RKTools subsystems are usually associated with one or two extremely small default UTABLE settings. Running the failing APSY in TEST DEBUG mode will highlight UTABLE parameters that need to be increased.

Note: One parameter that must be set for SIRMON, SIRPRO, and SIRSCAN is SCRNSTBL, which is necessary for the use of screen objects.

RKTools required parameter minimums
Parameter	Value
SCRNSTBL	12000

Additional setup for SirLib

Read and follow the instructions in the SirLib "getting started" steps.

Additional setup for SirScan

The SirScan administrator can use SIRADMIN to set default I/O and record maximums for users in the various SirScan SCLASSes. See SirScan setup for details.

Additional setup for SirMon

When users are added to SCLASSes, note that there is a special BUMP SCLASS. Any user added to this SCLASS gains the ability to BUMP other users. This class does not provide access to customizing options in SirMon. Only users in the ADMIN SCLASS are able to add custom screen definitions to SirMon.

If the SirMon background monitor is to be used, add the following line to User 0's input stream:

SIRMON BACKGROUND

The background monitor may also be started automatically in a BATCH2 thread or an sdaemon thread. Consult the SirMon documentation for details.

You can customize statistic thresholds or use the supplied defaults to establish problem conditions.

As of RKTools version 6.8, SirMon has a feature to send warnings to e-mail addresses and cell phones (via e-mail). This feature requires Janus Sockets and a started Janus Sockets port.

Additional setup for SirFile

If the SirFile background monitor is to be used, add the following line to User 0's input stream:

SIRFILE BACKGROUND

As with SirMon, the background monitor may be started automatically in a BATCH2 thread or in an sdaemon thread, and you can consult the SirFile User's Guide for details.

You can customize the system and file-specific thresholds or use the supplied defaults to establish problem conditions.

RKTools access privileges and SCLASSes

Each component application of RKTools has its own APSY definition and privileges associated with SCLASSes. If you have a good reason for doing so, you can redefine any of the RKTools APSYs as PUBLIC, SEMI-PUBLIC, or PRIVATE. Contact Rocket Software if you are unsure of the effect of a proposed change.

RKTools components are installed as auto-start. Use SUBSYSMGMT to disable this feature if you prefer the subsystems not start automatically at each user request.

RKTools on the Web

Web-specific versions of the RKTools subsystems are actively being developed and supported, and they are available to sites that own Janus Web Server.

All the RKTools APSYs can be used on the web via Janus Web Legacy Support, which simply translates the 3270 screens of the underlying product into HTML. Web-specific versions of both SirScan and SirMon can be invoked by setting up some Janus Web Server web rules.

Setup for web-based SirScan

Web-based SirScan is very lightweight, and requires a minimum of web rules to run.

1. Define a Janus Web Server port.
2. Define the following rule to invoke SirScan:

   JANUS WEB portname ON /SIRSCAN/* CMD 'SIRSCAN *'

3. The above rule will make SirScan available, but it will not necessarily require a logon to the system, so you will need to add rules to force users to log in as well:

   JANUS WEB portname DISALLOW /SIRSCAN/* JANUS WEB portname ALLOW /SIRSCAN/* USER *

4. Because the above rules force users to login, the port on which SirScan runs should either:
   • Be only on a company intranet.
   • Be SSL protected, to prevent userids and passwords from being sent over the internet in clear text format.

   The above rules will work on an unprotected port, but it is very strongly recommended that this feature only be used when SSL protection is in effect.

Setup for web-based SirMon

This applies only to RKTools version 8.1 and later.

Because web-based SirMon employs XML, XSLT, Javascript, a stylesheet and some graphics, the web rules needed to run SirMon on the web are a little more complex:

1. Define a Janus Web Server port.
2. Define the following rules to invoke SirMon:

   JANUS WEB portname TYPE ANY *.PNG IMAGE/PNG JANUS WEB portname TYPE ANY *.CSS TEXT/CSS JANUS WEB portname TYPE ANY *.JS APPLICATION/X-JAVASCRIPT JANUS WEB portname ON /*.CSS OPEN SIRIUS SEND *.CSS JANUS WEB portname ON /SIRMON/* CMD SIRMON JANUS WEB portname ON /SIRMON/*.GIF OPEN SIRIUS SEND *.GIF EXPIRE +2147483 JANUS WEB portname ON /SIRMON/*.PNG OPEN SIRIUS SEND *.PNG EXPIRE +2147483 JANUS WEB portname ON /SIRMON/*.JS OPEN SIRIUS SEND *.JS BINARY EXPIRE +2147483 JANUS WEB portname ON /AJAX/* OPEN SIRIUS SEND * JANUS WEB portname ON /AJAX/*.JS OPEN SIRIUS SEND *.JS TEXT JANUS WEB portname ON /AJAX/*.UL OPEN SIRIUS CMD 'INCLUDE *.UL' JANUS WEB portname DISALLOW /SIRMON/* JANUS WEB portname ALLOW /SIRMON/* USER * JANUS WEB portname TYPE ANY *.XML TEXT/XML JANUS WEB portname TYPE ANY *.XSL TEXT/XSL JANUS WEB portname ON /SIRMON/*.XSL OPEN SIRIUS SEND *.XSL EXPIRE +2147483 JANUS WEB portname ON /SIRMON/*.CSS OPEN SIRIUS SEND *.CSS EXPIRE +2147483 JANUS WEB portname ON /SIRMON/TEXTJS/*.JS OPEN SIRIUS SEND *.JS TEXT EXPIRE +2147483 JANUS WEB portname ON /SIRMON/BUILDJS/*.JS CMD SIRMON OPEN SIRSTATS IN SIRSTATS INITIALIZE KEEPDEFS

3. The above rules will make SirMon available, but they will not necessarily require a logon to the system, so you will need to add rules to force users to log in as well:

   JANUS WEB portname DISALLOW /SIRMON/* JANUS WEB portname ALLOW /SIRMON/* USER *

4. Because the above rules force users to login, the port on which SirMon runs should either:
   • Be only on a company intranet.
   • Be SSL protected, to prevent userids and passwords from being sent over the internet in clear text format.

   The above rules will work on an unprotected port, but it is very strongly recommended that this feature only be used when SSL protection is in effect.

   Note: Using SirMon on the web also requires the SIRSTATS file. As shown in the above web rules, SIRSTATS can be re-initialized each time the Online comes up. SIRSTATS contains historical snapshots of system performance, and the file will fill up if not archived or reinitialized on occasion.