KICKS
A
transaction processing system for
CMS &
TSO
Below is a copy of the official documentation for KICKS 1.5.0 as a backup just in case.
Configuration
The tables
Most of KICKS configuration is done by assembling option tables. In this version there are five tables – the System Initialization Table (SIT), the File Control Table (FCT), the Task Control Table (PCT), the Destination Control Table (DCT), and the Program Properties Table (PPT).In TSO the tables are assembled into load modules in userid.KICKS.V1R5M0.SKIKLOAD (searched first) or userid.KICKSSYS.V1R5M0.SKIKLOAD. In CMS the tables are assembled into object decks in KIKULOD TXTLIB (searched first) or KIKSLOD TXTLIB. The table objects themselves are named KIKSIT?? (SIT), KIKFCT?? (FCT), KIKPCT?? (PCT), KIKDCT?? (DCT), and KIKPPT?? (PPT) where ?? represents the 2 character load module suffix. Since the table names have these suffixes many version of each table can be present in the library, selected by suffix when KICKS starts up. Suffixes 0? and ?$ (where ? is any character) are reserved, meaning I might use them so you should not. All other combinations (that result in valid PDS member names) are available. You should establish your own convention of suffix use – for example you might use @1, @2, - or A1, A2, – or 1A, 1B, – whatever you like.
With many different suffixed version of tables how does KICKS know which ones to use? By default it will use a suffix of 00 for all tables. If you want it to use something else you have to tell it. How do you tell it? In one or more ways:
-
When you start KICKS you can pass it a list of parameters (PARMS) which KICKS expects to be things like SIT table arguments (see following SIT discussion). Among these are suffix specifiers like ‘SIT=3$’. If you look at the KICKS clist in TSO you will see something like this going on:
or, looking at the KICKS exec in CMS
which results in KICKS using KIKSIT1$ instead of the default KIKSIT00. You might notice this also runs a suffixed version of KIKSIP (the KICKS system initialization program). In this case it’s not KICKS itself doing the suffixing, it’s the CLIST/EXEC…
&KICKS SIT=1$
- In TSO KICKS will also read SYSIN looking for these SIT table arguments (one argument per line). KICKS could do this in CMS as well, but the exec has SYSIN dummied...
- Finally KICKS will use the loaded SIT to obtain the suffixes for all the other tables and management modules (except for KIKSIP which can only be suffixed as above).
SYSTEM INITIALIZATION TABLE (SIT)
The SIT is a list of table and program suffixes and of other startup parameters. It is generated with the KIKSIT macro, as below, with the values shown being the defaults.SUFFIX is the suffix for the SIT itself. It should match the suffix used to name the table in the load lib. The KIKSIT macro default is ‘00’ but the supplied SIT assembly job specifies 1$. DCT is the suffix to be used (subject to PARM and SYSIN overrides) for the destination control table. The KIKSIT macro default is ‘00’ but the supplied SIT assembly job, and the supplied DCT assembly job, specify 1$.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 PGM * DCP=00, suffix for destination control PGM * FCP=00, suffix for file control PGM * KCP=00, suffix for task control PGM * PCP=00, suffix for program control PGM * TCP=00, suffix for terminal control PGM * TSP=00, suffix for temp storage control PGM * 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
FCT is the suffix to be used (subject to PARM and SYSIN overrides) for the file control table. The KIKSIT macro default is ‘00’ but the supplied SIT assembly job, and the supplied FCT assembly job, specify 1$.
PCT is the suffix to be used (subject to PARM and SYSIN overrides) for the task control table. The KIKSIT macro default is ‘00’ but the supplied SIT assembly job and the supplied PCT assembly job, specify 1$.
PPT is the suffix to be used (subject to PARM and SYSIN overrides) for the program control table. The KIKSIT macro default is ‘00’ but the supplied SIT assembly job, and the supplied PPT assembly job, specify 1$.
BMS, DCP, FCP, KCP, PCP, TCP and TSP are suffixes for KICKS internal service programs. Although the macro default for them is 00 the supplied SIT overrides this to 1$, which matches the suffixes of the load modules supplied in the KIKSLOD library. Being able to change the KICKS management modules (programs) by suffix is of limited use to you – I usually only supply a few of each (suffixed 0$, 1$, 2$) and those are what you use (or what the KICKS clist selects). 0$ reflect null functionality, 1$ is used for most cases, 2$ if for unusual situations (such as KIKTCP2$ being used for legacy "no lock" terminal support).
OPID is the 3 character operator id that your programs can recover using EXEC KICKS ASSIGN OPID(myvar). Little used now, OPID is a leftover from pre-RACF days when applications all managed their own users. CICS had a table called the SNT (signon) of userids and passwords, with associated OPID’s for each. When you signed on CICS kept a copy of your OPID which it could check against transactions to see if you should be allowed to run them. KICKS implements none of this since a RACF style userid (your TSO id) is already available. But some applications still ask for it (as above). So for compatibility's sake some value must be returned and here is where you can set it to whatever you want it to be! The default is ‘999’, as good as any…
NATLANG is the 1 character operator id that your programs can recover using EXEC KICKS ASSIGN NATLANGINUSE(myvar), and of course also thereby implicitly defines the 3 character result you will obtain using EXEC KICKS ASSIGN LANGINUSE(myvar) as well. The default is 'E', (ENU, American English). A table relating IBM's definition of these codes to each other can be found in SC33-1688 ( CICS Application Programming Reference, available online as DFHP400.PDF ).
TRCNUM is the number of entries in the internal trace table. Each entry is 16 bytes. TRCNUM’s value can be 0 (no internal trace) or any value from 100 to 1000. The default is 100.
TRCFLAG is the initial state of 3 trace controls: whether the internal trace is active (1); whether the auxiliary (external, to file DD AUXTRAC) trace is active (2); and whether events marked as ’intense’ should be traced (8). The default value (1) means the internal trace is active. To combine flags add them, so to enable both the internal and the auxiliary trace set TRXFLAG=3.
These trace controls can be manipulated online using the KSMT transaction, so, for example, you can turn auxiliary trace on and off while KICKS is running. Changing the value using KSMT is only effective until KICKS is shutdown.
DMPCLAS is the sysout class that will be used when you want transaction dumps to print as soon as they are available (instead of waiting until you exit KICKS). The default is class A.
Additional information regarding transaction dumps and the trace table can be found in the Debugging Section of this User’s Guide.
ICVR is the number of milliseconds of elapsed time (not cpu time) to allow a user task to run before killing it with an AICA abend. ICVR’s value can be 0 (no time limit) or any value from 1000 (1 second) to 600000 (10 minutes). The default is 5000 (5 seconds).
This value can also be set up or down online using the KSMT transaction. Changing the value using KSMT is only effective until KICKS is shutdown.
Additional information regarding AICA abends and the ICVR parameter can be found in KooKbooK recipe #4.
MAXDELY is the maximum number of seconds of elapsed time (not cpu time) to allow a user task to delay using the EXEC KICKS DELAY api. The default is 180.
PLTPI is the 4 character transaction id for the first transaction KICKS is to run (before the first user input). The default is ‘KSGM’ (The transaction that put the big color letters ‘KICKS’ on the screen).
PLTSD is the 4 character transaction id for the last transaction KICKS is to run (after the last user input). The default is ‘K999’ (which just does a brief delay to let you see anything left on the screen).
Additional information regarding the PLTPI and PLTSD arguments, and the KSGM/KSSF/K999 transactions can be found in KooKbooK recipes #2 and #3. Source code for the KSGM/KSSF/K999 transactions can be found in KICKS.V1R5M0.COB.
CWAL is the length of the ‘Common Work Area’, or CWA. CWAL’s value can be 0 (no CWA) or any value from 1 to 1024. The default is 100.
TCTUAL is the length of the ‘TCTTE Work Area’, or TCTTEUA. TCTUAL’s value can be 0 (no TCTTEUA) or any value from 1 to 1024. The default is 100.
Additional information regarding the CWA and the TCTTEUA can be found in KooKbooK recipe #5.
FFREEKB is used to tell KICKS whether to force on the FREEKB option for all terminal writes, thus ensuring the keyboard is never locked. Recommend to leave default NO, meaning control over keyboard locked state is up to the application (as is always the case in CICS).
ENQSCOP is the scope value KICKS will use with the VSAM file control ENQ and DEQ macros it issues. ENQSCOP’s value can be SYSTEM or SYSTEMS. The default is SYSTEMS.
SYNCPGM, if specified, is the name of a program (which must also be defined in the PPT) that is to receive control when certain events occur. These events include SYNCPOINT COMMIT, SYNCPOINT ROLLBACK, task initiation, normal task end, and abnormal task end (abend). See HERC01.KICKSSYS.V1R5M0.COB(SYNCXIT) for a sample exit program.
KICKS.V1R5M0.INSTLIB(KIKSIT1$) is the source for the SIT used by default with the KICKS clist. I suggest that instead of modifying it you create a new member – such as KIKSITZZ, perhaps in your own dataset – copy KIKSIT1$ into it, edit it (especially change SUFFIX to ZZ and the name in the SYSLMOD override – 3rd card from the bottom), and submit. To run with your new SIT just start KICKS by typing
KICKS SIT(ZZ)Instead of just
KICKSWhen you add a new application to KICKS you will generally have some programs (these are defined in the PPT), some maps (screen layouts) (also defined in the PPT), some transactions used to initiate the programs (defined in the PCT) some VSAM files (defined in the FCT) and perhaps a new destination (defined in the DCT).
PROGRAM CONTROL TABLE (PPT)
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".SUFFIX is the suffix for the PPT itself. It should match the suffix used to name the table in the load lib. The KIKPPT macro default is ‘00’ but the supplied PPT assembly job specifies 1$.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
TYPE is either INITIAL, ENTRY, or FINAL. Your PPT assembly job should have one leading TYPE= INITIAL, as may TYPE=ENTRY’s as you have programs (or maps) to define, and one trailing TYPE=FINAL.
Your TYPE=INITIAL has only one other argument, SUFFIX.
Your TYPE=FINAL has no arguments.
Your TYPE=ENTRY’s (which may omit TYPE=ENTRY as it is the default) should specify PROGRAM or MAPSET (but not both), PGMLANG or USAGE (but not both), and optionally LOAD and/or PGMSTAT.
PROGRAM is the name of the load module in KIKRPL.
MAPSET is an alias for PROGRAM.
USAGE is a ‘one valid value’ – USAGE=MAP. It means the same as PGMLANG=MAP.
PGMLANG is the programming language used to code the program. It may be CMDLVL, ASSEMBLER, MACC, or MAP. CMDLVL should be used for any program that comes out of one of the preprocessor procs (KIKCOBCL, K2KCOBCL, KIKCB2CL, or KIKGCCCL) - meaning all of your COBOL or GCC programs. ASSEMBLER should be used for non-executable tables (such as KEDFILTR). MACC is used for programs coded with the 'macro level' interface (an undocumented internal interface for some system level transactions). MAP means the same as USAGE=MAP. If you look at the macro you will see some other values (COBOL, COB, MVTCOB, LECOB, GCC, etc) but these are in most cases just aliases for CMDLVL.
Older versions of KICKS had some entries coded with PGMLANG=C. This was the same as what is now MACC. PGMLANG=C has been removed to avoid confusion in how to code PPT entrees for GCCMVS programs, which, as above, should be coded PGMLANG=CMDLVL.
LOAD is used to tell KICKS when to load the program, and may have the value INITIAL or DEFERRED. Recommend to leave in default DEFERRED state.
PGMSTAT is used to tell KICKS whether it is allowed to use the program, and may have the value ENABLED or DISABLED. Recommend to leave in default ENABLED state.
The PPT source is in KICKS.V1R5M0.INSTLIB(KIKPPT1$). I suggest that instead of modifying it you create a new member – such as KIKPPTZZ, perhaps in your own dataset – copy KIKPPT1$ into it, edit it (especially change SUFFIX to ZZ and the name in the SYSLMOD override – 3rd card from the bottom), and submit. To run with your new PPT just start KICKS by typing
KICKS PPT(ZZ)Instead of just
KICKSWhen you look at the PPT source you will see it is just a series of KIKPPT macros. The first is a TYPE=INITIAL and just gives the suffix. The last is a TYPE=FINAL and just provides for final wrap up. In between are TYPE=ENTRY macros that define your maps and programs. The order of the TYPE=ENTRY macros is not significant except that you should use some convention to make it easy for you to find entries you want. Note that the first several TYPE=ENTRY macros are for KSGMPRG, KSGMMAP, and KSSFPRG. These are required entries for the KSGM (good morning message) and KSSF (signoff) programs. In general you should not name programs, transactions, or files with a first character of ‘K’ as these are used by KICKS. Also you should avoid naming these entities with a first character of ‘C’ as that is the equivalent CICS reservation.
Code the TYPE=ENTRY macros for your programs and maps like those in KIKPPT1$: for a COBOL program use
KIKPPT TYPE=ENTRY,PROGRAM=XXXXX,PGMLANG=CMDLVLand for a map use
KIKPPT TYPE=ENTRY, PROGRAM=YYYYY,USAGE=MAPThe PGMLANG keyword provides a couple of other choices (such as ‘C’) but you shouldn’t waste your time trying to get those to work with this KICKS release!
TASK CONTROL TABLE (PCT)
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".SUFFIX is the suffix for the PCT itself. It should match the suffix used to name the table in the load lib. The KIKPCT macro default is ‘00’ but the supplied PCT assembly job specifies 1$.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
TYPE is either INITIAL, ENTRY, or FINAL. Your PCT assembly job should have one leading TYPE= INITIAL, as may TYPE=ENTRY’s as you have transactions to define, and one trailing TYPE=FINAL.
Your TYPE=INITIAL has only one other argument, SUFFIX.
Your TYPE=FINAL has no arguments.
Your TYPE=ENTRY’s (which may omit TYPE=ENTRY as it is the default) should specify TRANSID, PROGRAM, and optionally TWASIZE and/or KPOPEN and/or ISTAT.
TPURGE, SPURGE, and TRANSEC are CICS PCT keywords that are tolerated but not acted upon in a KICKS PCT definition.
TRANSID is the 4 character transaction id that will be used for this transaction.
PROGRAM is the name of a program, named in the PPT, that will be used with this transaction.
TWASIZE is a number that represent the size in bytes of the Transaction Work Area (TWA). TWASIZE’s value can be 0 (no TWA) or any value from 1 to 1024. The default is 0. Additional information regarding the TWA can be found in KooKbooK recipe #5.
KPOPEN is used to tell KICKS whether to release a conversational task's open files for use by other KICKS users when the task does a blocking terminal control read (ie, RECEIVE or RECEIVE MAP). Recommend to leave in default DISABLED state, meaning files will be released.
ISTAT is used to tell KICKS whether it is allowed to use the transaction, and may have the value ENABLED or DISABLED. Recommend to leave in default ENABLED state.
The PCT source is in KICKS.V1R5M0.INSTLIB(KIKPCT1$). I suggest that instead of modifying it you create a new member – such as KIKPCTZZ, perhaps in your own dataset – copy KIKPCT1$ into it, edit it (especially change SUFFIX to ZZ and the name in the SYSLMOD override – 3rd card from the bottom), and submit. To run with your new PCT just start KICKS by typing
KICKS PCT(ZZ)Instead of just
KICKSWhen you look at the PCT source you will see it is just a series of KIKPCT macros. The first is a TYPE=INITIAL and just gives the suffix. The last is a TYPE=FINAL and just provides for final wrap-up. In between are TYPE=ENTRY macros that define your transaction id’s. The order of the TYPE=ENTRY macros is not significant except that you should use some convention to make it easy for you to find entries you want. Note that the first several TYPE=ENTRY macros are for KSGM, CSGM, KSSF, and CSSF. The id’s starting with ‘K’ are for the Good Morning Message program and for the Signoff transaction. The id’s starting with ‘C’ are the equivalent CICS transactions (thus allowing you to type either CSSF or KSSF to logoff).
Code the TYPE=ENTRY macros for your transaction id’s like those in KIKPCT1$: use KIKPCT
TYPE=ENTRY,TRANSID=XXXX,PROGRAM=YYYYYYYYEvery program specified with a PROGRAM keyword in a KIKPCT TYPE=ENTRY must also have a corresponding KIKPPT TYPE=ENTRY,PROGRAM= entry in the active PPT!
FILE CONTROL TABLE (FCT)
The FCT is a list of VSAM files. It is generated with the KIKFCT macro, as below, with the values shown being the defaults.SUFFIX is the suffix for the FCT itself. It should match the suffix used to name the table in the load lib. The KIKFCT macro default is ‘00’ but the supplied FCT assembly job specifies 1$.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
TYPE is either INITIAL, DATASET, or FINAL.
Your FCT assembly job should have one leading TYPE= INITIAL, as may TYPE=DATASET’s as you have files to define, and one trailing TYPE=FINAL.
Your TYPE=INITIAL has one required argument, SUFFIX, and seven optional arguments..
CATUSER, CATLNK1, CATLNK2, CATPASS, CATFM, and CATVOL, used only in CMS and on your TYPE=INITIAL macro, define the VSAM environment for all the files in this FCT. CATUSER, CATLNK1, CATLNK2, and CATPASS are used to link [ ie, CP LINK CATUSER CATLNK1 CATLNK1 WRITE CATPASS ] to a DOS formated mini-disk holding the VSAM catalog and space (which in turn holds all the files). CATLNK2 and CATFM are used to associate that linked mini-disk with a drive letter [ IE, ACC CATLNK2 CATFM ]. CATVOL is used by various utilities (such as AMSERV) that need to know the volser of the mini-disk. So CATUSER is the 'owner' logon id of the VSAM minidisk, CATLNK1 is the virtual device address in his virtual machine, CATLNK2 is the virtual device address in your virtual machine, CATPASS is the write password for the minidisk, CATFM is the drive letter in your virtual machine, and CATVOL is the volser of the mini-disk.
NUMREQ is the maximum number of concurrent but independent browses that will be active. It is specified on the TYPE=INITIAL macro to set the default for the files that follow. The default is 10. The minimum value is 1. The maximum value is 15.
Your TYPE=FINAL has no arguments.
Your TYPE= DATASET’s (which may omit TYPE=DATASET as it is the default) should specify DATASET and optionally FILESTAT and/or NUMREQ and/or BASE.
DATASET is the DDNAME you will use for the file
NUMREQ is the maximum number of concurrent but independent browses that will be active. The default is whatever was specified (or defaulted) in the TYPE=INITIAL macro. The minimum value is 1. The maximum value is 15.
BASE is used when this entry is for a path (access via alternate index), and it names the DATASET= for some other entry in the FCT that is for the base cluster of the path.
FILESTAT is used to tell KICKS whether it is allowed to use the file, and may have the value ENABLED or DISABLED. Recommend to leave in default ENABLED state.
The FCT source is in KICKS.V1R5M0.INSTLIB(KIKFCT1$). I suggest that instead of modifying it you create a new member – such as KIKFCTZZ, perhaps in your own dataset – copy KIKFCT1$ into it, edit it (especially change SUFFIX to ZZ and the name in the SYSLMOD override – 3rd card from the bottom), and submit. To run with your new FCT just start KICKS by typing
KICKS FCT(ZZ)Instead of just
KICKSWhen you look at the FCT source you will see it is just a series of KIKFCT macros. The first is a TYPE=INITIAL and just gives the suffix. The last is a TYPE=FINAL and just provides for final wrap up. In between are TYPE= DATASET macros that define your VSAM files. The order of the TYPE=DATASET macros is not significant except that you should use some convention to make it easy for you to find datasets you want. KICKS has no required entries in the FCT. Code the TYPE= DATASET macros for your transaction id’s like those in KIKFCT1$: use KIKPCT TYPE= DATASET, DATASET =XXXXXXXX
If the dataset is a path, BASE must name another KIKFCT TYPE=DATASET that is the base cluster for the path. So for example in KIKFCT1$ you see
KIKFCT TYPE=DATASET,DATASET=INVOICE
KIKFCT TYPE=DATASET,DATASET=INVPATH,BASE=INVOICE
which will allow KICKS to enqueue against the INVOICE base cluster when it needs to access INVPATH.
DESTINATION CONTROL TABLE (DCT)
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
SUFFIX is the suffix for the DCT itself. It should match the suffix
used to name the table in the load lib. The KIKDCT macro default is ‘00’ but the
supplied DCT assembly job specifies 1$. TYPE is either INITIAL, EXTRA, INTRA, INDIR, or FINAL.
Your DCT assembly job should have one leading TYPE= INITIAL, as many TYPE=EXTRA’s, INTRA's, and INDIR's as you have destinations (or aliases) to define, and one trailing TYPE=FINAL.
Your TYPE=INITIAL has one required argument, SUFFIX..
Your TYPE=FINAL has no arguments.
Your TYPE= EXTRA’s should specify DESTID, FILE, TYPEFIL and optionally ISTAT and/or OPEN.
Your TYPE= INTRA’s should specify DESTID and optionally ISTAT
Your TYPE= INDIR’s should specify DESTID and PHYDEST.
DESTID is the 4 character name you will use in your API calls referring to this destination.
PHYDEST is used only in TYPE=INDIR's and is the 4 character name of a TYPE=EXTRA entry this destination aliases.
FILE is the 8 character DDNAME you will use for the destination
TYPEFIL is either 'INPUT' or 'OUTPUT' and specifies that you will be using READQ or WRITEQ (respectively) API calls to this destination.
ISTAT is used to tell KICKS whether it is allowed to use the destination, and may have the value 'ENABLED' or 'DISABLED'. Recommend to leave in default ENABLED state
OPEN is either 'INITIAL' (meaning the destination is opened when KICKS starts) or 'DEFERRED' (meaning KICKS does not open the destination until it is first referenced).
The DCT source is in KICKS.V1R5M0.INSTLIB(KIKDCT1$). I suggest that instead of modifying it you create a new member – such as KIKDCTZZ, perhaps in your own dataset – copy KIKDCT1$ into it, edit it (especially change SUFFIX to ZZ and the name in the SYSLMOD override – 3rd card from the bottom), and submit. To run with your new DCT just start KICKS by typing
KICKS DCT(ZZ)Instead of just
KICKSWhen you look at the DCT source you will see it is just a series of KIKDCT macros. The first is a TYPE=INITIAL and just gives the suffix. The last is a TYPE=FINAL and just provides for final wrap up. In between are TYPE= EXTRA and TYPE=INDIR macros that define your destinations. The order of the TYPE= EXTRA and TYPE=INDIR macros is not significant except that you should use some convention to make it easy for you to find destinations you want. KICKS has no required entries in the DCT.
The Clist
The purpose of the KICKS clist (exec in CMS) is to let the user start KICK by simply typing KICKS (enter). To this end, in TSO it- Ensures KICKS startup is ‘allowed’
- FREE’s any files allocated by a previous (possibly failed) startup
- ALLOC’s necessary files
- Starts KICKS with the desired SIT (and possibly overrides)
- FREE’s allocated files following KICKS shutdown And of course you can customize it to do anything else you desire.
- Detects environment (for example, VM/370 or Z/VM) and adapts startup defaults as necessary
- Sets up FILEDEF's for non-VSAM files
- Uses the KICKSD exec to set up DLBL's for VSAM files
- Starts KICKS with the desired SIT (and possibly overrides)
- And of course you can customize it to do anything else you desire.
Checking to see if KICKS should be allowed to run
In TSO you may want to prevent users from starting KICKS – for example if you are running batch jobs that need the same files the KICKS users would be updating. The clist allows you to control this by doing a trial allocation of its loadlib. If that succeeds the loadlib is freed and the clist continues normally (ultimately reallocating the loadlib as part of the SKIKLOAD concatenation). If not a message tells the user KICKS is not available and the clist ends. This facility is intended for 'system installs' of KICKS. In a normal user install this file is userid qualified, hence not particularly useful.In use, the operator would run a job/started task that uncataloged the loadlib, This would prevent new KICKS starts. When it was OK for users to run KICKS again the operator would run another job/started task the recataloged the loadlib.
The KICKS installation does not provide a similar facility for CMS.
Detecting the environment and adapting startup defaults
In CMS the KTESTS EXEC is called to set exec globals defining the environment: VM/370 (or not), VSAM available (or not), MECAFF available (or not), and running in CMSBATCH (or not). If VSAM is available KFDEFLT is called to return the VSAM definition variables (CATUSER, CATLNK1, CATLNK2, CATPASS, CATFM, and CATVOL) from the current FCT.In TSO this environment detection/adaptation is part of the installation procedure so does not need to be done at KICKS startup.
Freeing previously allocated files
The TSO allocate command will fail if the file is already allocated. To simplify the clist’s error recovery it frees all the files it allocates – both before it begins the allocate process, and after a normal KICKS shutdown. Of course in the former case the FREE command might fail if the file wasn’t allocated, but the clist uses NOMSG NOFLUSH to hide these uninteresting errors.This is not an issue in CMS since it isn't an error to allocate a file you've already allocated.
This step also deletes the old auxiliary trace file (if it exists).
Allocating necessary files (or, in CMS, Sets up FILEDEF's for non-VSAM files)
- KICKS files
SKIKLOAD The KICKS system load library concatenation
- TSO: userid.KICKS.V1R5M0.SKIKLOAD
- userid.KICKSSYS.V1R5M0.SKIKLOAD
- CMS: KIKULOD, KIKSLOD txtlibs
-
TSO userid.KICKS.V1R5M0.KIKRPLuserid.KICKSSYS.V1R5M0.KIKRPL
-
CMS KIKURPL, KIKSRPL txtlibs
- TSO userid.KICKS.V1R5M0.OPIDS(userid) or, if that does not exist, DUMMY
- CMS always DUMMY
- TERMINAL
- TERMINAL or SYSOUT if QUIET specified (see below)
- SYSOUT(A)
- Unallocated, which caused the dump program to allocate it dynamically and spin it off for printing as soon as the dump is completed, or
- Allocate to SYSOUT(A) if you want the dumps printed all at once when you logoff, or
- (not recommended) allocate to SYSOUT(Z) if you don’t want them to print at all.
- SYSOUT(A)
- userid.KICKS.AUXTRC
-
USER filesOne for each ‘TYPE=DATASET’ VSAM cluster (or path) in the FCT and for each 'TYPE=EXTRA' destination in the DCT. As distributed these will be the files for the example programs. In TSO ou will modify the clist to add your files here. Don’t forget to ‘free’ them in the appropriate parts of the clist. VSAM files are usually allocated DISP(SHR) allowing multiple KICKS users to access the file. DISP(OLD) is ok is the file is not to be shared (userid qualified?)
In CMS, if VSAM is available the KICKSD EXEC is called (using the VSAM definition variables obtained from KFDEFLT) to setup the required DLBL's for the VSAM files. It is expected the user will modify KICKSD EXEC to include DLBL's for his own files as necessary to match changes to his FCT.
However, if you choose you can leave KICKSD alone and use your own exec instead. Just copy KICKSD EXEC to your own (for example YOURNAME EXEC), make changes as you like, and start KICKS using it with KICKS DLBLS YOURNAME.
Whether you use KICKSD or your own exec to setup DLBLs, be sure you use SYSCAT for the logical unit, and that you use &CATFM for the file mode. As discussed above (under FCT), in this version of KICKS all VSAM files must be on one mini-disk (ie, &CATFM) that also contains the VSAM master catalog.
Starts KICKS with the desired SIT (and possibly overrides)
Based on the environment the appropriate default suffixes are selected. For example in CMS if MECAFF is present TCP=2$ is defaulted instead of TCP=1$ as would normally be used for Z/VM. Or if VSAM is not present FCP=0$ is defaulted instead of FCP=1$ as normal. Then EXEC arguments are analyzed, defaults updated, and KICKS is started with resulting program and table suffixes..In TSO there is a bit less of this automatic selection of suffixes, but unlike the CMS exec the TSO clist supports SYSIN overrides to the SIT and command line arguments.
FREE’s allocated files following KICKS shutdown
The same file list freed during startup is freed again after a normal shutdown.More Customization
The SIT overrides in the clist/exec are the ones I thought most likely necessary. You can easily add more if you want. Just make sure the name of the override is the same as the SIT assembly argument.The TSO clist frees, reallocates, and finally frees a number of DD’s that may be important for other TSO applications you run. You should review its final disposition of SYSIN, SYSTERM, SYSPRINT, SYSOUT, and SYSUDUMP to ensure free’ing those DD’s does not interfere with your other applications.
The TSO clist is written using standard TSO features available in the base TK3. This version of TSO is missing many features in more modern TSO/E implementations, especially the &SYSDSN clist function. That’s why you see tests for allocation failure (etc) instead of SYSDSN tests to ensure the file exists before allocating it. In most cases this is just a stylistic concern, but in the case of the SYSIN allocation & member test it results in a 013-18 message on the system console when the member does not exist. A couple of possible solutions to eliminate the message are (1) just allocate SYSIN to dummy and don’t use it for SIT overrides; (2) add members to the OPID dataset for all KICKS users; (3) install ZP60014 (see http://www.prycroft6.com.au/vs2mods/download/zp60014.zip) to provide &SYSDSN support. Of course this is not an issue under Z/OS.
Nothing says you have to use my clist/exec to run KICKS. Make your own to do whatever you think it should do!
For example the CMS api tests use a customized exec - TKICKS EXEC - to run KICKS in a CRLP environment. It forces CRLP input (and output) even if run in an interactive environment and used TKICKSD to define it's files instead of KICKSD. It also allows you to specify an additional user TXTLIB for programs and tables. Almost all the sample execs (in TESTCOB VMARC and TESTGCC VMARC) use TKICKS this way.
For another example you might want to use KICKS as a ‘hidden’ wrapper for some application of your own. If you suppress the startup messages, make your application the PLTPI startup application, and have your application issue EXEC KICKS SIGNOFF before its final EXEC KICKS RETURN you can easily achieve this. You would use a renamed custom version of the KICKS clist/exec to run your app.
KICKS |
A transaction processing system for CMS & TSO |
Operation
File Sharing
KICKS implements VSAM file sharing by the simple expedient of opening files only when access is demanded and closing files at the end of each transaction (or when a blocking terminal read is attempted). Enqueues against the base cluster are issued to ensure opens will succeed without excessive console messages.This creates a possibility for deadly embrace in that since enqueues are obtained as files are accessed, a program that accesses files in different initial order (based on some criteria) could lock up against another copy of the same program operated by another user – even if that program did not exhibit such behavior under real CICS. If such a scenario is detected KICKS will abend one of the tasks. Programs that exhibit such behavior can be fixed by making them initially access (in fixed order) each of the files they might use.
Since with this scheme only one task will ever be using any file those files should be defined with VSAM shareoptions (1 3) – meaning only one task can have the file open at a time for read or write. Of course in order for multiple users to be able to open the files as needed the files must be allocated DISP=SHR.
This provides for file sharing between KICKS users. It does not allow for file sharing between KICKS users and CICS users, or between KICKS users and normal batch jobs (ie, batch jobs other than KICKS in batch) . CICS and normal batch jobs usually open files at startup and keep them open until the program ends so usually can’t participate in the kind of file sharing KICKS uses.
Shutdown KICKS, prevent any new KICKS startups
In an environment where KICKS is installed at the system level and available to all users it may be desirable to control when KICKS is available and/or shutdown all running KICKS users.When KICKS is started the clist performs a test allocation of the system level SKIKLOAD dataset. If the attempted allocation fails, the clist issues a message to the TSO user and quits. This behavior allows the operator to control new KICKS logons by cataloging or uncataloging that SKIKLOAD dataset.
So
- To disable further KICKS logons run a job (or started task) to uncatalog that SKIKLOAD dataset
- To terminate currently running KICKS tasks ‘P TSO’ (then restart it with S TSO to enable non-KICKS TSO use)
- To re-enable KICKS logons run a job (or started task) to recatalog that SKIKLOAD dataset.
Using KICKS in batch
It's possible to run KICKS as a batch job. Essentially what you do is replace the KICKS clist with similar JCL and allocate two new datasets, CRLPIN and CRPLOUT. These are the input and output side (respectively) of the simulated terminal KICKS uses for the batch run.The KICKS userid in batch will be either the JOBNAME on the JCL jobcard, or the USERID you specified on the JCL jobcard or that your security system supplied (if you have a security system installed).
The simulated terminal is by default a 24x80 3270 and has a default id of "CRLP". If there is a problem using that as a terminal id - for example some transactions use the terminal id as part of some resource name (a common practice in naming temporary storage queues) - you can use the CRLP transaction to change it. The CRLP transaction can also change the batch terminal's default behavior from 3270 to a legacy pure card-in / printer-out behavior if necessary (specify PURE or NO3270 to change it, 3270 to change it back).
When the terminal is in legacy mode each record of CRLPIN is presented to the program one at a time without any edits (including line numbers if present) and each terminal write results in printing exactly one line into CRLPOUT. The maximum input or output length is 80 characters.
When NOT in legacy mode:
When the transaction sends 3270 data to the terminal KICKS translates that datastream into a printer representation (pretty much like a screen shot - black characters on a white background, attributes ignored) and writes it to CRLPOUT.
KICKS reads card images from CRLPIN and makes the data available to the transaction. Data on each card should end with a <XXX> , where the XXX can be an upper or lower case command or aid. Commands are REMARK (or just REM), TAB, BTAB, HOME, END, ERASE and <RR,CC> cursor placement. Aids are ENTER, CLEAR, PA1-PA3, and PF1-PF24. Anything following the <XXX> on the card is a remark.
<REM> or <REMARK> is just a way to end terminal input from the current card (allowing remarks to follow) without doing anything.
<TAB> advances the cursor (where data goes) to the next input field.
<BTAB> moves the cursor to the start of the current field, or, if the cursor is already at the start of a field, to the start of the previous field.
<HOME> moves the cursor to the start of the first field on the screen. First being top left most.
<END> moves the cursor to the start of the last field on the screen, Last being the bottom right most. <END> is logically equivalent to <HOME><BTAB>.
<ERASE> fills the remainder of the current field with binary zeros but does not move the cursor.
<RR,CC> places the cursor at row RR (1-24), column CC (1-80).
Since anything following a <XXX> is a remark only the first <XXX> on the card is a command. (Others being remarks!)
Actually, anything starting with a < is expected to be a <XXX> and terminates input on the card. If you need to enter data containing a < you must 'escape' it using a \, so to enter "here is an <XXX>" you would code "here is an \<XXX>". If you need to enter a \ you would use \\.
Data on a card preceding the <XXX> is put, character by character, into fields starting at the current cursor location (which is initially wherever the last terminal write left it). If the cursor hits the end of a field it will either advance to the next field, or to the next input field depending on askip as usual. If the field it ends up in does not allow input then any data entered is thrown away without moving the cursor until something (<TAB> ?) does move the cursor. This simulates a 'locked' state.
When a <XXX> is an aid - <ENTER> <CLEAR> <PA1> <PF1> etc - the resulting data is made available to the transaction.
End of file on CRLPIN simulates a <CLEAR> and sets the KICKS shutdown bit, which will take effect when the current transaction (if any) ends.
Here is sample JCL from userid.KICKSSYS.V1R5M0.TESTCOB(BATCH1) to start KICKS and run a couple of transactions.
Here is the output (from DD CRLPOUT) the above JCL produces. I've highlighted the echoed input in yellow...
//BATCH1 JOB CLASS=A,MSGCLASS=A,MSGLEVEL=(1,1),REGION=2000K, // USER=HERC01 //* //ALLOW EXEC PGM=IEFBR14 //ALLOW DD DSN=HERC01.KICKSSYS.V1R5M0.ALLOW.STARTUP,DISP=SHR //* fail job if KICKS startup not allowed... //GO EXEC PGM=KIKSIP1$,TIME=1,PARM='SIT=1$' //* kiksip1$ comes from steplib... //STEPLIB DD DSN=HERC01.KICKSSYS.V1R5M0.SKIKLOAD,DISP=SHR //* tables come from skikload... //SKIKLOAD DD DSN=HERC01.KICKSSYS.V1R5M0.SKIKLOAD,DISP=SHR //* programs & maps come from kikrpl... //KIKRPL DD DSN=HERC01.KICKS.V1R5M0.KIKRPL,DISP=SHR, // DCB=BLKSIZE=32000 // DD DSN=HERC01.KICKSSYS.V1R5M0.KIKRPL,DISP=SHR //* //SYSPRINT DD SYSOUT=*,DCB=(RECFM=F,BLKSIZE=80) //SYSTERM DD SYSOUT=*,DCB=(RECFM=F,BLKSIZE=80) //SYSOUT DD SYSOUT=*,DCB=BLKSIZE=132 //CRLPOUT DD SYSOUT=*,DCB=(RECFM=F,BLKSIZE=132) //TRANDUMP DD SYSOUT=*,DCB=(RECFM=F,BLKSIZE=132) //SYSUDUMP DD SYSOUT=* //* //AUXTRC DD SYSOUT=*,DCB=(RECFM=F,BLKSIZE=120) //* //SYSIN DD DUMMY,DCB=(RECFM=F,BLKSIZE=80) //* //TACDATA DD DSN=HERC01.KICKS.TACDATA,DISP=SHR //* //CRLPIN DD *,DCB=BLKSIZE=80 <clear> get blank screen to enter next transaction crlp<REMARK> the CRLP transaction can be used to set <REMARK> or change the sequential terminal name or options <REMARK> TERMID=xxxx - change name from default CRLP to ? <REMARK> TRIM/NOTRIM - trailing spaces trimmed off (or not) <REMARK> BORDER/NOBORDER - box around screen (or not) <REMARK> ** note that TRIM & BORDER are mutually exclusive <REMARK> ECHO/NOECHO - crlpin echoed to crlpout (or not) <REMARK> TIOA/NOTIOA - generated TIOA displayed (or not) <REMARK> SHOWI/NOSHOWI - input screen displayed (or not) border<enter> show current options <clear> get blank screen to enter next transaction BTC0<ENTER> show the main menu <PF1> show the auto refund menu <PF1> show the add request screen 10<REM> YEAR, NO <TAB> 'CAUSE AUTOSKIPPED ALREADY memyself<erase> NAME, NO SPACES, AUTOSKIP (except last!) <TAB> <tab> can't go on same line <erase> above... 14725 INNER WAY<ERASE> <TAB> SITKA<ERASE> <TAB> AK<REM> ST, NO <ERASE> OR <TAB> 'CAUSE FIELD FILLED 99835<REM> ZIP, NO <ERASE> OR <TAB> 'CAUSE FIELD FILLED 516384991<REM> SSN, NO <ERASE> OR <TAB> 'CAUSE FIELD FILLED 43210<ERASE> GROSS <TAB> 1NOT<ERASE> CONTRIB - not numeric, force error <ENTER> try to do the add, get error msg <CLEAR> back up to auto refund menu <CLEAR> back up to main menu <CLEAR> back up to 'data entry concluded' <clear> get blank screen to enter next transaction KSSF<ENTER> LOGOFF - would happen anyway at following /* /* //
One use for KICKS in batch is CLG (Compile, Link & Go) debugging of your KICKS transactions - see the various jobs in userid.KICKSSYS.V1R5M0.TESTCOB (and TESTGCC). These jobs are intended to illustrate how to use some of the KICKS API's, but are also useful as models for your own 'CLG' jcl. A few things to notice about those jobs: they use SIT=B$, which pulls in PCT=B$, PPT=B$, FCT=B$, and DCT=B$. SIT=B$ also specifies a null PLTPI, which is why KSGM doesn't show up as the initial screen when you run the TESTJCL jobs. You should examine the tables so you know what is in them, but the most important point is that the PCT has a entry named TCOB that calls a program TESTCOB; and the PPT has an entry TESTCOB for a command level program. So all the CLG test jobs link their programs as TESTCOB, and all the test jobs run the transaction TCOB in batch KICKS.
Supplied Transactions
KICKS is supplied with a number of transactions and associated programs to assist with its operation These includeKSGM (aka CSGM)
The KSGM transaction is typically used to present the first screen the user sees when KICKS is started. This occurs because KSGM is typically the argument of the SIT PLTPI option, so this transaction is automatically run when KICKS starts. Since it's the first message, this has been called the "good morning" (ie, GM) message.The most usual action following display of the KSGM screen is to simply press the CLEAR (or PF3) key and enter the first transaction you need to run. But if you decide to stop and play you'll find you can get rapidly changing set of colors by rapidly pressing the ENTER key (or holding the ENTER key down if your terminal emulator implements repeat in that case). PF1 will display a limited help screen, and PF2 from the help screen will display (and allow you to print) the KICKS license.
The PCT entry for KSGM has an optional "TWASIZE" agrument. KSGM does not actually use a TWA (transaction work area), but it uses the defined size as the number of seconds to delay between changing the colors on the block letters displayed. If a static display (no color updates) is desired simply specify TWASIZE=0 (or omit TWASIZE altoghther). TWASIZE=1 is a special case that always produces exactly the same color combination, it's used for documentation purposes. TWASIZE=2 (meaning 2 seconds between color updates) thru 60 (once a minute) are available.
KSGM requires a PCT entry pointing to the COBOL program KSGMPGM, which in turn requires a PPT entry for KSGMPGM. It also requires a PPT entry for KSGMAPL which defines BMS maps for 24x80, 32x80, 43x80, 32x87, 27x132, and 62x160 screens. Limited help for this program is presented by the GCC program KSGMHLP (which also requires a PPT entry), and the help program may display or print the KICKS license agreement using the COBOL program KSGMLIC (which also requires a PPT entry. KSGMLIC is an example of a KICKS program that uses non-CICS api's, in this case batch COBOL i/o used to read the license from a pds member.
Other PCT entries may also point to KSGMPGM; CSGM (the usual CICS transaction id for the good morning message) is supplied with TWASIZE=0 for a random color but static display, and KSG1 is supplied to access the TWASIZE=1 special "documentation" version of the display.
Source for KSGMPGM (and for KSGMHLP and for KSGMLIC) is in HERC01.KICKSSYS.V1R5M0.COB as one source member KSGMPGM. Source for KSGMAP and KSGMAPL maps are in HERC01.KICKSSYS.V1R5M0.MAPSRC as one source member KSGMMAP.
KSSF (aka CSSF, aka LOGOFF)
The KSSF transaction is used for user initiated KICKS shutdown. The similar CICS transaction, CSSF, refers to "sign off", and indeed signoff is the api that the KSSF transaction will initiate. But signoff from KICKS is the same as shutting down KICKS and returning to TSO...The KSSF transaction runs KSSFPGM, which, besides putting out a cute little KICKS is shutting down message, mainly does an
EXEC KICKS SIGNOFF END-EXEC
to tell KICKS it's time to quit (see the SIGNOFF api in the Programming section of this User's Guide).
If you have some action that needs to happen at KICKS shutdown you might be tempted to add them to KSSFPGM. Do NOT. This isn't the only place that the SIGNOFF api might be triggered! For example the batch (CRLP) terminal will signal SIGNOFF when it encounters EOF on the input file (CRLPIN). Instead add your actions to K999PGM (or whatever you are using for a PLTSD program); these will always be executed at shutdown, regardless of the path taken to get there...
KSSF requires a PCT entry pointing to the COBOL program KSSFPGM, which in turn requires a PPT entry for KSSFPGM.
Other PCT entries may also point to KSSFPGM; CSSF (the usual CICS transaction id for 'signoff') is available, as is LOGOFF (LOGO actually, KICKS and CICS only see the first 4 characters of a transaction).
Source for KSSFPGM is in HERC01.KICKSSYS.V1R5M0.COB.
K999
The K999 transaction is typically the last thing run when KICKS is shutdown. This occurs because K999 is typically the argument of the SIT PLTSD option, so this transaction is automatically run just before KICKS quits.The K999 transaction runs K999PGM, which, as delivered, is just a shell you can modify to do anything you think needs to happen at that point.
K999 requires a PCT entry pointing to the COBOL program K999PGM, which in turn requires a PPT entry for K999PGM.
Source for K999PGM is in HERC01.KICKSSYS.V1R5M0.COB.
KSMT (aka KEMT, aka CSMT, aka CEMT)
The KSMT transaction is used to display and modify KICKS internal control variables.KICKS Master Terminal Program (maxcc = 0) Press a PF key to obtain indicated action: PF1 = SHOW TRACE STATUS PF2 = TOGGLE INTERNAL TRACE ON/OFF PF3 = TOGGLE AUX TRACE ON/OFF PF4 = TOGGLE INTENSE TRACE ON/OFF PF5 = SHOW ICVR VALUE PF6 = DECREASE ICVR PF7 = INCREASE ICVR PF8 = PF9 = PF10 = PF11 = PF12 = QUIT |
The KSMT transaction runs the KSMTPGM program
KSMT requires a PCT entry pointing to the COBOL program KSMTPGM, which in turn requires a PPT entry for KSMTPGM. It also requires a set of PPT entries for MACC routines it uses to obtain and change KICKS system information; these entries are KTRCSTA (get trace status), KTRCON (turn trace on), KTRCOFF (turn trace off), KTRCAON (turn aux trace on), KTRCAOF (turn aux trace off), KTRCINON (turn intense trace on), KTRCINOF (turn intense trace off), KICVRGET (obtain ICVR value), KICVRPUT (change ICVR value), KLASTCCG (get lastcc value), KLASTCCP (change lastcc value), KMAXCCG (get maxcc value), and KMAXCCP (change maxcc value).
Other PCT entries such as CSMT and CEMT may also point to KSMTPGM.
Source for KSMTPGM is in HERC01.KICKSSYS.V1R5M0.COB. Source for the subroutines is part of the KICKS source distribution, in HERC01.KICKSTS.JCL members KSMTSUBS and LASTCC.
KEDF (aka CEDF)
The KEDF transaction is used to turn the interactive debug facility on or off; to specify on which EXEC KICKS api calls the debug facility is to display it's before/after screens; and to enable source code trace.When entered as just "KEDF" it displays a table of api calls, each of which is shown as hightlighed (enabled), or not highlighed (not enabled).
KEDF (1.5.0) is OFF to toggle it ON press PF4 12:31:49 10/21/14 Highlighed items will be displayed, to change put cursor on item, press PF5 DELETEQ TD DELETE ADDRESS ABEND RECEIVE READQ TD ENDBR ASKTIME DUMP RECEIVE MAP WRITEQ TD READ ASSIGN ENTER SEND TEXT READNEXT ENQ LINK SEND MAP SPOOLOPEN READPREV DELAY LOAD SEND CONTROL SPOOLWRITE RESETBR DEQ RELEASE SPOOLCLOSE REWRITE FORMATTIME RETURN HANDLE CONDITION STARTBR SIGNOFF XCTL IGNORE CONDITION DELETEQ TS UNLOCK SUSPEND HANDLE AID READQ TS WRITE SYNCPOINT FREEMAIN HANDLE ABEND WRITEQ TS WRITE OPERATOR GETMAIN SOURCE TRACE To highlight all press PF6, to Un-high all press PF7 Enter (or PF3) - exit+save Clear - exit+nosave |
Besides the interactive "KEDF" invocation as above you can also use "KEDF ON" to simply turn on the debugger with current api selection but no source trace, or "KEDF ON/S" to turn in on with current api selection and source trace, or "KEDF OFF" to turn off further debugger interaction.
The KEDF transaction runs KEDFPGM.
KEDF requires a PCT entry pointing to the COBOL program KEDFPGM, which in turn requires a PPT entry for KEDFPGM. It also requires a PPT entry for KEDMAP which defines BMS maps for a 24x80 screen. It also requires a PPT entry for KEDFILTR which is the table of default api trace enable switches that KEDFPGM displays and modifies. It also requires a set of PPT entries for MACC routines it uses to obtain and change KEDF system information; these entries are .
KIKPPT TYPE=ENTRY,PROGRAM=KEDFON,PGMLANG=MACC KEDF ON
KIKPPT TYPE=ENTRY,PROGRAM=KEDFOFF,PGMLANG=MACC KEDF OFF
KIKPPT TYPE=ENTRY,PROGRAM=KEDFSTA,PGMLANG=MACC KEDF STATUS
Other PCT entries may also point to KEDFPGM, especially CEDF, the transid used in CICS systems.
Source for KEDFPGM is in HERC01.KICKSSYS.V1R5M0.COB.Source for KEDMAP is in HERC01.KICKSSYS.V1R5M0.MAPSRC. Source for KEDFILTR is in HERC01.KICKSSYS.V1R5M0.INSTLIB. Source for the subroutines is part of the KICKS source distribution, in HERC01.KICKSTS.JCL member KEDFSUBS.
KEDFILTR
The KEDFILTR table is assembled from source in HERC01.KICKSSYS.V1R5M0.INSTLIB. It is referenced by the online debugger to determine if a given api call should cause a break or not. It is loaded and modified (in memory only) by KEDFPGM.Each line in the assembler source shows the api's eibfn and a flag value indicating, if zero, that that api call should cause a break, or by a one that the api call should not cause a break. Comments on the line indicate the name of the api call. Note that 9999 is not an api eibfn, rather it is a flag for source trace. Zero marks the end of the list.
Do not rearrange the list; KEDFPGM depends on the existing order...
KSDB
The KSDB transaction reads input generated by the language preprocessors and updates the online source code database used by the debugger to display lines of the source code for a running application. KSDB is intended for batch use only. It is run in the final step of the KIKCB2CS, K2KCOBCS, and KIKGCCCS procs.The KSDB transaction runs the KSDBLOAD program.
KSDB requires a PCT entry pointing to the COBOL program KSDBLOAD, which in turn requires a PPT entry for KSDBLOAD. KSDBLOAD is another example of a KICKS program that uses non-CICS api's, in this case batch COBOL i/o used to read the preprocessor input and annotation.
Source for KSDBLOAD is in HERC01.KICKSSYS.V1R5M0.COB.
CRLP
The CRLP transaction is used to control the sequential terminal used when KICKS is run in batch.An example of use of the CRLP transaction is shown in Using KICKS in Batch.
CRLP requires a PCT entry pointing to the macro level GCC program CRLPPGM, which in turn requires a PPT entry for CRLPPGM.
Source for this program is part of the KICKS source distribution, in HERC01.KICKSTS.ROOT.C member CRLPPGM.
KEBR (aka CEBR)
KEBR is used to browse temporary storage queues and delete them. It is modeled on the CEBR transaction used for the same purpose in CICS. You can also use the KEBR transaction to transfer the contents of a file or transient data queue to temporary storage in order to look at them, and to reestablish the transient data queue when you have finished. The KEBR commands that perform these transfers allow you to add records to a transient data queue and remove all records from a transient data queue. KEBR commands do not edit or delete files.How to use the KEBR transaction
You start the KEBR transaction by entering the transaction identifier KEBR, followed by the name of the queue you want to browse. For example, to display the temporary storage queue named TSTST, you type:
KEBR TSTSTand press ENTER. KICKS responds with a display of the queue, for example:
KEBR TS Queue TSTST Line/Item 1 of 7 Command ===> Column 1 of 389 Transaction Q Ok ....|....1....|....2....|....3....|....4....|....5....|....6....|....7.. *** TOP OF QUEUE ****** 00001 00358491-07-23400015PROM1 000000100000000050000010000000050000000000 00002 00358591-07-23400003PROM1 0000000000000000000000000 00003 00358691-07-23400007PROM1 0000000000000000000000000 00004 00358791-07-23400005PROM1 0000000000000000000000000 00005 00358891-07-23400004PROM1 0000000000000000000000000 00006 00358991-07-23400016PROM1 0000000000000000000000000 00007 00359091-07-23400003PROM1 0000000000000000000000000 *** BOTTOM OF QUEUE ****** ....|....1....|....2....|....3....|....4....|....5....|....6....|....7.. PF1 : Help PF2 : HEX/Char PF3 : Quit PF4 : PF5 : RFind PF6 : PF7 : Back PF8 : Forward PF9 : PF10: Left PF11: Right PF12: Quit |
KEBR TS Queue KEBRU0C0 Line/Item 0 of 0 Command ===> Column 0 of 0 Default Q Can not read that QUEUE PF1 : Help PF2 : HEX/Char PF3 : Quit PF4 : PF5 : RFind PF6 : PF7 : Back PF8 : Forward PF9 : PF10: Left PF11: Right PF12: Quit |
The header The header shows:
- The transaction being run, that is, KEBR.
- The identifier of the temporary storage queue. You can overtype this field in the header if you want to switch the screen to another queue.
- The number of the top record in the body.
- The number of records in the queue (seven in TSTST and none in KEBRU0C0).
- The position in each record at which the screen starts (position 1 for queue TSTST, zero for queue KEBRU0C0) and the length of the longest record (389 for queue TSTST and zero for queue KEBRU0C0).
The command area is where you enter commands that control what is to be displayed and what function is to be performed.
The body
The body is where the command response, queue records, and other indicators are shown.
When a command (other than positioning) is complete the top two lines of the body display the text of the command and the response.
Indicators include "*** TOP OF QUEUE ******" (white), "*** TOP OF QUEUE ******" (white), and rulers (magenta). Rulers can be turned on or off using either the RULER command.
Queue records are prefaced by their 5 digit item number and begin one space thereafter at the item position indicated in the header. If a record is too long for the line, it is truncated. You can change the portion of the record that is displayed, however, so that you can see an entire record on successive screens. If the queue contains more records than will fit on the screen, you can page forward and backward through them, or specify at what record to start the display, so that you can see all the records you want.
The menu of functions
The function keys that you can use are displayed at the bottom of every KEBR screen. The keys have the same meaning on all screens.
PF1 (command HELP) - Displays a help screen that lists all the commands you can use when the KEBR transaction is running. You can return to the main screen by pressing ENTER.
PF2 (command HEX) - Switches the screen from character to hexadecimal format, and back again. In hexadecimal format each item requires 3 lines: The first line is exactly as the character format display. The following two lines are 'vertical' hex of the characters in the first line.
PF3 (command QUIT) - Terminates the KEBR transaction. Same as PF12. Shift-PF3 (PF15) and Shift-PF12 (PF24) also quit.
PF5 (command RFIND) - Repeats the previous FIND command. Shift-PF5 (PF17) changes direction then does the RFIND.
PF7 - Moves the display backward by the number of records that fit on the screen. Shift-PF7 (PF19) moves he display backward to the top.
PF8 - Advances the display by the number of records that fit on the screen, Shift-PF8 (PF20) moves he display forward to the bottom.
PF10 (command LEFT) - Changes the screen to show the columns immediately after (to the right of) the columns currently on display. You can also use the COLUMN command to change the column at which the display begins.
PF11 (command RIGHT) - Changes the screen to show the columns immediately before (to the left of) the columns currently on display. You can also use the COLUMN command to change the column at which the display begins.
PF12 (command QUIT) - Terminates the KEBR transaction. Same as PF3. Shift-PF3 (PF15) and Shift-PF12 (PF24) also quit.
KEBR 'cursor' scrolling
KEBR scrolls by full screens, but like ISPF it is possible to make any item the top or bottom line on the screen by placing the cursor on that item before pressing PF7 or PF8 (respectively). In a similar manner it is possible to modify the LEFT and RIGHT scrolls by placing the cursor on the desired first or last column of an item before pressing PF10 or PF11 (respectively).
KEBR commands
BOTTOM (Abbreviation: BOT) Shows the last records in the temporary storage queue (as many as fill up the body of the screen, with the last record on the last line).
COLUMN nnnn (Abbreviation: COL nnnn) Displays the records starting at character position (column) nnnn of each record. The default starting position, assumed when you initiate the KEBR transaction, is the first character in the record.
FIND [FWD/BWD] string (Abbreviation: F string) Finds the next (or previous) occurrence of the specified string. FWD is optional, being assumed if unspecified. The search starts one character after (or before) the top left item/column displayed. If the string is found, the body is scrolled to that line and column, thus making the sought string the new top left. If the string is not found the body is not scrolled, and a "NOT FOUND" message is shown. The value that you specify can be in character format (for example, find ABCD) or in hexadecimal format (for example, find x'F0F1F2'). In a character search delimiters of your choice may optionally be used; ie, if the first and last characters of the string are the same they are assumed to be delimiters. A hexadecimal search is conducted using an even number of hex digits, so if you specify an odd number of digits a leading zero is assumed.
HELP Displays a brief summary of the KEBR commands
LEFT Changes the screen to show the columns immediately after (to the right of) the columns currently on display. You can also use the COLUMN command to change the column at which the display begins.
LINE nnnn Starts the body of the screen at the queue record nnnn, and sets the current line to nnnn.
PURGE Deletes the queue being browsed.
PUT xxxx Copies the temporary storage queue that is being browsed to the named transient data queue. xxxx must be either the name of an intrapartition transient data queue, or the name of an extrapartition transient data queue that has been opened for output. The special queue name SYSOUT is recognized making PUT SYSOUT an alias for PRINT.
PRINT [CLASS x LPP nn FIRST nnnn ITEMS nnnn] Prints a report of the current queue, either as lines of printable characters, or as vertical hex depending on the current screen display. Rulers or not, also as per the current display. Output class, lines per page, starting item number and number of items can be specified with optional arguments in any order. The defaults are CLASS A LPP 60 FIRST 1 ITEMS 50.
QUEUE xxxxxxxx (Abbreviation: Q xxxxxxxx) Changes the name of the queue you are browsing. The value that you specify can be in character format (for example, QUEUE ABCD) or in hexadecimal format (for example, QUEUE X'C1C2C3C4'). The KEBR transaction responds by displaying the data that is in the named queue. You can also change the queue name by overtyping the current value in the header.
=X
CANCEL
END
QUIT the command (and several aliases) used to quit the KEBR transaction. The screen will clear and the message "Browse ended normally. Ready for next transaction:" is shown.
REFRESH (same as just pressing ENTER) The queue is re-read and displayed at the current item and offset (if possible).
RFIND {FWD/BWD] repeats the previous find, changing direction as necessary if FWD or BWD is specified. If neither is specified the repeated find is in the direction of the last FIND or RFIND.
RIGHT Changes the screen to show the columns immediately after (to the left of) the columns currently on display. You can also use the COLUMN command to change the column at which the display begins.
RULER Toggles on/off the display of rulers and the top and bottom of the body to make it easier to determine data location.
TERM [xxxx] Changes the name of the queue you are browsing, but is tailored to applications that use the convention of naming temporary storage queues that are associated with a terminal by a constant in the first four characters and the terminal name in the last four. The new queue name is formed from the first four characters of the current queue name, followed by xxxx. If xxxx is not specified the current terminal id is used.
TOP Causes the KEBR transaction to start the display at the first record in the queue.
VGET xxxxxxxx [FIRST nnnn RECS nnnn] Transfers records of the named file to the end of the temporary storage queue currently on display. This enables you to browse the contents of the file. xxxxxxxx must be the name of a vsam file (ksds, esds, rrds, or path) defined in the FCT. The optional arguments FIRST and RECS specify the first record and the number of records to read. Either or both may be specified in any order following the file name. The defaults are FIRST 1 RECS 100.
Using the KEBR transaction with transient data
The GET command reads each record in the transient data queue that you specify and writes it at the end of the temporary storage queue you are browsing, until the transient data queue is empty. You can then view the records that were in the transient data queue. When you have finished your inspection, you can copy the temporary storage queue back to the transient data queue (using the PUT command). This usually leaves the transient data queue as you found it, but not always. Here are some points you need to be aware of when using the GET and PUT commands:
- If you want to restore the transient data queue unchanged after you have browsed it, make sure that the temporary storage queue on display at the time of the GET command is empty. Otherwise, the existing temporary storage records will be copied to the transient data queue when the subsequent PUT command is issued.
- After you get a transient data queue and before you put it back, other tasks may write to that transient data queue. When you issue your PUT command, the records in the temporary storage queue will be copied after the new records, so that the records in the queue are no longer in the order in which they were originally created. Some applications depend on sequential processing of the records in a queue.
More KEBR details
KEBR requires a PCT entry pointing to the COBOL program KEBRPGM, which in turn requires a PPT entry for KEBRPGM. PPT entries for KEBRM (the map) and KEBRHELP (the loaded help file) are also required.
Other PCT entries such as CEBR may also point to KEBRPGM.
Source for KEBRPGM and KEBRHELP is in HERC01.KICKSSYS.V1R5M0.COB. Source for KEBRM is in HERC01.KICKSSYS.V1R5M0.MAPSRC as member KEBRMAP.
KLOGIT
The KLOGIT program allows you to easily put a message onto the KICKS log (destination 'LOG ') with your message automatically prefaced by the date, time, user id, terminal id, and transaction id.See for example any of the TESTFILE suite programs that use this to report unexpected returns.
KLOGIT requires a PPT entry for KLOGIT. Source for KLOGIT is in HERC01.KICKSSYS.V1R5M0.GCC.
LASTCC
The LASTCC programs allow you to set and retrieve the last and highest return codes in a current KICKS run. KICKS maintains the MAXCC as the highest set value of LASTCC or MAXCC. When KICKS ends it reports the then current value of MAXCC as the return code.KLASTCCG (get) returns the lastcc as a S9(8) comp item.
KLASTCCP (put) sets the lastcc from a S9(8) comp item.
KMAXCCG (get) returns the maxcc as a S9(8) comp item.
KMAXCCP (put) sets the maxcc from a S9(8) comp item.
Most KICKS applications do not use these routines, and neither normal nor abend transaction ending sets LASTCC/MAXCC, so KICKS normally shuts down with a return code of zero. If you want to change that you can use these programs to set LAST or MAX CC. See for example the KSDBLOAD program...
The required PPT entries are part of the KSMT group. Source for these programs is part of the KICKS source distribution, in HERC01.KICKSTS.JCL member LASTCC.
SYNCXIT
The SYNCXIT program is a sample syncpoint exit, coded as a command level COBOL program. The sample simply LINK's to KLOGIT to report each type of entry (transaction start, transaction end, transaction abend, syncpoint commit, syncpoint rollback) as it is made.SYNCXIT requires a PPT entry for SYNCXIT . Source for SYNCXIT is in HERC01.KICKSSYS.V1R5M0.COB.
DSNHDECP
The DSNHDECP program is not included with KICKS, but a PPT for it (as a assembler table) is. This PPT entry causes KICKS to try to load DSNHDECP into memory on startup. KICKS never calls or uses this module, but if any of your applications use DB2 then the in memory copy of DSNHDECP will specify the DB2 subsystem to be used.Copy member DSNHDECP from an 'appropriate' (meaning the one for the DB2 subsystem you intend to use) SDSNEXIT library to your KIKRPL library. Your application will use a CAF 'implicit' connection to DB2, and CAF will obtain the id of the DB2 subsystem to connect to by looking in the DSNHDECP member.
| KICKS |
A
transaction processing system for
CMS &
TSO
|
Programming
A KICKS application consists of a a group of related objects. The first set of objects in the group are the MAPS that define terminal input and output characteristics. The second is set of objects are PROGRAMS that may use the MAPS to interact with the terminal, implement some kind of business logic, and optionally commit the results of the logic to external FILES, which are a third set of objects.The relationship between KICKS application objects is created by the KICKS system tables (see KICKS configuration section) and by the programs that use the other objects.
Generating BMS maps
KICKS supports 3270 BMS maps much like CICS BMS maps. KICKS uses macros named KIKMSD, KIKMDI, and KIKMDF instead of DFHMSD, DFHMDI, and DFHMDF, but with similar arguments. To make conversion easier it also support ‘dummy’ versions of DFHMSD, DFHMDI, and DFHMDF that do nothing but invoke KIKMSD, KIKMDI, and KIKMDF respectively. This allows for generation of maps directly from source originally intended for CICS.Detailed instructions for coding BMS maps may be found by simply Googling "BMS map". I recommend the IBM sites. Another excellent set of resources are the Murach books "CICS for the COBOL Programmer" and "CICS Programmer's Desk Reference". And don't overlook our own KooKbooK recipes!
The map you code needs to be translated into three separate components. The first is a COBOL copybook you include with each COBOL program that will use the map. The second is a GCCMVS include file you include with each GCC program that will use the map. The third is a binary representation of the map that KICKS will use to format the screen as you describe and to process input data from the screen when the user presses ‘enter’.
On an MVS system the KIKMAPS proc is used to directly generate the COBOL and GCC copybooks and binary representation from the map source. The proc takes arguments as indicated in the proc header below
The proc header is customized during installation so that it is usually only necessary to specify the MAPNAME of the map to be gnerated.//KIKMAPS PROC SOUT='*',
// DSCTLIB='COBCOPY',
// DSCTLIC='GCCCOPY',
// MAPLIB='KIKRPL',
// KIKSSYS='HERC01.KICKSSYS',
// KIKSUSR='HERC01.KICKS',
// VER='V1R5M0',
// ASM='IFOX00', (ASMA90 FOR Z/OS)
// MAPNAME='DUMMY'
Most of the proc arguments should be self explanatory. The step names are COPY, BMAP, ASM, LINKMAP COBMAP, and GCCMAP. BMAP, COBMAP, and GCCMAP are the KICKS map translator executions and return condition 2-comment, 4-warning; 8-error; 12-fatal error.
Numerous examples of use of proc can be seen in the members of HERC01.KICKS.V1R5M0.MAPSRC, which compiles the sample program maps.
On a VM/CMS system the KIKMG exec is used to directly generate the COBOL and GCC copybooks and binary representation from the map source. It takes arguments as below
mapname filetype filemode txtlib coblib gcclib asmnam
default - MAPSRC A KIKURPL KIKCOUSR KIKGCUSR ASSEMB
There is no particular install customization of this exec.
Additional detail about the arguments can be obtained by typing KIKMG without any arguments. The steps executed are the same as in MVS/TSO: COPY, BMAP, ASM, LINKMAP COBMAP, and GCCMAP. BMAP, COBMAP, and GCCMAP are the KICKS map translator executions and return condition 2-comment, 4-warning; 8-error; 12-fatal error.
Numerous examples of use of this execs can be seen in the KIKSAMPM EXEC which compiles the sample program maps.
Whether MVS or VM/CMS, the map generator step(s) are controlled thru parm switches, ie
|
-list list stdin to stderr * -nolist do not list stdin to stderr -g=dsect override source msd type with 'dsect' -g=map override source msd type with 'map' -l=cobol override source msd lang with 'COBOL' -l=c override source msd lang with 'c' * -t translate DFH's to KIK's; CICS's to KICKS's -nt do not translate DFH's and CICS's -v show version -? list help where '*'s are built-in defaults; effectively what you get with KIKMG. |
It is not usually necessary to be concerned with these; the exec/proc
sets appropriate values for each pass.
Compiling COBOL programs
Detailed instructions for designing and coding COBOL programs for KICKS may be found by simply Googling "CICS programming". I recommend the IBM sites. Another excellent set of resources are the Murach books "CICS for the COBOL Programmer" and "CICS Programmer's Desk Reference". And don't overlook our own KooKbooK recipes!Preparing a command level COBOL program to run in KICKS requires three steps:
- Run the KICKS command level pre-processor against the COBOL source, generating intermediate source that has been modified as necessary for the current release of KICKS. The pre-processor’s primary function is to translate “EXEC KICKS … END-EXEC” statements into a variety of COBOL statements necessary to implement the desired function. In most cases this ultimately turns into a call to KIKCOBGL which is the KICKS stub that is link edited into every KICKS command level program. To ease conversion of CICS programs to KICKS the pre-processor accepts “EXEC CICS” as equivalent to “EXEC KICKS”. It also generally sees anything starting with DFH as starting with KIK, so for example you don’t have to change something like DFHRESP to it equivalent KIKRESP – the preprocessor will do that for you.
-
Compile the intermediate source with the COBOL compiler.
-
Linkedit the compiled program, including KIKCOBGL for the current release of KICKS and place the resulting load module into a PDS in the KIKRPL concatenation of the KICKS clist.
On an MVS system several procs are supplied for doing all this, each proc corresponding to a different COBOL compiler. The first of these is K2KCOBCL, for the MVT ANSI COBOL compiler. This is the compiler on the Tur(n)key MVS system. It would not normally be installed on a Z/OS system, but is available for download at http://www.jaymoseley.com/hercules/compilers/cobol.htm.
K2KCOBCL's proc header looks like
The proc will have been customized during install so that the default values will contain your TSO id instead of 'HERC01'. Tur(n)key or Z/OS, it is not usually necessary to override these customized defaults.//K2KCOBCL PROC SOUT='*',ZOUT='Z',
// UNT='SYSDA',
// KIKSSYS='HERC01.KICKSSYS',
// KIKSUSR='HERC01.KICKS',
// VER='V1R5M0',
// CBLPARM='SUPMAP,DMAP,CLIST'
Most of the proc arguments should be self explanatory. The step names are COPY. PP1, COB1, PP2, COB2, and LKED. COBs requires a condition code of less than 4 from PPs, and LKED requires condition codes of less than 4 from both PP and COB. PP’s condition code values are 2-warning; 4-error; 8-severe error; 12-fatal error (PP aborts).
| Digression: Why are
the preprocessor & compiler executed twice? KICKS users upgrading from past releases will notice the name of this proc has changed. The old proc, KIKCOBCL, is still available but should not be used. The primary difference between them is that the new proc executes the preprocessor and COBOL compiler twice, instead of once as does the old proc. Why?? Because many KICKS api calls require an argument length. 'Modern' compilers support a LENGTH OF construct that allows the preprocessor to supply this length if it is omitted. The ANSI MVT compiler supplied with the MVS Tur(n)key system does not. To compensate for this missing COBOL feature the preprocessor supplies the feature. It does so by using two passes; the first to obtain the compiler DMAP (ie, symbol table), the second pass to provide the required lengths by referencing the DMAP from the first pass. |
The proc will have been customized during install so that the default values will contain your user id instead of 'HERC01'.. It is not usually necessary to override these customized defaults.//KIKCB2CL PROC SOUT='*',ZOUT='Z',
// UNT='SYSDA',
// KIKSSYS='HERC01.KICKSSYS',
// KIKSUSR='HERC01.KICKS',
// VER='V1R5M0',
// CBLPARM='OFFSET,MAP,XREF'
The rest of the proc arguments are similar to K2KCOBCL. The step names are the same except that since COBOL2 supports "LENGTH OF" the preprocessor and compiler and only executed once in this proc, so PP1 and COB1 are missing.
Besides K2KCOBCL & KIKCB2CL there are 2 similar procs, K2KCOBCS & KIKCB2CS, that are used when you need to setup your program for use with the KEDF source code trace facility and are further explained in that section of the User's Guide.
Numerous examples of use of these procs can be seen in HERC01.KICKSSYS.V1R5M0.COB (CB2 for COBOL2) which compile the sample programs. Briefly, most of them look like this
Where "ENTRY asdf" and "NAME asdf" both reference the PROGRAM-ID in the ID DIVISION.//asdf JOB
// EXEC PROC=K2KCOBCL (or KIKCB2CL for COBOL2)
//COPY.SYSUT1 DD *
…COBOL source…
/*
//LKED.SYSIN DD *
INCLUDE SKIKLOAD(KIKCOBGL)
ENTRY asdf
NAME asdf(R)
/*
On an VM/CMS system several execs are supplied for doing all this, each exec corresponding to a different COBOL compiler.
The first of these is K2KCOBCL, for the MVT ANSI COBOL compiler. This is the compiler on the VM/370 turnkey system. It would not normally be installed on a Z/VM system, but is available for download at http://www.jaymoseley.com/hercules/compilers/cobol.htm. The arguments for this exec are:
pgmname filetype filemode txtlib maclib glue
defaults - COBOL A KIKURPL * KIKCOBGL
There is no particular install customization of this exec.
Another COBOL compile exec is KIKCB2CL, for a 'modern' program product COBOL compiler. It's arguments are the same as K2KCOBCL.
Additional detail about the arguments of these execs can be obtained by typing them without any arguments. The steps executed are the same as in MVS/TSO.
Numerous examples of use of these execs can be seen in the KIKSAMPP EXEC which compiles the sample programs.
It's worth noting that the same KICKS COBOL preprocessor is used on all systems, MVS or VM, legacy or modern. The environmental differences are passed from the clist/exec to the preprocessor mostly thru parm switches, ie
| -s
generate for source debugger * -ns do not generate for source debugger * -t translate DFH's to KIK's; CICS's to KICKS's -nt do not translate DFH's and CICS's -cb2 generate for COBOL 2 instead of ansi COBOL * -ncb2 generate for ansi COBOL instead of COBOL 2 * -wc preprocess 'when compiled' -nwc do not preprocess 'when compiled' * -ndmap no dmap processing -dmapin1 do 1st pass dmap processing -dmapin2 do 2nd pass dmap processing -nosyslib disable pre-processor 'copy' function -nokicks generate for use in normal batch (or for CICS) (not KICKS) apps -v show version -? show help where '*'s are built-in defaults; effectively what you get with K2KCOBCL. KIKCB2CL overrides to provides "-cb2". |
It is not usually necessary to be concerned with these; the proc/exec
sets appropriate values. But sometimes you may not want to translate DFH's and
CICS's, and/or may not want "when compiled" handled by the pre-processor. Of
course you could make your own special copy of K2KCOBCL to handle that but there
is an easier way. The pre-processor understands a few simple 'markup' tags
that you can add to your source program to control the pre-processor's actions.
These tags begin with a "<" in column 1, followed by a tag, followed by a ">",
with the remainder or the line subsequently ignored. Note that none of
these tags may be used within an 'EXEC' block. Here are the tags the
pre-processor understands:
| <T>
following lines handled as if "-t" were specified <NT> following lines handled as if "-nt" were specified <WC> following lines handled as if "-wc" were specified <NWC> following lines handled as if "-nwc" were specified So for example you could use <NT> at the top of a program that didn't want CICS's and DFH's translated; or you could put a <NT> just before lines with such strings in them and then put a <T> after them allowing translations everywhere but the selected lines. Besides the parm switch overrides the pre-processor also supports matched sets of tags. These allow you to conditionally include program lines. The syntax is <xxx> to start, then the lines for that condition, then </xxx> to stop. Conditions are <CB2> lines to </CB2> only generate if -cb2 parm is set <NCB2> lines to </NCB2> only generate if -cb2 parm is not set <TSO> lines to </TSO> only generate if compiled on KICKS for TSO. <NTSO> lines to </NTSO> only generate if not KICKS for TSO. do not assume 'not KICKS for TSO' means 'is KICKS for CMS' <CMS> lines to </CMS> only generate if compiled on KICKS for CMS. <NCMS> lines to </NCMS> only generate if not KICKS for CMS. <NOP> lines to </NOP> do not generate. <REM> for a one line remark. There is no </REM> <KICKS> lines to </KICKS> only generate if -nokicks parm is not set <NOKICKS> lines to </NOKICKS> only generate if -nokicks parm is set <SD>, </SD>, <SN> are used in connection with source code tracing and are explained in that section of the documentation. |
Compiling GCCMVS programs
A GCC C compiler (GCCMVS) and library (PDPCLIB) is included with most legacy MVS and VM/370 distributions and can also be installed on a Z/OS or Z/VM system.Detailed instructions for designing and coding C programs for KICKS are not easy to find, but one place with numerous examples is the SAS C documentation site. KICKS with GCC is not exactly the same as CICS with SASC, but quite similar. And don't overlook our own KooKbooK recipes!
Preparing a command level GCCMVS program to run in KICKS requires three steps:
- Run the KICKS command level pre-processor against the C source, generating intermediate source that has been modified as necessary for the current release of KICKS. The pre-processor’s primary function is to translate “EXEC KICKS … ;” statements into a variety of C statements necessary to implement the desired function. In most cases this ultimately turns into a call to KIKGCCGL which is the KICKS stub that is link edited into every KICKS command level program. To ease conversion of CICS programs to KICKS the pre-processor accepts “EXEC CICS” as equivalent to “EXEC KICKS”. It also generally sees anything starting with DFH as starting with KIK, so for example you don’t have to change something like DFHRESP to it equivalent KIKRESP – the preprocessor will do that for you.
-
Compile the intermediate source with the GCCMVS compiler.
-
Linkedit the compiled program, including KIKGCCGL for the current release of KICKS from HERC01.KICKSSYS.V1R5M0.SKIKLOAD, and place the resulting load module into a PDS in the KIKRPL concatenation of the KICKS clist.
On an MVS system the KIKGCCCL proc is supplied for doing all this. It's proc header looks like
The proc will have been customized during install so that the default values will contain your user id instead of 'HERC01'.//KIKGCCCL PROC OUTC='*',LAOUTC='Z',LBOUTC='Z',
// UNT='SYSDA',
// KIKSSYS='HERC01.KICKSSYS',
// KIKSUSR='HERC01.KICKS',
// VER='V1R5M0',
// ASM='IFOX00', ASMA90 FOR Z/OS// COPTS='',
// LOPTS='XREF,MAP',
// GCCPREF='HERC01.GCC.V80',
// PDPPREF='HERC01.PDPCLIB.V80'
The GCCPREF and PDPPREF default values will probably have to be manually customized. On an MVS380 system they should be 'GCC' and 'PDPCLIB' respectively. On other systems that will likely vary. For example on a Z/OS system GCCMVS will likely have been installed by the TSO user with his own TSO id as a HLQ, and it may be that he would have installed it with a lower level qualifier (like 'V80') to denote what version of the compiler and library was used.
LAOUTC and LBOUTZ are sysout classes for optional listings for the preprocessor C source input and the C source output respectively. Normally they are directed to a JES dummy queue (usually Z), but you may want to override them if errors are detected. If the preprocessor complains about something it will indicate a line number and that number will correspond to a line number in the LAOUTC sysout. If the compiler complains about something it will indicate a line number and that number will correspond to a line number in the LBOUTC sysout.
Most of the other proc arguments should be self explanatory. The step names are COPY, LISTA, PP2, LISTB, COMP, ASM, and LKED. The list steps provides a listing of the preprocessor input and output, with line numbers, so that diagnostics from the compiler and be traced to the offending line of source. This is necessary because the GCCMVS compiler does not provide a listing itself. COMP requires a condition code of less than 4 from PP, and LKED requires condition codes of less than 4 from both PP and COMP. PP’s condition code values are 2-warning; 4-error; 8-severe error; 12-fatal error (PP aborts).
Besides KIKGCCCL there is a similar proc, KIKGCCCS, that is used when you need to setup your program for use with the KEDF source code trace facility and is further explained in that section of the User's Guide.
Some examples of use of these procs can be seen in HERC01.KICKSSYS.V1R5M0.TESTGCC which compile the api test programs. Briefly, most of them look like this
Where "NAME asdf" matches the name you defined for this program in the PPT. If you use a <SN xxxxxxxx> preprocessor markup statement the name in your linkedit NAME statement should match.//asdf JOB
// EXEC PROC=KIKGCCCL
//COPY.SYSUT1 DD *
…GCC source…
/*
//LKED.SYSIN DD *
INCLUDE SKIKLOAD(KIKGCCGL)
ENTRY @@KSTRT
NAME asdf(R)
/*
On an VM/CMS system similarly named KIKGCCCL and KIKGCCCS execs are supplied for the same purpose. The arguments for the KIKGCCCL exec are:
pgmname filetype filemode txtlib maclib glue asmname
defaults - C A KIKURPL * KIKGCCGL ASSEMBLE
There is no particular install customization of this exec.
Additional detail about the arguments of these execs can be obtained by typing them without any arguments. The steps executed are the same as in MVS/TSO.
Numerous examples of use of these execs can be seen in the members of TESTGCC VMARC, which compiles the api test programs.
It's worth noting that the same KICKS GCC preprocessor is used on all systems, MVS or VM, legacy or modern. The environmental differences are passed from the clist/exec to the preprocessor mostly thru parm switches, ie
| -s
generate for source debugger * -ns do not generate for source debugger * -t translate DFH's to KIK's; CICS's to KICKS's -nt do not translate DFH's and CICS's -v show version -nokicks generate for use in normal batch (or for CICS) (not KICKS) apps -? show help where '*'s are built-in defaults; effectively what you get with KIKGCCCL. |
It is not usually necessary to be concerned with these; the proc
sets appropriate values. But sometimes you may not want to translate DFH's and
CICS's. Of
course you could make your own special copy of KIKGCCCL to handle that but there
is an easier way. The pre-processor understands a few simple 'markup' tags
that you can add to your source program to control the pre-processor's actions.
These tags begin with a "<" in column 1, followed by a tag, followed by a ">",
with the remainder or the line subsequently ignored. Note that none of
these tags may be used within an 'EXEC' block. Here are the tags the
pre-processor understands:
| <T>
following lines handled as if "-t" were specified <NT> following lines handled as if "-nt" were specified So for example you could use <NT> at the top of a program that didn't want CICS's and DFH's translated; or you could put a <NT> just before lines with such strings in them and then put a <T> after them allowing translations everywhere but the selected lines. Besides the parm switch overrides the pre-processor also supports matched sets of tags. These allow you to conditionally include program lines. The syntax is <xxx> to start, then the lines for that condition, then </xxx> to stop. Conditions are <TSO> lines to </TSO> only generate if compiled on KICKS for TSO. <NTSO> lines to </NTSO> only generate if not KICKS for TSO. do not assume 'not KICKS for TSO' means 'is KICKS for CMS' <CMS> lines to </CMS> only generate if compiled on KICKS for CMS. <NCMS> lines to </NCMS> only generate if not KICKS for CMS. <NOP> lines to </NOP> do not generate. <REM> for a one line remark. There is no </REM> <KICKS> lines to </KICKS> only generate if -nokicks parm is not set <NOKICKS> lines to </NOKICKS> only generate if -nokicks parm is set <SD>, </SD>, <SN> are used in connection with source code tracing and are explained in that section of the documentation. |
KICKS (CICS) API
KICKS tries to be compatible with the application programming api (Application Programming Interface) as defined in CICS Application Programming Reference, SC33-1688, available online as DFHP400.PDF. Another good reference to this api is Murach's CICS Desk Reference.The api is implemented using EXEC blocks. These blocks are "embedded" in the host programming language (COBOL or GCCMVS), parsed by a preprocessor that replaces the blocks with host language calls to a code library, then the output from the preprocessor is compiled by the host language compiler.
The blocks start with EXEC KICKS, then continue with the name of the function desired, followed by any required and optional arguments for that function, and finish with an END-EXEC. A block may be split over several lines and no continuation markup is required or allowed within it, however individual parameters within the block should not be split across lines. The block should be entirely upper case except, in the case of GCCMVS, for lower case letters that are part of variable names used in function arguments. No host language statements, including comments, should be on any line of the block.
The sole exception to "no host language statements" is that, in COBOL programs, a period may immediately follow the END-EXEC (same line). This period will be placed immediately following the code for the host language calls generated by the block. If no period follows the END-EXEC the generated code will not contain any periods. This behavior is useful when you need such a block inside a COBOL 'if' statement.
In GCCMVS programs the END-EXEC is replaced by a semicolon. These semicolons are 'consumed' by the preprocessor and should not be followed by further statements or comments on the same line. The code generated for the host language calls will be bracketed "{}" so that blocks may be safely placed within normal C constructs (such as 'if' statements).
The following table lists each supported function with a description of its purpose, a syntax diagram, arguments, and exceptional conditions. Syntax is shown for use in COBOL programs but use in GCCMVS programs is identical except that the END-EXEC's are replaced with semicolons.
Although none of the syntax diagrams show it, any of the functions in this table may be coded using the error recovery/reporting arguments NOHANDLE, RESP(data-area), or RESP2(data-area). For RESP the data-area is a PIC S9(4) COMP item (a "short" item for GCCMVS) which will receive a copy of EIBRESP. For RESP2 the data-area is also PIC S9(4) COMP and will receive a copy of EIBRESP2. If none of these are coded, "Exceptional Conditions" will almost always cause an associated transaction abend. Further, regarding "Exceptional Conditions":
- these are run-time conditions, not preprocessor diagnostics.
- reported conditions should be the same as CICS, but KICKS reports conditions as they are discovered and multiple conditions might not be discovered in the same order, which could result in CICS and KICKS reporting different conditions.
Use of non-CICS API’s
Although KICKS currently lacks support for some of the CICS command level programming api, I expect it will ultimately support all the important parts of it. That said, a big KICKS advantage over CICS is freedom from the CICS api! If you don’t care about compatibility, techniques that would crash a CICS system will work very well in KICKS! Since KICKS is itself just a normal TSO application that calls your application, your application can do just about anything you would normally do in a normal TSO or batch application.- Use normal COBOL file access. Define files using the INPUT-OUTPUT
SECTION and FILE-CONTROL in the ENVIRONMENT DIVISION; FILE-SECTION and FD’s
in the DATA DIVISION; normal OPEN’s, CLOSE’s, READ’s, WRITE’s, etc in the
PROCEDURE DIVISION – just like a batch program. Be sure to include ALLOC’s
(and FREE’s) for these files in your KICKS clist…
This is a great way to implement some kind of file access KICKS
does not support, especially ISAM, direct, and partitioned.
But take some care: KICKS won’t be providing any kind of sharing support for this, you must implement any necessary sharing controls yourself! Some possibilities for ‘sharing safe’ allocations include temporary files, files with userid qualified file names, anything with DISP=OLD. -
Use COBOL sort. Define using INPUT-OUTPUT SECTION and FILE-CONTROL in the ENVIRONMENT DIVISION; FILE-SECTION and SD’s in the DATA DIVISION; normal SORT’s and MERGE’s in the PROCEDURE DIVISION – just like a batch program. Be sure to include ALLOC’s (and FREE’s) for these sort work files in your KICKS clist…As with non-sort file access take some care: KICKS won’t be providing any kind of sharing support for this, you must implement any necessary sharing controls yourself. This may not be much of a problem as your sort work files would probably be allocated as temporary files.
-
Use COBOL report writer. Similar to use of normal COBOL files and sort work files as above. Note that closed SYSOUT’s are not usually available for JES processing until KICKS ends (when the ALLOC is FREE’d).
-
For GCCMVS apps compatibility is probably not an issue, but for the record your non-compatible GCCMVS based KICKS app can use most any PDPCLIB or other library api's it needs.
Debugging
The debugging process starts when you realize your program is doing something wrong and ends when you understand why.Many times the whole process happens in your head when you first look at the problem: you've recently made a change to a program, and you realize you didn't consider the situation that you can now see lead to the problem. Debugging over, time to fix the problem.
Unfortunately sometime it's not so easy. Maybe you have just made a change (or two), but you just don't see how your change could possibly cause this mess...
The process (science? art?) you use to discover the cause is way beyond the scope of this documentation, but the process will certainly involve learning more about exactly what is going on to cause the problem, and that will involve using whatever debugging aids are available to help you.
KICKS provides several debugging aids: KICKS abends, user abends via EXEC KICKS ABEND in your program, formatted dumps, internal trace table and auxiliary trace, and KICKS's own 'execution debug facility' (aka KEDF).
When KICKS detects some kind of abnormal condition it usually either generates a defined abend with a dump, or, if your application requested it, returns to your application with appropriate codes set to allow your application to handle the problem. In the event your application requested error return but does not handle the problem it can generate its own abend that can produce a dump (or it can abend without a dump if the cause of the abend is so obvious no dump is needed).
Besides abends generated when KICKS detects some kind of abnormal condition there are three more abends that are the result of MVS detecting some situation. None of these abends are reflected to the user application, all result in KICKS shutdown following a formatted dump and a SYSUDUMP.
The first of these abends is AICA – aka runaway task – which occurs when an application takes longer than the time specified in the ICVR value of the SIT (default 5 seconds) between calls for KICKS service. If your code is doing something that really takes a long time make sure you at least do an EXEC KICKS SUSPEND END-EXEC every 3-4 seconds…
The second of the three special abends is ASRA – aka program check – which occurs when an application (or KICKS itself) gets a program check (0C1-bad instruction, 0C4-storage violation, 0C7-bad data, etc, etc).
The last of the three special abends is ASRB – aka OS abend – when some other kind of OS abend (804/80A out of memory? 222 operator cancel?) is detected.
Transaction Dumps
Here is a sample of the kind of transaction dump KICKS will produce for it's abends, or you can request for your own abends. The KICKS clist usually does not allocate the dump dataset (TRANDUMP), and when KICKS sees this situation it dynamically allocates a SYSOUT dataset for the dump, which is available immediately (you don't have to stop KICKS to get it).Starting at line 158 you see the Exec Interface Block (EIB) contents. You can see (from EIBTRNID) that this is a dump for the DFXX transaction, task number 0006 (from EIBTASKN). You can also see (EIBAID) that the input was terminated with a PF6. Knowing what you do about the DFXX transaction (see EXAMPLES) all you need to do to reproduce this dump is type DFXX (enter), then type PF6. FYI, the source code for the DFXX transaction in HERC01.KICKS.V1R5M0.COB(DFXXP00A).
A little further down (line 274) you see the COMM-AREA and it’s length. Since a COMM-AREA exists (length not equal zero) this is not the first pseudo-conversational call to the program.
Next (lines 315-320) are the decoded trace table entries for the abending task (task 0006 - matching EIBTASKN). If you look just above that in the trace table you will see the entries for task 0005, which was the first pseudo-conversational call.
After that (lines 379-381) are your program registers for the KICKS call that resulted in the abend, with register 14 being the return point in your program DFXXP00A. Just below that (line 383) KICKS has determined that the register 14 return address is at offset 0D5C in program DFXXP00A. and it then lists program DFXXP00A (starting at program relative address 000000). Further down the listing (line 597) relative offset 0D5C is marked with an eyecatching <<<<. Listing your compiled program is not often useful, but the listing does contain your working storage, in this case beginning with ‘ABEND TESTER’ (line 399).
You know from the first line of the dump that this was an AEIL abend (file not found), and since there is only one file operation in DFXXP00A it’s not really a mystery what happened, but it’s easy to use the information in the dump to pinpoint exactly the line in the program where it occurred. Use of offset into DFXXP00A (0D5C, as given at line 383) and compare that to the code offsets in the compile listing CLIST at line 945, which shows the code was ‘between’ the start of line 334 and line 344 (ie, it was the CALL). Note that 334 and 344 are COBOL compiler line numbers corresponding to my compile listing line numbers 744-754. By either set of line numbers, those are lines of code the preprocessor added for the EXEC KICKS READ DATASET api call.
Internal and External API trace
KICKS has internal (in memory) and external (written to disk, or maybe sysout) traces. The internal trace (default 100 entries, settable by the SIT/startup parameter TRCNUM) wraps around, so that it only show the last 100 (sic) entries. The external trace (called the auxiliary trace) is the same format, but does not wrap so there is less risk of losing the necessary information when the chain of events leading to the error is a long one. The internal trace is (by default) always on, but the external trace is (by default) off because there is a pretty high overhead to running it, and because it may cause a crash if it fills up its disk allocation (or the JES2 spool). Since the external trace is normally turned off, you need to use KSMT to turn it on. The strategy is usually (1) use KSMT to turn it on; (2) do whatever you want traced; (3) turn it off; (4) shutdown KICKS and print (or review online) the auxiliary file. The 'REVIEW' utility (pre-installed on TK3UPD, SU1 and MVS380) is the best way I've found to look at this file online.It’s also possible to write a user trace entry into the table. EXEC KICKS ENTER FROM() END-EXEC will do this. The resulting trace table entry will be a PU xxxx (program control entry, user trace, xxxx being text specified in ‘FROM’). The internal trace only saves the first 12 (at most) bytes of your FROM message. Up to 256 bytes of your message will be saved in the external trace (if it is turned on).
Use of non-CICS API’s (for debugging)
Earlier we discussed use of non-CICS api’s. Another use for some of those is debugging. You can sometimes use DISPLAY, EXHIBIT and READY TRACE to your advantage. All of these normally display their output on dd SYSOUT, which the KICKS clist directs to SYSOUT(A). DISPLAY can also be directed to SYSPUNCH (no DD for this in KICKS clist, you’d have to add it) and CONSOLE. I find it very convenient to DISPLAY UPON CONSOLE as I don’t have to wait for KICKS to shutdown to see what I’m after – but you need to make sure you don’t go overboard and flood the console (forcing an IPL).You might be tempted to use ACCEPT (which actually works fine, except…) but I recommend against it. ACCEPT FROM CONSOLE would be your most likely desire and you should understand that it will block – which will trigger an AICA abend as described above when the block exceeds the ICVR value.
KEDF (KICKS Execution Debug Facility)
Debugging from a transaction dump, or using some of the other above discussed techniques is often sufficient. But there's a bigger gun in your arsenal! The Execution Debug Facility ( KEDF ) lets you peek inside your program, while it's running, immediately before and after every (or selected) KICKS api call! You can see the api call itself with all its arguments; the EIB; the COMM-AREA, the program (with WORKING-STORAGE); the internal trace table; and a variety of KICKS storage areas such as the TWA, the CWA, and the TCTTEUA.KEDF is enabled by use of the KEDF transaction, saying ON to turn it on.
kedf on |
which doesn't seem to do much, just acknowledges your request
KEDF is on |
At this point you can type the transaction you want to debug
(clear screen first, or just type it where KEDF left the cursor)
dfxx KEDF is on |
For this example we'll use the DFXX PF6 case we saw in the above
transaction dump, so enter DFXX and press enter
Transaction: DFXX Task: 0005 Program: DFXXP00A Offset X'000B0E' KICKS 1.5.0 Status: ABOUT TO EXECUTE COMMAND 14:39:04 14.304 EXEC KICKS SEND TEXT EIBFN=X'1806' FREEKB ERASE LENGTH(1106) 000000 000BD5C8: C1C2C5D5 C440E3C5 E2E3C5D9 40404040 ABEN D TE STER 000010 000BD5D8: 40404040 40404040 40404040 40404040 000020 000BD5E8: 40404040 40404040 40404040 40404040 000030 000BD5F8: 40404040 40404040 40404040 40404040 000040 000BD608: 40404040 40404040 40404040 40404040 000050 000BD618: 40404040 40404040 40404040 40404040 000060 000BD628: 40404040 40404040 40404040 40404040 000070 000BD638: 40404040 40404040 40404040 40404040 000080 000BD648: 40404040 40404040 40404040 40404040 000090 000BD658: 40404040 40404040 40404040 4040D799 Pr 0000A0 000BD668: 85A2A240 8140D7C6 409285A8 40A39640 ess a PF key to 0000B0 000BD678: 86969983 85409695 85409686 40A38885 forc e on e of the 0000C0 000BD688: 40869693 9396A689 95874081 82859584 fol lowi ng a bend 0000D0 000BD698: A27A4040 40404040 40404040 40404040 s: 0000E0 000BD6A8: 40404040 40404040 40404040 40404040 0000F0 000BD6B8: 40404040 40404040 40404040 40404040 000100 000BD6C8: 40404040 40404040 40404040 40404040 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Well, this is new - it's the initial SEND TEXT from line
667 in the program listing, caught
between DFXX saying to do it and KICKS starting to do it. Let's
take a long look at this screen as it's a model for many more we'll shortly see.
The first thing at the top left of the screen is DFXX. Next is
the task number (EIBTASKN).. Then the name of the program that is
running - DFXXP00A, and the offset within that program to the displayed api
call. If we weren't sure this is from the first SEND TEXT in the program we
could use this offset, and the compile listing CLIST to verify that it is indeed
from line 667.
On the 2nd line left, STATUS tells us this is a picture BEFORE
the api call is executed. On the 2nd line right the date and time are for this
screen display (not EIB date and time).
The 3rd line starts the api listing, telling us this is a SEND
TEXT, with the FREEKB and ERASE options, that the text being sent is 948
characters long, and then showing us the text itself (in dump hex/ebcdic
format).
The bottom line provides some clues about our choices. If we
press ENTER the command will be executed and we will see the results
Transaction: DFXX Task: 0005 Program: DFXXP00A Offset X'000B0E' KICKS 1.5.0 Status: COMMAND EXECUTION COMPLETE 14:39:19 14.304 EXEC KICKS SEND TEXT EIBFN=X'1806' FREEKB ERASE LENGTH(1106) 000000 000BD5C8: C1C2C5D5 C440E3C5 E2E3C5D9 40404040 ABEN D TE STER 000010 000BD5D8: 40404040 40404040 40404040 40404040 000020 000BD5E8: 40404040 40404040 40404040 40404040 000030 000BD5F8: 40404040 40404040 40404040 40404040 000040 000BD608: 40404040 40404040 40404040 40404040 000050 000BD618: 40404040 40404040 40404040 40404040 000060 000BD628: 40404040 40404040 40404040 40404040 000070 000BD638: 40404040 40404040 40404040 40404040 000080 000BD648: 40404040 40404040 40404040 40404040 000090 000BD658: 40404040 40404040 40404040 4040D799 Pr 0000A0 000BD668: 85A2A240 8140D7C6 409285A8 40A39640 ess a PF key to 0000B0 000BD678: 86969983 85409695 85409686 40A38885 forc e on e of the 0000C0 000BD688: 40869693 9396A689 95874081 82859584 fol lowi ng a bend 0000D0 000BD698: A27A4040 40404040 40404040 40404040 s: 0000E0 000BD6A8: 40404040 40404040 40404040 40404040 0000F0 000BD6B8: 40404040 40404040 40404040 40404040 000100 000BD6C8: 40404040 40404040 40404040 40404040 Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Here are the results. STATUS on the 2nd line tells us this is
AFTER the api call is executed. Notice the time at the right of the 2nd line is
updated as well.
On the prior screen the line one up from the bottom was blank.
Now that line shows the KICKS feedback from the api call. On the left is the
text response (would match what you code in a DFHRESP(NORMAL) statement); on the
right is EIBRESP and EIBRESP2, both zero in this case as you would expect for a
NORMAL return..
Lets see what some of those other keys across the bottom do. PF1
is HELP - seems promising
Transaction: DFXX Task: 0005 Program: DFXXP00A Offset X'000B0E' KICKS 1.5.0 Status: COMMAND EXECUTION COMPLETE 14:39:19 14.304 EXEC KICKS SEND TEXT EIBFN=X'1806' FREEKB ERASE LENGTH(1106) 000000 000BD5C8: C1C2C5D5 C440E3C5 E2E3C5D9 40404040 ABEN D TE STER 000010 000BD5D8: 40404040 40404040 40404040 40404040 000020 000BD5E8: 40404040 40404040 40404040 40404040 000030 000BD5F8: 40404040 40404040 40404040 40404040 000040 000BD608: 40404040 40404040 40404040 40404040 000050 000BD618: 40404040 40404040 40404040 40404040 000060 000BD628: 40404040 40404040 40404040 40404040 000070 000BD638: 40404040 40404040 40404040 40404040 000080 000BD648: 40404040 40404040 40404040 40404040 000090 000BD658: 40404040 40404040 40404040 4040D799 Pr 0000A0 000BD668: 85A2A240 8140D7C6 409285A8 40A39640 ess a PF key to Last Response: NORMAL EIBRESP=0, EIBRESP2=0 ENTER - step CLEAR - Show user screen PF1 - help PF2 - src<->api PF3 - goto bkpt PF4 - skip subroutine PF5 - tog bkpt PF6 - .... PF7 - back PF8 - forward PF9 - trace tbl PF10 - eib PF11 - commarea PF12 - working storage 13/1 - tog ST 14/2 - cwa 15/3 - quit 16/4 - 17/5 - dump 18/6 - abend 19/7 - top 20/8 - bottom 21/9 - twa 22/10 - tctteua 23/11 - tioa 24/12- re center |
What happened was a couple extra lines of help pushed up from
the bottom telling us about more PF keys. If you push PF1 again a couple more
lines of this will pop up. Push PF1 a third time will return to the single help
line of the bottom of the screen. For now lets press enter to see what
comes next.
Transaction: DFXX Task: 0005 Program: DFXXP00A Offset X'000EC8' KICKS 1.5.0 Status: ABOUT TO EXECUTE COMMAND 14:40:23 14.304 EXEC KICKS RETURN TRANSID(DFXX) EIBFN=X'0E08' COMM-AREA(000BDA30) COMM-AREA LENGTH(1) 000000 000BDA30: 00 . ENTER - step CLEAR - Show user screen PF1 - help PF2 - src<->api PF3 - goto bkpt PF4 - skip subroutine PF5 - tog bkpt PF6 - .... PF7 - back PF8 - forward PF9 - trace tbl PF10 - eib PF11 - commarea PF12 - working storage |
If we peeked at the program listing we certainly hoped this
would be next! We wrote the screen, so now it's time to become
pseudo-conversational by doing a RETURN TRANSID. Let's press ENTER again to see
what happens AFTER
ABEND TESTER Press a PF key to force one of the following abends: PF1 = ASRA (Data Exception) PF2 = ASRA (Decimal Divide Exception) PF3 = ASRA (Protection Exception) PF4 = ABM0 (Missing Map) PF5 = AEIO (PGMIDERR) PF6 = AEIL (DSIDERR) PF7 = AICA (Run away task) Or press Enter to exit without abending. |
So the program screen is restored and the program is waiting for
us to do something. Before moving on this is a good time to say that KEDF almost
always is able to properly save and restore user screens, but unfortunately not
absolutely 100% of the time. It actually does a much better job of this than
does CICS's similar 'CEDF' facility, but it lacks CEDF's ability to debug using
a second terminal (which probably really is a 100% solution). Using a second
terminal doesn't seem practical in a TSO environment, so my commitment is to fix
all problems with KEDF screen restore, but I can only do so if you bring
problems to my attention! Please do!!
Pick PF6 (the AEIL abend) to follow what was going on in the transaction dump
Transaction: DFXX Task: 0006 Program: DFXXP00A Offset X'000D5C' KICKS 1.5.0 Status: ABOUT TO EXECUTE COMMAND 14:40:49 14.304 EXEC KICKS READ FILE(NOFILE ) EIBFN=X'0602' INTO(X'0BD560') LENGTH(-1) ENTER - step CLEAR - Show user screen PF1 - help PF2 - src<->api PF3 - goto bkpt PF4 - skip subroutine PF5 - tog bkpt PF6 - .... PF7 - back PF8 - forward PF9 - trace tbl PF10 - eib PF11 - commarea PF12 - working storage |
So the next thing that happens is the READ FILE api call. Notice
it shows where the RIDFLD is located and its length, then the RIDFLD itself in
hex and ebcdic, then it shows the INTO location and how big that area is. Notice
the size is shown as -1, meaning the program did not supply a length, telling
KICKS to use the file's record size. Also notice the task number is no
longer 0005, it's incremented to 0006. Press ENTER again and we get
Transaction: DFXX Task: 0006 Program: DFXXP00A Offset X'000D5C' KICKS 1.5.0 Status: COMMAND EXECUTION COMPLETE 14:41:25 14.304 EXEC KICKS READ FILE(NOFILE ) EIBFN=X'0602' INTO(X'0BD560') LENGTH(-1) Last Response: FILENOTFOUND (DSIDERR) EIBRESP=12, EIBRESP2=1 ENTER - step CLEAR - Show user screen PF1 - help PF2 - src<->api PF3 - goto bkpt PF4 - skip subroutine PF5 - tog bkpt PF6 - .... PF7 - back PF8 - forward PF9 - trace tbl PF10 - eib PF11 - commarea PF12 - working storage |
KICKS comes back and says there has been a
problem! It show error responses in RED
to make them harder to miss. Usually the response will be one word, but
FILENOTFOUND is so often called DSIDERR that KICKS recognizes (and
displays) both. On the right you see EIBRESP=12 (filenotfound/dsiderr) and
EIBRESP=1. You could look these up if you want but I'm sure you already know
that "NOFILE" isn't in the FCT. BTW - notice that the
0CE6 offset is the same as
it was in the transaction dump.
Before pressing ENTER to see what happens next let's peek at the
EIB and the internal trace table. Press PF10 to see the EIB
Transaction: DFXX Task: 0006 Program: DFXXP00A Offset X'000D5C' KICKS 1.5.0 Status: COMMAND EXECUTION COMPLETE 14:41:25 14.304 0D486C: EIBCALEN 1 0D486E: EIBCPOSN 0460 (15,1) 0D4870: EIBDATE 0114304F (14.304) 0D4874: EIBTIME 0144049F (14:40:49) 0D4878: EIBRESP 12 0D487C: EIBRESP2 1 0D4880: EIBRSRCE NOFILE 0D4888: EIBDS NOFILE 0D4890: EIBFN 0602 0D4892: EIBRCODE 00 00 00 00 00 00 0D4898: EIBTRMID U0C0 0D48A0: EIBAID F6 0D48A1: EIBOPID 999 0D48A4: EIBUSRID HERC01 0D48AC: EIBSYSID BSP1 0D48C8: EIBPROG DFXXP00A 0D48B4: EIBNETID CUU0C0 0D48C4: EIBLINE 83886195 0D48BC: EIBPGMID DFXXP00A 0D48D0: EIBWC 14:53:09OCT 30, 2014 ENTER - step CLEAR - Show user screen PF1 - help PF2 - src<->api PF3 - goto bkpt PF4 - skip subroutine PF5 - tog bkpt PF6 - .... PF7 - back PF8 - forward PF9 - trace tbl PF10 - eib PF11 - commarea PF12 - working storage |
Notice the difference between EIBTIME and the time in the upper
right corner. This transaction has been "frozen" for almost a minute, meaning
any resources it's holding are unavailable to other users. That's why you should
be a little careful using KEDF if the transaction you are debugging uses
resources (ie, files) someone else might be trying to use. They won't be happy
about the transaction delays and timeouts you are causing them! Probably the
best way to avoid this issue is to use 'test' files for your debugging...
You can also see that it really was
a PF6 that got us here (EIBAID = F6).
On the subject of PF keys (and KEDF
navigation), recall it was a PF10 that got us to this screen. If you press PF10
again on this screen you return to the api screen. Again and you come back to
this screen.. From either of those screens press PF9 to get to the trace screen.
Transaction: DFXX Task: 0006 Program: DFXXP00A Offset X'000D5C' KICKS 1.5.0 Status: COMMAND EXECUTION COMPLETE 14:41:25 14.304 Trace Table storage address 0BB950, length 1600 0001C0 000BBB10: Program Control, exit PX000 0005 0001D0 000BBB20: BMS, send text B04 0005 0001E0 000BBB30: Terminal Control, send T02 0005 0001F0 000BBB40: Terminal Control, exit TX000 0005 000200 000BBB50: BMS, exit BX000 0005 000210 000BBB60: Program Control, return P05 DFXX 0005 000220 000BBB70: Task Control, exit KX001 0000 000230 000BBB80: Terminal Control, receive T03 0000 000240 000BBB90: Terminal Control, exit TX024 0000 000250 000BBBA0: Task Control, attach K02DFXX 0006 000260 000BBBB0: Program Control, load P02DFXXP00A 0006 000270 000BBBC0: Program Control, exit PX000 0006 000280 000BBBD0: File Control, read F06NOFILE 0006 000290 000BBBE0: Program Control, abend (might be tr P07 AEIL 0006 <<<< ENTER - step CLEAR - Show user screen PF1 - help PF2 - src<->api PF3 - goto bkpt PF4 - skip subroutine PF5 - tog bkpt PF6 - .... PF7 - back PF8 - forward PF9 - trace tbl PF10 - eib PF11 - commarea PF12 - working storage |
This is the trace table, scrolled automatically to include the
final entry for this transaction ( 0023 ). Note the AEIL abend,
and the <<<<. marker to show you the
last entry in the table.
Now let's see what DFXX is going
to do with the problem.. Press Enter
ABEND TESTER Press a PF key to force one of the following abends: PF1 = ASRA (Data Exception) PF2 = ASRA (Decimal Divide Exception) PF3 = ASRA (Protection Exception) PF4 = ABM0 (Missing Map) PF5 = AEIO (PGMIDERR) PF6 = AEIL (DSIDERR) PF7 = AICA (Run away task) Or press Enter to exit without abending. Transaction Abend Code AEIL |
Not a surprise, it didn't handle it at all! At this point the
transaction dump we looked at earlier has been written. And although the
transaction has finished, freeing any resources someone else was waiting for, KEDF is actually
still active, waiting for us to do something else. We should press CLEAR, then type KEDF OFF to turn it off.
KEDF is off |
That's a quick intro to KEDF. Now lets look a little deeper.
KEDF filtering
Most real world debugging exercises aren't quite as easily
resolved as this DFXX example. And if the transaction dump sometimes doesn't
provide enough information, KEDF can easily bury you under too much. One problem
is that it "trains" you to press ENTER to move on to the next screen, often
before you've spent the time to realize the answer you are looking for is
staring back at you from the screen you're about to leave behind.
For me, part of the solution to the overabundance is to filter
what I have to look at. Of course filtering has its own risks, and I can't offer
much in the way of advice on how to decide what to filter, but the way I often
use filtering is to help me confirm or refute a hypothesis. For example I might
say "This could be a data problem - let's see what records the transaction is reading and what they look like".
If I'm interested in the files, I don't care (at least for the moment)
about programs or maps being loaded, screens being updated, returns or any of
that stuff - and not having to look at it will help me focus on the few file api
calls I really need to see.
KEDF implements filtering by allowing you to specify which api
calls to break on when you start KEDF. In the last example we used "KEDF
ON" to turn it on, "KEDF OFF" to turn it off. But if you don't say ON or
OFF, but just "KEDF", you get a screen to fine tune your KEDF session.
KEDF (1.5.0) is OFF to toggle it ON press PF4 14:43:31 10/31/14 Highlighed items will be displayed, to change put cursor on item, press PF5 DELETEQ TD DELETE ADDRESS ABEND RECEIVE READQ TD ENDBR ASKTIME DUMP RECEIVE MAP WRITEQ TD READ ASSIGN ENTER SEND TEXT READNEXT ENQ LINK SEND MAP SPOOLOPEN READPREV DELAY LOAD SEND CONTROL SPOOLWRITE RESETBR DEQ RELEASE SPOOLCLOSE REWRITE FORMATTIME RETURN HANDLE CONDITION STARTBR SIGNOFF XCTL IGNORE CONDITION DELETEQ TS UNLOCK SUSPEND HANDLE AID READQ TS WRITE SYNCPOINT FREEMAIN HANDLE ABEND WRITEQ TS WRITE OPERATOR GETMAIN SOURCE TRACE To highlight all press PF6, to Un-high all press PF7 Enter (or PF3) - exit+save Clear - exit+nosave |
From this KEDF screen you can turn it ON or OFF by pressing PF4.
And any of the api's can be toggled on or off by placing the cursor under it and
pressing PF5. They can all be turned on by pressing PF6, and all turned off by
pressing PF7. Pressing ENTER or PF3 saves the on screen changes and exits, while
CLEAR abandons all changes and quits.
So to follow up on my earlier plan to focus on the file control
api's, I'd press PF7 to turn them all off, then move the cursor to DELETE and
press PF5, then down arrow, then PF5, down, PF5, down, PF5, down, ... until the
screen looked like this
KEDF (1.5.0) is OFF to toggle it ON press PF4 14:44:03 10/31/14 Highlighed items will be displayed, to change put cursor on item, press PF5 DELETEQ TD DELETE ADDRESS ABEND RECEIVE READQ TD ENDBR ASKTIME DUMP RECEIVE MAP WRITEQ TD READ ASSIGN ENTER SEND TEXT READNEXT ENQ LINK SEND MAP SPOOLOPEN READPREV DELAY LOAD SEND CONTROL SPOOLWRITE RESETBR DEQ RELEASE SPOOLCLOSE REWRITE FORMATTIME RETURN HANDLE CONDITION STARTBR SIGNOFF XCTL IGNORE CONDITION DELETEQ TS UNLOCK SUSPEND HANDLE AID READQ TS WRITE SYNCPOINT FREEMAIN HANDLE ABEND WRITEQ TS WRITE OPERATOR GETMAIN SOURCE TRACE To highlight all press PF6, to Un-high all press PF7 Enter (or PF3) - exit+save Clear - exit+nosave |
Then press PF4 to turn KEDF on, and ENTER to save all changes
and exit.
KEDF is on |
The filtering changes remain in place until you change them, or
until KICKS is shutdown. On restart the default filters are back.
But the default filters can themselves be changed if desired.
HERC01.KICKSSYS.V1R5M0.INSTLIB(KEDFILTR) is a job to
reassemble the default filter table. Contained within are instructions for setting the default
state (on or off) of each of the api filters.
Source code trace in KEDF
You probably observed references to 'source trace', 'goto bkpt', 'skip subroutine', and similar options on the preceding screens. These refer to controls for an additional level of KEDF tracing. KEDF normally traces KICKS api calls, possibly filtered. When source trace is enabled (and your program has been compiled for it) KEDF traces all your program's statements. Let's take a quick look at the DFXX transaction again, this time with source trace.The first step to using source trace is to compile the program with a proc/exec that put the source into an online dataset so that KEDF can display it at run time. Generally speaking the normal compile proc/exec ends with an 'L' (K2KCOBCL, KIKCB2CL, KIKGCCCL, etc). The compile proc/exec for use with source trace ends with an 'S' (K2KCOBCS, KIKCB2CS, KIKGCCCS, etc).
The COBOL procs/exec uses the name of the program as specified in the "PROGRAM-ID." statement to save the online source. GCC programs have no such internal identification, so the GCC procs/exec require you to add a <SN xxxxxxxx> statement to the source, where xxxxxxxx is the name you want used to identify the online source.
JCL to compile DFXX for source trace, using the K2KCOBCS proc, is in HERC01.KICKS.V1R5M0.COB($DFXX).
KEDF is enabled by use of the KEDF transaction, saying ON/S to turn it on with trace
kedf on/s |
which doesn't seem to do much, just acknowledges your request
KEDF is on |
At this point you can type the transaction you want to debug
(clear screen first, or just type it where KEDF left the cursor)
dfxx KEDF is on |
For this example we'll use the DFXX PF6 case we saw in the above
transaction dump, so enter DFXX and press enter
Transaction: DFXX Task: 000B Program: DFXXP00A Offset X'000B12' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:07:55 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 67 01 MORE-ARGS. 05 FILLER PIC S9(8) COMP. 05 CWA-BLL PIC S9(8) COMP. 01 COMMON-WORK-AREA. 05 CWA-DATE PIC 9(06). PROCEDURE DIVISION. 0000-FORCE-USER-ABEND. * EVALUATE TRUE * WHEN EIBCALEN = ZERO IF EIBCALEN = ZERO EXEC KICKS SEND TEXT FROM(START-UP-MESSAGE) Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
The last time we did this, the first thing we saw was the
'before' screen for the SEND TEXT. This time we start with the PROCEDURE
DIVISION of the program! Let's
take a long look at this screen as it's a model for many more we'll shortly see.
The first thing to note is that the source is displayed in several colors. Blue
indicates the line will not trace and will not support a breakpoint, which makes
sense for all the blue items here as they are either data division or comments.
White indicates the line is the current line. Green indicates the line will
trace and will accept a breakpoint.
Pressing ENTER on this screen will advance to the next
source line.
Transaction: DFXX Task: 000B Program: DFXXP00A Offset X'000B36' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:02 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 69 05 CWA-BLL PIC S9(8) COMP. 01 COMMON-WORK-AREA. 05 CWA-DATE PIC 9(06). PROCEDURE DIVISION. 0000-FORCE-USER-ABEND. * EVALUATE TRUE * WHEN EIBCALEN = ZERO IF EIBCALEN = ZERO EXEC KICKS SEND TEXT FROM(START-UP-MESSAGE) ERASE FREEKB Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000B Program: DFXXP00A Offset X'000B5A' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:03 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 73 05 CWA-DATE PIC 9(06). PROCEDURE DIVISION. 0000-FORCE-USER-ABEND. * EVALUATE TRUE * WHEN EIBCALEN = ZERO IF EIBCALEN = ZERO EXEC KICKS SEND TEXT FROM(START-UP-MESSAGE) ERASE FREEKB END-EXEC * WHEN EIBAID = KIKPF1 ELSE IF EIBAID = KIKPF1 Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000B Program: DFXXP00A Offset X'000BCE' KICKS 1.5.0 Status (S): ABOUT TO EXECUTE COMMAND 20:08:05 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 74 PROCEDURE DIVISION. 0000-FORCE-USER-ABEND. * EVALUATE TRUE * WHEN EIBCALEN = ZERO IF EIBCALEN = ZERO EXEC KICKS SEND TEXT FROM(START-UP-MESSAGE) ERASE FREEKB END-EXEC * WHEN EIBAID = KIKPF1 ELSE IF EIBAID = KIKPF1 MOVE SPACE TO ALPHA-FIELD-2 Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000B Program: DFXXP00A Offset X'0011DC' KICKS 1.5.0 Status (S): ABOUT TO EXECUTE COMMAND 20:08:06 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 136 SEND TEXT FROM(TERMINATION-MESSAGE) ERASE FREEKB END-EXEC EXEC KICKS RETURN END-EXEC. * END-EVALUATE. EXEC KICKS RETURN TRANSID('DFXX') COMMAREA(COMMUNICATION-AREA) END-EXEC. * LOOP-FOREVER. GO TO LOOP-FOREVER. * Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
ABEND TESTER Press a PF key to force one of the following abends: PF1 = ASRA (Data Exception) PF2 = ASRA (Decimal Divide Exception) PF3 = ASRA (Protection Exception) PF4 = ABM0 (Missing Map) PF5 = AEIO (PGMIDERR) PF6 = AEIL (DSIDERR) PF7 = AICA (Run away task) Or press Enter to exit without abending. |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'000B12' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:15 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 67 01 MORE-ARGS. 05 FILLER PIC S9(8) COMP. 05 CWA-BLL PIC S9(8) COMP. 01 COMMON-WORK-AREA. 05 CWA-DATE PIC 9(06). PROCEDURE DIVISION. 0000-FORCE-USER-ABEND. * EVALUATE TRUE * WHEN EIBCALEN = ZERO IF EIBCALEN = ZERO EXEC KICKS SEND TEXT FROM(START-UP-MESSAGE) Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'000B36' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:18 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 69 05 CWA-BLL PIC S9(8) COMP. 01 COMMON-WORK-AREA. 05 CWA-DATE PIC 9(06). PROCEDURE DIVISION. 0000-FORCE-USER-ABEND. * EVALUATE TRUE * WHEN EIBCALEN = ZERO IF EIBCALEN = ZERO EXEC KICKS SEND TEXT FROM(START-UP-MESSAGE) ERASE FREEKB Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'000B5A' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:20 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 73 05 CWA-DATE PIC 9(06). PROCEDURE DIVISION. 0000-FORCE-USER-ABEND. * EVALUATE TRUE * WHEN EIBCALEN = ZERO IF EIBCALEN = ZERO EXEC KICKS SEND TEXT FROM(START-UP-MESSAGE) ERASE FREEKB END-EXEC * WHEN EIBAID = KIKPF1 ELSE IF EIBAID = KIKPF1 Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'000BF8' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:21 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 81 IF EIBCALEN = ZERO EXEC KICKS SEND TEXT FROM(START-UP-MESSAGE) ERASE FREEKB END-EXEC * WHEN EIBAID = KIKPF1 ELSE IF EIBAID = KIKPF1 MOVE SPACE TO ALPHA-FIELD-2 MOVE 100 TO PACKED-FIELD-1 MULTIPLY PACKED-FIELD-1 BY PACKED-FIELD-2 * WHEN EIBAID = KIKPF2 ELSE IF EIBAID = KIKPF2 MOVE 100 TO PACKED-FIELD-1 MOVE ZERO TO PACKED-FIELD-2 Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'000CC8' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:23 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 87 * WHEN EIBAID = KIKPF1 ELSE IF EIBAID = KIKPF1 MOVE SPACE TO ALPHA-FIELD-2 MOVE 100 TO PACKED-FIELD-1 MULTIPLY PACKED-FIELD-1 BY PACKED-FIELD-2 * WHEN EIBAID = KIKPF2 ELSE IF EIBAID = KIKPF2 MOVE 100 TO PACKED-FIELD-1 MOVE ZERO TO PACKED-FIELD-2 DIVIDE PACKED-FIELD-2 INTO PACKED-FIELD-1 * WHEN EIBAID = KIKPF3 ELSE IF EIBAID = KIKPF3 * SET ADDRESS OF COMMON-WORK-AREA TO NULL MOVE 0 TO CWA-BLL Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'000D9A' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:25 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 93 * WHEN EIBAID = KIKPF2 ELSE IF EIBAID = KIKPF2 MOVE 100 TO PACKED-FIELD-1 MOVE ZERO TO PACKED-FIELD-2 DIVIDE PACKED-FIELD-2 INTO PACKED-FIELD-1 * WHEN EIBAID = KIKPF3 ELSE IF EIBAID = KIKPF3 * SET ADDRESS OF COMMON-WORK-AREA TO NULL MOVE 0 TO CWA-BLL MOVE ZERO TO CWA-DATE * WHEN EIBAID = KIKPF4 ELSE IF EIBAID = KIKPF4 EXEC KICKS SEND MAP('NOMAP1') Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'000E2C' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:26 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 99 * WHEN EIBAID = KIKPF3 ELSE IF EIBAID = KIKPF3 * SET ADDRESS OF COMMON-WORK-AREA TO NULL MOVE 0 TO CWA-BLL MOVE ZERO TO CWA-DATE * WHEN EIBAID = KIKPF4 ELSE IF EIBAID = KIKPF4 EXEC KICKS SEND MAP('NOMAP1') MAPSET('NOSET1') FROM(I-O-AREA) ERASE END-EXEC * WHEN EIBAID = KIKPF5 ELSE Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'000EE2' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:28 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 108 EXEC KICKS SEND MAP('NOMAP1') MAPSET('NOSET1') FROM(I-O-AREA) ERASE END-EXEC * WHEN EIBAID = KIKPF5 ELSE IF EIBAID = KIKPF5 EXEC KICKS XCTL PROGRAM('NOPGM1') END-EXEC * WHEN EIBAID = KIKPF6 ELSE IF EIBAID = KIKPF6 EXEC KICKS READ DATASET('NOFILE') Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'000F78' KICKS 1.5.0 Status (S): SOURCE CODE TRACE 20:08:29 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 114 * WHEN EIBAID = KIKPF5 ELSE IF EIBAID = KIKPF5 EXEC KICKS XCTL PROGRAM('NOPGM1') END-EXEC * WHEN EIBAID = KIKPF6 ELSE IF EIBAID = KIKPF6 EXEC KICKS READ DATASET('NOFILE') INTO(I-O-AREA) RIDFLD(ALPHA-FIELD-2) END-EXEC * WHEN EIBAID = KIKPF7 ELSE IF EIBAID = KIKPF7 Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'001008' KICKS 1.5.0 Status (S): ABOUT TO EXECUTE COMMAND 20:08:31 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 115 ELSE IF EIBAID = KIKPF5 EXEC KICKS XCTL PROGRAM('NOPGM1') END-EXEC * WHEN EIBAID = KIKPF6 ELSE IF EIBAID = KIKPF6 EXEC KICKS READ DATASET('NOFILE') INTO(I-O-AREA) RIDFLD(ALPHA-FIELD-2) END-EXEC * WHEN EIBAID = KIKPF7 ELSE IF EIBAID = KIKPF7 PERFORM LOOP-FOREVER Last Response: NORMAL EIBRESP=0, EIBRESP2=0 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
Transaction: DFXX Task: 000C Program: DFXXP00A Offset X'001008' KICKS 1.5.0 Status (S): COMMAND EXECUTION COMPLETE 20:08:32 14.306 COB program compiled 19:35:11NOV 02, 2014, now at line 115 ELSE IF EIBAID = KIKPF5 EXEC KICKS XCTL PROGRAM('NOPGM1') END-EXEC * WHEN EIBAID = KIKPF6 ELSE IF EIBAID = KIKPF6 EXEC KICKS READ DATASET('NOFILE') INTO(I-O-AREA) RIDFLD(ALPHA-FIELD-2) END-EXEC * WHEN EIBAID = KIKPF7 ELSE IF EIBAID = KIKPF7 PERFORM LOOP-FOREVER Last Response: FILENOTFOUND (DSIDERR) EIBRESP=12, EIBRESP2=1 PF1 - help PF3 - goto bkpt ENTER - step CLEAR - Show user screen |
ABEND TESTER Press a PF key to force one of the following abends: PF1 = ASRA (Data Exception) PF2 = ASRA (Decimal Divide Exception) PF3 = ASRA (Protection Exception) PF4 = ABM0 (Missing Map) PF5 = AEIO (PGMIDERR) PF6 = AEIL (DSIDERR) PF7 = AICA (Run away task) Or press Enter to exit without abending. Transaction Abend Code AEIL |
Although the
transaction it done, KEDF is actually
still active, waiting for us to do something else. We should press CLEAR, then type KEDF OFF to turn it off.
KEDF is off |
Source trace is a powerful feature and you may be tempted to
compile all your programs to use it. You should be aware it has substantial
overhead. First there is the file space the source data base uses to store your
programs so that they can be displayed online. Probably more significant is the
cpu overhead, and the corresponding slow down of executed programs, even when
not actively tracing. This is due to adding several new statements before almost
every original statement in your program! It is especially noticeable when
program loops are used for character handling or similar activates. This effect
can be reduced by using the <SD> and </SD> preprocessor markup to turn on and
off (respectively) the generation of these additional statements. Of course if
generation is off the original statements within the marked off block will show
up in blue, meaning that you can't step thru them nor set breakpoints within
them. KEBRPGM is a good example of use of <SD> and </SD> for such purpose.
Summary of KEDF commands
ENTER Pressing ENTER restores the user screen and returns to the user program. Often the next user program api occurs so quickly that the user screen is not seen, or seen only as a flash before the KEDF screen is showing again.CLEAR Pressing CLEAR displays the user screen. Pressing CLEAR in that user screen display returns to the preceding KEDF display. Actually, pressing any AID key will return to the KEDF display.
PF1 ( help ) Pressing PF1 toggles between 1 line, 4 lines, and 7 lines of PF key command help at the bottom of the screen.
PF2 ( src <-> api ) Pressing PF2 switches between Source mode and API mode. If Source mode the first field on the 2nd screen line will show Status (S), if in API mode it will show Status (A). This is only relevant in source trace mode (see PF13), and the difference is only apparent when the current line is a KICKS api call. If in Source mode the About to Execute Command api call is shown inline with the source, and the Command Execution Complete screen is suppressed. If in API mode the api call screens (both About & Complete) are shown as they normally are when not doing source trace.
PF3 ( goto bkpt ) Pressing PF3 restores the user screen and returns to the user program, then ignores further source or api trace events until until (a) a breakpoint (see PF5) is hit, or (b) a new transaction starts (see PF6), or (c) a KICKS api call results in an exceptional condition (ie, EIBRESP <> 0).
PF4 ( skip subroutine ) Pressing PF4 sets a temporary breakpoint at the next executable statement past the current statement (ie, the next green line), then does a "go to breakpoint" (see PF3). When that breakpoint is hit it is automatically unset. Assuming the current statement is a call or perform, this normally results in 'skipping' the called or performed code. Note however that the "next executable statement past the current statement" may not be the statement that will be executed when the called/performed code returns - so some care must be exercised in using this.
PF5 ( toggle breakpoint ) If the cursor is at the default location (just past Last Response:) pressing PF5 toggles a breakpoint at the current line (the white line in the middle of the screen). If the cursor is instead on a line that is breakable (green) pressing PF5 toggles a breakpoint on that line. Breakpoints show up in reverse video. When breakpoints are set the right side of line 3 shows the number set and the maximum number the can be set.
PF6 ( .... or transaction id ) Pressing PF6 toggles the help text beside PF6 between '....' and the current transaction id. When it's .... a "go to breakpoint" will stop when the current transaction number changes (ie, the next pseudo conversational task). When it's a transaction id a "go to breakpoint will not stop until the transaction id is different from that.
PF7 ( page backward ) Pressing PF7 scrolls any scrollable area on the screen backward (toward lower addresses). PF8 will scroll the other way. PF19 (shift PF7) scrolls to the top (lowest address). PF20 (shift PF8) scrolls to the bottom (highest address). PF24 (shift PF12) will re-center on whatever was initially showing. These keys can used (for example) to page thru a program source listing in source trace mode.
PF8 ( page forward ) Pressing PF8 scrolls any scrollable area on the screen forward (toward higher addresses).
PF9 ( trace tbl ) Pressing PF9 displays the trace table. The scrolling keys (PF7, PF8, PF19, PF20, PF24) can be used to review the otherwise off screen portions.
PF10 ( EIB ) Pressing PF10 displays the EIB. This usually fits on one screen (but you may need to press PF1 a couple times to reduce the number help lines on a 24 line display).
PF11 ( CommArea ) Pressing PF11 displays a line showing the address and size of the current comm area, and if the length is non-zero it displays the comm area in a scrollable 'dump' format. In this dump format the first column is the offset, the second column is the address, the next 4 columns are 16 characters in hex format, and the last 4 columns are the same 16 characters in ebcdic (dots for unprintable).
PF12 ( Working Storage ) Pressing PF12 displays a line showing the address and size of the current program (including any internal working storage), and if the length is non-zero it displays the program in a scrollable 'dump' format.
PF13 ( tog ST ) Pressing PF13 (shift PF1) toggles source code display on/off. When source code trace is on the first field on the 2nd screen line will show Status (S) or Status (A). When it is off the 2nd screen line will show just Status.
PF14 ( CWA ) Pressing PF14 (shift PF2) displays a line showing the address and size of the common work area, and if the length is non-zero it displays the CWA in a scrollable 'dump' format.
PF15 ( QUIT ) Pressing PF15 (shift PF3) turns off KEDF and returns to the user program. KEDF can be turned on again by using the KEDF transaction.
PF16 ( unassigned )
PF17 ( dump ) Pressing PF17 (shift PF5) generates a transaction dump (code KEDF) for the user transaction, but no abend.
PF18 ( abend ) Pressing PF18 (shift PF6) generates a transaction abend (code KEDF) for the user transaction, which of course also terminates the current KEDF presentation. KEDF remains active however and will trace the next transaction.
PF19 ( top ) Pressing PF19 (shift PF7) scrolls any scrollable area on the screen backward (to the lowest address).
PF20 ( bottom ) Pressing PF20 (shift PF8) scrolls any scrollable area on the screen forward (to the highest address).
PF21 ( TWA ) Pressing PF21 (shift PF9) displays a line showing the address and size of the transaction work area, and if the length is non-zero it displays the TWA in a scrollable 'dump' format.
PF22 ( TCTTEUA ) Pressing PF22 (shift PF10) displays a line showing the address and size of the terminal user area, and if the length is non-zero it displays the TCTTEUA in a scrollable 'dump' format.
PF23 ( TIOA ) Pressing PF23 (shift PF11) displays a line showing the address and size of the terminal I/O area, and if the length is non-zero it displays the TIOA in a scrollable 'dump' format.
PF24 ( re-center ) Pressing PF24 (shift PF12) scrolls any scrollable area on the screen to its initial location.
Securing your program from KEDF trace
If you accidentally leave KEDF turned on you'll see that essentially all command level programs will trace. But a few do not (like KEDF, KSGM, KSSF), and you may wonder how to similarly secure your own program's operation.First, understand that the overhead of normal KEDF trace (not talking about source trace here!) code in your own program is minimal if KEDF is not turned on. Balance this tiny overhead against the ability to closely observe your program's operation if that becomes necessary. Still, there are may be situations where you do not want your program's operation observed, or have concerns that such observation may cause other problems (such as holding files for long periods).
To prevent KEDF from tracing your COBOL program linkedit it with KIKCOBGX instead of with KIKCOBGL. Linkedit your GCC program with KIKGCCGX instead of with KIKGCCGL. Note this will prevent trace, but will not eliminate the compiled in overhead in a source trace enabled program. The only way to do that is to recompile the program without source trace enabled.
No comments:
Post a Comment