| KICKS |
A transaction processing system for CMS & TSO |
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.
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
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.
//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 /* /* //
Here is the output (from DD CRLPOUT) the above JCL produces. I've highlighted the echoed input in yellow...
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.
KICKS is supplied with a number of transactions and associated programs to assist with its operation These include
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.
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.
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.
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 |
As above,KSMT is PF key driven, PF12 quits.
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.
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 |
KEDF is PF driven. On the top line you will note use of PF4 to turn the debugger on or off. On the bottom line you will note use of ENTER or PF3 to exit with changes saved, and CLEAR to exit with any changes discarded. PF6 is used to highlight (enable) all the api's, and PF7 is used to un-highlight (disable) all the api's. Individual api's can be toggled between enabled/disabled by moving the cursor to the api name and pressing PF5.
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.
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...
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.
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 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 TSTST
and 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 |
If instead you invoke the KEBR transaction and do not supply a queue name the transaction responds by displaying the temporary storage queue whose name consists of the four letters KEBR followed by the four letters of your terminal identifier.
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 transaction display consists of a header, a command area, a body (the primary display area), and a menu of functions you can select at this point.
The headerThe header shows:
The command area
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:
The GET and PUT commands do not need to be used as a pair. You can add to a transient data queue from a temporary storage queue with a PUT command at any time. If you are debugging code that reads a transient data queue, you can create a queue in temporary storage (with the KEBR GET command, or by program) and then refresh the transient data queue as many times as you like from temporary storage. Similarly, you can empty a transient data queue by using a GET command without a corresponding PUT command.
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.
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.
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.
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.
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.