December 2020
I have had a couple of individuals ask me if it is possible to install KICKS on an MVS 3.8j system built using my installation instructions. The answer is yes, and I have installed it in the past on at least two systems I have built. The author of the KICKS system, Mike Noel has written an extensive set of documentation for installing and using KICKS, but I have decided to include a step by step guide to an installation on my own system here that might be of use to some who have not yet had a lot of experience installing on MVS 3.8j.
KICKS is a transaction processing system, modeled on CICS, IBM's for-charge transaction processing system. KICKS provides a high level of source code compatibility with CICS. You can migrate applications either way between CICS and KICKS simply by recompiling. KICKS cannot support the volume of users that CICS is able to, but has been demonstrated to be capable of supporting several hundred simultaneous users. KICKS may also be used to develop applications under MVS 3.8j that may then be uploaded to an IBM system running z/OS and CICS, where they may then be compiled and executed under CICS. KICKS is also an excellent platform for learning CICS programming skills.
As I write this the current version of KICKS is 1.5.0, updated in 2014. The documentation indicates later releases were planned, but have not appeared on the targeted release dates, so it is possible that development has stalled. Nevertheless, this is an excellent product and is worth the time and effort to install and utilize on MVS 3.8j.
The KICKS forum was migrated from Yahoo groups to https://groups.io/g/KICKSforTSO when Yahoo Groups ceased to exist, although it is not a very active group. There is documentation available from the KICKS website http://www.kicksfortso.com/, but it is necessary to acquire the installation archive from https://github.com/moshix/kicks.
The first step is to download the master archive for KICKS available from GitHub: wget https://github.com/moshix/kicks/archive/master.zip. This archive contains the installation archives for both TSO and CMS, so you will need to extract from the archive the folder kicks-tso-v1r5m0, which contains the necessary files for installing on MVS 3.8j as well as the installation and documentation for KICKS. I will also make this archive available for download from my site: kicks-tso-v1r5m0.zip [1.6 mB MD5: fd8928b7183ecd133146fd050ff9f149].
The MVS 3.8j systems I build and use do not have any security system installed. I find little use for a security system in an environment where I am the sole user, and having one active is simply a nuisance. If you are installing on a system where a security system is installed, it may be necessary to make additional allowances for KICKS to function properly under the control of a security system.
In previous installations of KICKS on my own systems I have not made provision for multiple TSO User IDs to have access to the KICKS system, but as I write these instructions from my notes it is my intention to document the installation of KICKS in such a manner that KICKS programs may be executed by any TSO User ID on the system. I will be preparing a new 3350 DASD image to contain the KICKS system, so that is the first step in restoration of the installation archive on my MVS 3.8j system. I have chosen to use a 3350 image, rather than a larger capacity DASD type, because a 3350 is more than adequate to hold the initial KICKS datasets and allow for quite a bit of user datasets to still be created on the same volume.
I use the dasdinit utility (included with Hercules) to create an empty 3350 DASD image in my DASD subdirectory:
dasdinit -a kicks0.3350 3350 111111
I attach the DASD image to my running Hercules/MVS 3.8j system with the Hercules' console command:
attach 351 3350 dasd/kicks0.3350
I use ICKDSF to initialize the DASD and write the Volume Table of Contents:
//ICKDSF JOB 1,ICKDSF,CLASS=A,MSGCLASS=X //* ***************************************************************** * //* * USE FOR 3350 | 3330 | 3340 | 2314 * //* ***************************************************************** * //* //ICKDSF EXEC PGM=ICKDSF,REGION=4096K //SYSPRINT DD SYSOUT=* //SYSIN DD * INIT UNITADDRESS(351) VERIFY(111111) - VOLID(KICKS0) OWNER(HERCULES) - VTOC(0,1,15) //
The output from this job may be viewed at ickdsf.pdf.
I can now vary the DASD volume online and mount it as a private volume with the MVS console commands:
v 351,online m 351,vol=(sl,kicks0),use=private
I edit my Hercules' configuration file to add the new DASD volume to my configuration, so that it will be present when MVS is restarted, and I edit the SYS1.PARMLIB(VATLST00) member to add the volume to the Volume Attribute List so that when MVS starts the volume will be mounted with the proper attributes:
KICKS0,0,2,3350 ,N KICKS LIBRARIES/DATA (PRIVATE)
I use IDCAMS to set up a User Catalog on the KICKS0 volume:
//IDCAMS JOB (1),IDCAMS,CLASS=A,MSGCLASS=X //IDCAMS01 EXEC PGM=IDCAMS,REGION=4096K //SYSPRINT DD SYSOUT=* //KICKS0 DD UNIT=SYSALLDA,DISP=OLD,VOL=SER=KICKS0 //SYSIN DD * DEFINE USERCATALOG ( - NAME (UCKICKS0) - VOLUME (KICKS0) - TRACKS (7500 0) - FOR (9999) ) - DATA (TRACK (15 5) ) - INDEX (TRACKS (15) ) - CATALOG (SYS1.VSAM.MASTER.CATALOG/SYSPROG) DEFINE ALIAS ( - NAME (KICKS) - RELATE (UCKICKS0) ) - CATALOG (SYS1.VSAM.MASTER.CATALOG/SYSPROG)
In the job above, I have allocated 7,500 tracks (250 cylinders) of the volume to the VSAM Dataspace and sub-allocated the catalog space using 15 tracks. The remainder of the data space will be available for VSAM objects that may be defined and used for KICKS user data. The output from this job may be viewed at idcams.pdf.
There are several methods that may be used to transfer an XMIT to MVS 3.8j, and I have discussed these methods in other areas of my site, but for this application I will be using the quickest, single-step method, which is to use the program RECV370 to read the XMIT file on the host system through an emulated MVS card reader and create the dataset on MVS that is contained within the XMIT file.
There is a prototype job in SYSC.JCLLIB(RECV370) that may be quickly tailored to the needed requirements. Here is the completed JCL for the job:
In the JCL above, the input dataset (XMITIN DD statement), you are specifying the exact address of a card reader that is emulated by Hercules. On the Hercules command window, initialize the card reader to point to the file on your host Operating System that holds the XMIT to be transferred. The Hercules command is devinit 01c <path>/kicks-tso-v1r5m0.xmi ebcdic. You should specify the correct path to the file in place of <path> in the example command. Note: This command specifies address x'01c' which is the correct address for an MVS system built using my instructions. The address specified must match a device in your MVS system that is defined as a card reader and that card reader must not be managed by JES2. It is also imperative that you include the ebcdic operand to inform Hercules to not do ASCII to EBCDIC translation when the host Operating System file is read in.
The output dataset should be named KICKS.V1R5M0.INSTALL, as it will be referenced in the instructions below. The dataset will be placed on volume KICKS0, which you prepared in the step above, and it will be cataloged in the User Catalog UCKICKS0.
Submit the job to MVS to transfer the XMIT dataset to MVS and unpack it. The output for this job may be viewed at recv370.pdf.
The dataset loaded from the XMIT contains 29 members. Of these, 26 are additional embedded XMIT files that will be expanded to create the KICKS installation datasets. The final member of this dataset - V1R5M0 - is the jobstream to expand the 26 embedded XMIT files.
Edit the V1R5M0 member to make the following changes:
Before: //RCVKICK2 JOB CLASS=C,MSGCLASS=A,MSGLEVEL=(1,1),REGION=4096K
After: //RCVKICK2 JOB (1),RCVKIK2,CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1),
// REGION=4096K
//JOBLIB DD DISP=SHR,DSN=SYSC.LINKLIB
Before: //RECV PROC UID=HERC01,MEM=DUMMY,MEM2=DUMMY,TRK=30,MLQ=KICKS
After: //RECV PROC UID=KICKS,MEM=DUMMY,MEM2=DUMMY,TRK=30,MLQ=KICKS
Before: //XMITIN DD DSN=&UID..KICKS.V1R5M0.BIGPDS(&MEM),DISP=SHR
After: //XMITIN DD DSN=KICKS.V1R5M0.INSTALL(&MEM),DISP=SHR
Before: // UNIT=SYSALLDA,
After: // UNIT=SYSALLDA,VOL=SER=KICKS0,
Submit the modified jobstream to expand the remainder of the installation datasets. The output of this job may be viewed at recv370_2.pdf.
After this job successfully executes, you may delete the dataset KICKS.V1R5M0.INSTALL, as it is no longer needed.
A CLIST is provided that will assist in the customization of the KICKS installation. However, that CLIST, and probably the CLIST that will be used to start the KICKS system later, require the capability of dynamically allocating a large number of datasets as they execute. An MVS 3.8j installation built using my instructions has a limit of 20 dynamically allocated datasets per TSO session, so this number needs to be increased. The catalogued procedure that is used to create TSO sessions is located in SYS1.PROCLIB and, unless there have been modifications since the system was generated, the name of the member is IKJACCNT. You can verify the name of the active procedure by looking at the main panel of RPF, where the active procedure is shown in the field TSO-proc:
Edit SYS1.PROCLIB(IKJACCNT) and change the DYNAMNBR parameter to 64:
Before: //IKJACCNT EXEC PGM=IKJEFT01,DYNAMNBR=20,
After: //IKJACCNT EXEC PGM=IKJEFT01,DYNAMNBR=64,
Save the changes, then log off and back on so that the change becomes active for your TSO session.
The TSO User IDs created by my TSONUSER procedure will have a REGION size of 4096, which is the minimum recommended in the KICKS User Guide. If you write applications that open many VSAM datasets simultaneously, it may be necessary to increase the size of your REGION, which is defined by the SIZE parameter of the TSO User ID in the TSO ACCOUNT command.
There are two types of datasets for KICKS: 'system' and 'user'. The 'system' files can be recognized by the second node of the dataset name: KICKSSYS. We will be installing the system with all KICKS datasets having a High Level Qualifier of KICKS, so 'system' datasets will be recognizable as KICKS.KICKSSYS.
Use the PROFILE TSO command to change your prefix to KICKS:
Execute the CLIST KFIX:
Pressing ENTER cycles through the possible High Level Qualifiers. The one you should select is KICKS, which is the second one presented. When you see KICKS, type yes and press ENTER again to complete the CLIST:
Use the PROFILE TSO command to change your prefix back to NOPREFIX:
There are three jobs in KICKS.KICKS.V1R5M0.INSTLIB: LOADMUR, LOADSDB, and LOADTAC. Each of these jobs create test data for KICKS example transactions that have been supplied with KICKS. Edit each of the jobs to make the following changes:
- Add an account number to the JOB card, add a programmer name parameter, change the class to A, and the MSGCLASS to X:
Before: //MURACH JOB CLASS=C,MSGCLASS=A,MSGLEVEL=(1,1),REGION=1024K
After: //MURACH JOB (1),LOADMUR,CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1),
// REGION=1024KBefore: //LOADSDB JOB CLASS=C,MSGCLASS=A,MSGLEVEL=(1,1),REGION=1024K
After: //LOADSDB JOB (1),LOADSDB,CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1),
// REGION=1024KBefore: //TACDATA JOB CLASS=C,MSGCLASS=A,MSGLEVEL=(1,1)
After: //TACDATA JOB (1),TACDATA,CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
- Change all instances of the VOLUMES parameter from PUB002 to KICKS0.
Submit the jobs to create the test datasets. The output from these jobs may be viewed at murach.pdf, loadsdb.pdf, and tacdata.pdf.
There are two jobs in KICKS.KICKSSYS.V1R5M0.INSTLIB: LODINTRA and LODTEMP. LODINTRA defines and initializes the Intrapartition Transient Data Queue. LODTEMP defines and initializes the Temporary Storage Queues.
- Add an account number to the JOB card, add a programmer name parameter, change the class to A, and the MSGCLASS to X:
Before: //LODINTRA JOB CLASS=C,MSGCLASS=A,MSGLEVEL=(1,1)
After: //LODINTRA JOB (1),LODINTRA,CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)Before: //LODTEMP JOB CLASS=C,MSGCLASS=A,MSGLEVEL=(1,1)
After: //LODTEMP JOB (1),LODTEMP,CLASS=A,MSGCLASS=X,MSGLEVEL=(1,1)
- Change all instances of the VOLUMES parameter from PUB002 to KICKS0.
Submit the jobs to create the KICKS system datasets. The output from these jobs may be viewed at lodintra.pdf, and lodtemp.pdf.
You now have 44 datasets on the KICKS0 volume and 6,816 tracks of available non-VSAM space, as well as the almost half of the volume in available VSAM data space. The VSAM files created for the datasets above are allocated as UNIQUE, so they are created out of the non-VSAM space on the volume.
Only some of the datasets created during installation will be relevant to MVS 3.8j use of KICKS. Of those, some will only be relevant if you plan to code CICS programs in COBOL.
There is a CLIST provided that starts the KICKS system and prepares it for executing user applications: KICKS.KICKSSYS.V1R5M0.CLIST(KICKS). However, there is an error in this CLIST that must be corrected. On line #145 there is an allocation command:
ALLOC FILE(SKIKLOAD) DSN('&TSOID..KICKS.&VER..SKIKLOAD' +
'&KIKID..KICKS.&VER..SKIKLOAD' +
'&KIKID..KICKSSYS.&VER..SKIKLOAD' +
) SHR BLKSIZE(32760)
The second dataset does not exist. Edit the CLIST member, delete this line so that the command reads:
ALLOC FILE(SKIKLOAD) DSN('&TSOID..KICKS.&VER..SKIKLOAD' +
'&KIKID..KICKSSYS.&VER..SKIKLOAD' +
) SHR BLKSIZE(32760)
and save. At a READY prompt, issue the command: EXEC 'KICKS.KICKSSYS.V1R5M0.CLIST(KICKS)'. There will be a screen of startup information displayed. Press ENTER to see the KICKS color banner screen:
Each time you press Enter on this screen, the colors will change and the time will update. The screen will also automatically update periodically after a preset delay period has expired.
Pressing PF1 will show a screen of help information.
To execute any KICKS (CICS) application, you press CLEAR and enter the four character transaction identification.
To bring the KICKS system to an orderly shutdown, press CLEAR to see a blank screen and enter the sign off transaction: KSSF and press ENTER. You will see the signoff message:
After shutting down KICKS I consistently see that the READY prompt does not appear until I press ENTER again, then I see two READY prompts in succession. I also consistently experience what seems to be a requirement to execute a non-critical TSO command, such as TIME or DATE, a couple of times before TSO seems to become synchronized with the screen. This is not a major problem, but may be something you need to be aware of.
From the KICKS installation documentation:
KICKS is installed with a terminal driver (2$) that should work with any version of Tur(n)key MVS. It also includes the higher function Z/OS terminal driver (1$) that will work if you have a 'recent' Tur(n)key version (such as "TK4-"). You can try this driver by starting KICKS with "KICKS TCP(1$)". If this works you could change the KICKS clist to use 1$ instead of 2$ (end of line 5).
The higher function driver will work on MVS 3.8j built following my installation tutorial, so you may want to edit the KICKS CLIST - KICKS.KICKSSYS.V1R5M0.CLIST(KICKS) - and change the TCP parameter (in line 5) to:
KCP() PCP() FCP() DCP() SCP() TSP() BMS() TCP(1$)
It is possible to start the KICKS system from any TSO User ID on your system using the EXEC command shown above to execute the 'KICKS' CLIST provided in KICKS.KICKSSYS.V1R5M0.CLIST. However it will be more convenient to use one of these three methods to make the KICKS CLIST available to any TSO User IDs that you want to be able to utilize KICKS.
- Add KICKS.KICKSSYS.V1R5M0.CLIST into your SYSPROC concatenation, or
- Copy the KICKS CLIST from KICKS.KICKSSYS.V1R5M0.CLIST into SYS1.CMDPROC, or
- Copy the KICKS CLIST from KICKS.KICKSSYS.V1R5M0.CLIST into the <TSO User ID>.CLIST for each TSO User you want to enable KICKS for.
KICKS operation, like CICS, is controlled through tables. The tables are maintained by assembling load modules that are loaded by KICKS during initialization.
The SIT is a list of table and program suffixes and other startup parameters. It is generated with the KIKSIT macro, as below, with the values shown being the defaults.
KIKSIT SUFFIX=00, suffix for system initialization table DCT=00, suffix for destination control table FCT=00, suffix for file control table PCT=00, suffix for task control table PPT=00, suffix for program control table BMS=00, suffix for basic mapping support DCP=00, suffix for destination control FCP=00, suffix for file control KCP=00, suffix for task control PCP=00, suffix for program control TCP=00, suffix for terminal control TSP=00, suffix for temp storage control OPID=999, 3 char (numeric?) 'operator id' NATLANG=E, 1 char language code TRCNUM=100, # entries in the internal trace tbl TRCFLAG=1, trace control startup configuration DMPCLAS=A, sysout class for 'spin off' dumps ICVR=5000, time (milliseconds) to AICA MAXDELY=180, max time (seconds) for a 'DELAY' PLTPI=KSGM, first transaction PLTSD=K999, last transaction CWAL=100, size (characters) of CWA TCTUAL=100, size (characters) of TCTTEUA FFREEKB=NO, whether to force terminal freekb ENQSCOP=SYSTEMS must be SYSTEM or SYSTEMS SYNCPGM= name of syncpoint exit, or null
There are detailed explanations of all the settings in this table in the KICKS documentation. The default settings should be adequate for most users. The jobstream to assemble and link the SIT may be found in KICKS.KICKSSYS.V1R5M0.INSTLIB(KIKSIT1$). Note that there are two additional SIT jobstreams in this dataset, with suffixes other than 1$, that serve special purposes.
The PPT is a list of programs residing in the KIKRPL concatenation. It is generated with the KIKPPT macro, as below, with the values shown being the defaults. For historical reasons PPT is "Processing Program Table" in CICS, but that full title is seldom used, it's almost always simply called "the PPT". When you add a new mapset or program to KICKS, you must make additions to the PPT for them.
KIKPPT SUFFIX=00, suffix for program control table TYPE=ENTRY, INITIAL, ENTRY, or FINAL PROGRAM=, MAPSET=, USAGE=, PGMLANG=CMDLVL, LOAD=DEFERRED, INITIAL or DEFERRED PGMSTAT=ENABLED ENABLED or DISABLED
The jobstream to assemble and link the PPT may be found in KICKS.KICKSSYS.V1R5M0.INSTLIB(KIKPPT1$).
Note that there are two additional PPT jobstreams in this dataset, with suffixes
other than 1$, that serve special purposes.
The PCT is a list of transactions and associated programs to be run when the transactions are started. It is generated with the KIKPCT macro, as below, with the values shown being the defaults. For historical reasons PCT is "Processing Control Table" in CICS, but that full title is seldom used, it's almost always simply called "the PCT". When you add a new transaction program to KICKS, you must make a addition to the PCT for it.
KIKPCT SUFFIX=00, suffix for task control table TYPE=ENTRY, INITIAL, ENTRY, or FINAL TPURGE=,SPURGE=,TRANSEC=, TRANSID=, PROGRAM=, TWASIZE=0, 0-1024 KPOPEN=DISABLED, ENABLED or DISABLED ISTAT=ENABLED ENABLED or DISABLED
The jobstream to assemble and link the PCT may be found in KICKS.KICKSSYS.V1R5M0.INSTLIB(KIKPCT1$). Note that there are two additional PCT jobstreams in this dataset, with suffixes other than 1$, that serve special purposes.
The FCT is a list of VSAM files. It is generated with the KIKFCT macro, as below, with the values shown being the defaults. If you add a transaction/program that utilizes a VSAM dataset that has not been defined to KICKS previously, you must make an addition to the FCT for it.
KIKFCT SUFFIX=00, suffix for file control table TYPE=DATASET, INITIAL, DATASET, or FINAL FILSTAT=ENABLED, ENABLED or DISABLED NUMREQ=, DATASET=, BASE=, CATUSER=CMSUSER, CATLNK1=194, CATLNK2=222, CATPASS=WRITE, CATFM=O, CATVOL=VSAMIN
The last six parameters are only used in CMS, so will not be coded for MVS 3.8j systems.
The jobstream to assemble and link the FCT may be found in KICKS.KICKSSYS.V1R5M0.INSTLIB(KIKFCT1$). Note that there are two additional FCT jobstreams in this dataset, with suffixes other than 1$, that serve special purposes.
The DCT is a list of destination queues your program can access with the READQ and WRITEQ api’s.
This version of KICKS supports extrapartition and indirect destination queues.
Extrapartition destinations are sequential files, often SYSIN or SYSOUT datasets.
Application logs for example are often extrapartition destinations written using the WRITEQ TD api.
Indirect destinations are aliases for other destinations and can be used to consolidate output. Suppose you have 5 different applications that want to write various log messages.
One refers to destination MLOG. Another to LOG1. The other 3 to SLOG.
You could define 3 separate logs, each an extrapartition destination, or you could define one extrapartition destination and two indirect destinations pointing to the single extrapartition destination.
The applications won't know or care this is going on. It's pretty common on CICS systems to define a single logging destination and then use indirect destinations to route all application logging to the common log.
The DCT is generated with the KIKDCT macro, as below, with the values shown being the defaults.
KIKDCT SUFFIX=00, suffix for destination control table TYPE=EXTRA, INITIAL, EXTRA, INTRA, INDIR or FINAL DESTID=, PHYDEST=, FILE=, TYPEFIL=INPUT, ISTAT=ENABLED, ENABLED or DISABLED OPEN=INITIAL
The jobstream to assemble and link the DCT may be found in KICKS.KICKSSYS.V1R5M0.INSTLIB(KIKDCT1$). Note that there are two additional DCT jobstreams in this dataset, with suffixes other than 1$, that serve special purposes.
There are several demonstration programs included and installed with KICKS. Some of them are based on chapters in Murach's CICS for the COBOL Programmer. As with most textbook programs, they are not particularly useful or user-friendly, as they were mostly designed to illustrate coding concepts. But the source code is included in KICKS.KICKS.V1R5M0.COB. See the $README member for an index of the programs. The source for the mapsets is included in KICKS.KICKS.V1R5M0.MAPSRC. See the $README member for an index of the maps.
The PROCs for assembling mapsets and for compiling application programs with the MVT COBOL compiler are included in KICKS.KICKSSYS.V1R5M0.PROCLIB. You will need to copy the procedures you need to use into a PROCLIB on your system, for example: SYS2.PROCLIB.
I hope that you have found my instructions useful. If you have questions that I can answer to help expand upon my explanations and examples shown here, please don't hesitate to send them to me:
Return to Site Home Page Frequently Asked Questions
This page was last updated on April 30, 2022 .
