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

//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'                          

The proc header is customized during installation so that it is usually only necessary to specify the MAPNAME of the map to be gnerated.

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:

  1. 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.

  2. Compile the intermediate source with the COBOL compiler.

  3. 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.

An optional 4th step is to add the source code to an online vsam file so that the debugger's source trace facility can display it at run time. This is discussed in the KEDF section of this User's Guide.

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

//K2KCOBCL PROC SOUT='*',ZOUT='Z',                    
//           UNT='SYSDA',                             
//           KIKSSYS='HERC01.KICKSSYS',               
//           KIKSUSR='HERC01.KICKS',                  
//           VER='V1R5M0',                            
//           CBLPARM='SUPMAP,DMAP,CLIST'              

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.

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.

Another COBOL compile proc is KIKCB2CL, for a 'modern' program product COBOL compiler. It's proc header looks like

//KIKCB2CL PROC SOUT='*',ZOUT='Z',                   
//           UNT='SYSDA',                            
//           KIKSSYS='HERC01.KICKSSYS',              
//           KIKSUSR='HERC01.KICKS',                 
//           VER='V1R5M0',                           
//           CBLPARM='OFFSET,MAP,XREF'               

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.

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

//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)                                         
/*                                                   

Where "ENTRY asdf" and  "NAME asdf" both reference the PROGRAM-ID in the ID DIVISION.

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:

  1. 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.

  2. Compile the intermediate source with the GCCMVS compiler.

  3. 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.

An optional 4th step is to add the source code to an online vsam file so that the debugger's source trace facility can display it at run time. This is discussed in the KEDF section of this User's Guide.

On an MVS system the KIKGCCCL proc is supplied for doing all this. It's proc header looks like

//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 proc will have been customized during install so that the default values will contain your user id instead of 'HERC01'.

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

//asdf JOB                                           
// EXEC PROC=KIKGCCCL                                
//COPY.SYSUT1 DD *                                   
…GCC source…                                         
/*                                                   
//LKED.SYSIN DD *                                    
INCLUDE SKIKLOAD(KIKGCCGL)                           
ENTRY @@KSTRT                                        
NAME asdf(R)                                         
/*                                                   

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.

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":

ABEND

Purpose:

The ABEND function forces the current task to terminate abnormally. If a HANDLE ABEND is in effect control will be transferred to the routine it specifies, otherwise control returns to KICKS.

Syntax:

EXEC KICKS ABEND

      [ABCODE(name)]

      [NODUMP]

END-EXEC

Arguments:

ABCODE(name) - specifies the 4 character ID used to title the storage dump and/or in the message produced for the terminal user.

 

NODUMP - a storage dump will be produced unless NODUMP is specified.

Exceptional Conditions:

None

Notes:

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(TESTPGM) for usage example.
ADDRESS

Purpose:

The ADDRESS function lets you access system information that's maintained in storage outside your program.

Syntax:

EXEC KICKS ADDRESS

      [COMMAREA(pointer-ref)]
      [CSA(pointer-ref)]

      [CWA(pointer-ref)]

      [EIB(pointer-ref)]
      [TCTUA(pointer-ref)]

      [TIOA(pointer-ref)]

      [TIOAUSED(pointer-ref)]

      [TWA(pointer-ref)]

END-EXEC

Arguments:

COMMAREA(pointer-ref) - obtains the address of the current commarea.
 

CSA(pointer-ref) - obtains the address of the Common System Area. The CSA address is not especially useful in either CICS or KICKS (since the CSA is OCO in both), but in CICS the pointer returned will always be an EVEN number, and in KICKS it will always be an ODD number (actually -1). This provides a way for a program to determine at run time if it is in KICKS or CICS.

 

CWA(pointer-ref) - obtains the address of the Common Work Area.

 

EIB(pointer-ref)- obtains the address of the Exec Interface Block.
 

TCTUA(pointer-ref) - obtains the address of the Terminal User Area.

 

TIOA(pointer-ref)- obtains the address of the Terminal Input/Output Area. This area's address is available in KICKS but not in CICS. After a READ MAP, READ TEXT, SEND MAP,  SEND TEXT, or SEND CONTROL the area pointed to will contain the raw 3270 data for the last READ or SEND.

 

TIOAUSED(pointer-ref) - obtains the address of a PIC S9(4) COMP item containing the number of characters of the TIOA currently used. This area's address is available in KICKS but not in CICS. TIOAUSED+1 is where the next character will go in an output TIOA.

  

TWA(pointer-ref)- obtains the address of the Transaction Work Area.

Exceptional Conditions:

None

Notes:

  • One at a time! In CICS a single EXEC ADDRESS can obtain addresses of 1 or many of the above arguments, but KICKS requires that you code a separate EXEC ADDRESS for each of the arguments you need.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(ASSADRTS) for usage examples.
ASKTIME

Purpose:

The ASKTIME function lets you obtain the current time and date. This information is stored in two EIB fields: EIBTIME and EIBDATE. When a task is started those fields are updated to reflect the starting time and date for the task. ASKTIME simply updates those fields. You can also use the ABSTIME argument to specify a field where KICKS places an absolute time. You can then use this field in a FORMATTIME function to format the time in one of several ways.

Syntax:

EXEC KICKS ASKTIME

      [ABSTIME(data-area)]

END-EXEC

Arguments:

ABSTIME(data-area) - specifies an 8 byte area to receive the number of milliseconds elapsed since midnight January 1, 1900. Format is packed - PIC S9(15) COMP-3. This value may be passed to FORMATTIME to generate external representations of date and time.

Exceptional Conditions:

None

Notes:

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(FMTTIME) for usage examples.
ASSIGN

Purpose:

The ASSIGN function lets you obtain information from various KICKS system areas.

Syntax:

EXEC KICKS ASSIGN

      [ABCODE(data-area)]

      [ALTSCRNHT(data-area)]

      [ALTSCRNWD(data-area)]

      [COLOR(data-area)]

      [CWALENG(data-area)]

      [DEFSCRNHT(data-area)]

      [DEFSCRNWD(data-area)]

      [EWASUPP(data-area)]

      [EXTDS(data-area)]

      [FACILITY(data-area)]

      [FCI(data-area)]

      [HILIGHT(data-area)]

      [LANGINUSE(data-area)]

      [NATLANGINUSE(data-area)]

      [NETNAME(data-area)]

      [OPID(data-area)]

      [PARTNS(data-area)]

      [PROGRAM(data-area)]

      [PS(data-area)]

      [SCRNHT(data-area)]

      [SCRNWD(data-area)]

      [SYSID(data-area)]

      [TCTUALENG(data-area)]

      [TERMCODE(data-area)]

      [TIOASIZE(data-area)]

      [TWALENG(data-area)]

      [USERID(data-area)]

END-EXEC

Arguments:

ABCODE(data-area) - gets the abend code associated with a captured abend (HANDLE ABEND) into a PIC X(4) item.

 

ALTSCRNHT(data-area) - gets the alternate screen height into a PIC S9(4) COMP item.

 

ALTSCRNWD(data-area) - gets the alternate screen width into a PIC S9(4) COMP item.

 

COLOR(data-area) - gets the terminal's 'color' attribute into a PIC X item, which is high values if color is supported (low values otherwise).

 

CWALENG(data-area) - gets the length of the Common Work Area (CWA) into a PIC S9(4) COMP item.

 

DEFSCRNHT(data-area) - gets the default screen height into a PIC S9(4) COMP item.

 

DEFSCRNWD(data-area) - gets the default screen width into a PIC S9(4) COMP item.

 

EWASUPP(data-area) - gets the terminal's 'erase write alternate' attribute into a PIC X item, which is high values if erase write alternate is supported (low values otherwise).

 

EXTDS(data-area) - gets the terminal's 'extended data stream' attribute into a PIC X item, which is high values if extended data streams are supported (low values otherwise).

 

FACILITY(data-area) - gets the terminal's ID into a PIC X(4) field.

 

FCI(data-area) - gets the type of facility used by the task into a PIC X field. For KICKS this will always be X'01', meaning 'terminal'.

 

HILIGHT(data-area) - gets the terminal's 'extended highlighting' attribute into a PIC X item, which is high values if extended highlighting is supported (low values otherwise).

 

LANGINUSE(data-area) - gets the 3 byte mnemonic code showing the language in use. This 3 byte code has a 1-1 relationship with the 1 byte NATLANGINUSE code.

 

NATLANGINUSE(data-area) - gets the 1 byte mnemonic code showing the language in use. This 1 byte code has a 1-1 relationship with the 3 byte LANGINUSE code.

The NATLANGINUSE code is directly specified with the NATLANG parameter in the KICKS SIT and may be overriden as usual during KICKS startup. It may be an upper case A-Z or 0-9. The default is 'E', aka 'ENU', aka US English. A table relating the codes to each other can be found in SC33-1688.

 

NETNAME(data-area) - gets the terminal's ID into a PIC X(8) field.

 

OPID(data-area) - gets the operator id (not userid!) into a PIC X(3) field.

 

PARTNS(data-area) - gets the terminal's 'partition' attribute into a PIC X item, which is high values if partitions are supported (low values otherwise). Note that KICKS does not presently support terminal partitions.

 

PROGRAM(data-area) - gets the name of the last loaded program (or mapset) into a PIC X(8) area.

 

PS(data-area) - gets the terminal's 'programmed symbols' attribute into a PIC X item, which is high values if programmed symbols are supported (low values otherwise). Note that KICKS does not presently support programmed symbols.

 

SCRNHT(data-area) - gets the current screen height into a PIC S9(4) COMP item.

 

SCRNWD(data-area) - gets the current screen width into a PIC S9(4) COMP item.

 

SYSID(data-area) - gets the 'system id' into a PIC X(4) item. In CICS the 'system id' is a unique id for each CICS system. In KICKS for TSO the 'system id' is the SMF id of the MVS system. In KICKS for CMS the 'system id' is spaces.

 

TCTUALENG(data-area) - gets the length of the Terminal User Area (TCTTEUA) into a PIC S9(4) COMP item.

 

TERMCODE(data-area) - gets a code defining the terminal type into a PIC S9(4) COMP item. Currently in KICKS this code will be either X'9902' (for a 3270 terminal), or X'1800' (for the CRLP sequential terminal).

 

TIOASIZE(data-area) - gets the size of the TIOA (Terminal Input Output Area) into a PIC S9(4) COMP item. This is available in KICKS but not in CICS.

  

TWALENG(data-area) - gets the length of the Transaction Work Area (TWA) into a PIC S9(4) COMP item.

 

USERID(data-area) - gets the 'userid' (not the Operator id!) into a PIC X(8) item. In KICKS this is usually your TSO id.

Exceptional Conditions:

None

Notes:

  • One at a time! In CICS a single EXEC ASSIGN can obtain information about 1 to 16 of the above, but KICKS requires that you code a separate EXEC ASSIGN for each of those you need.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(ASSADRTS) for usage examples.
DELAY

Purpose:

The DELAY function lets you suspend your task until specified time interval has elapsed or a specified time of day has arrived.

Syntax:

EXEC KICKS DELAY

       INTERVAL(hhmmss)

       TIME(hhmmss)

       FOR [HOURS(hh)] [MINUTES(mm)] [SECONDS(ss)]
       UNTIL [HOURS(hh)] [MINUTES(mm)] [SECONDS(ss)]

END-EXEC

Arguments:

INTERVAL(hhmmss) - delay for an amount of time specified by the PIC S9(7) COMP-3 variable hhmmss, where the top 2 digits (hh) are for the number of hours, the middle 2 digits (mm) are for the number of minutes, and the bottom 2 digits (ss) are for the number of seconds.

 

TIME(hhmmss) - delay until local time specified by the PIC S9(7) COMP-3 variable hhmmss is reached. As in INTERVAL, hhmmss represents the hour, minute and second of the time, in this case local time at which to end the delay.

 

FOR [HOURS(hh)] [MINUTES(mm)] [SECONDS(ss)] - delay for an 'INTERVAL' with the amount of time specified by HOURS(hh) and/or MINUTES(mm) and/or SECONDS(ss) where hh, mm, and ss are PIC S9(8) COMP variables.


UNTIL [HOURS(hh)] [MINUTES(mm)] [SECONDS(ss)] - delay until local time specified by the HOURS(hh) and/or MINUTES(mm) and/or SECONDS(ss) variables is reached. As in FOR, hh, mm, and ss are PIC S9(8) COMP.

Exceptional Conditions:

EXPIRED (aka eibresp=31)(aka abend AEI4) - (eibresp2=0) the time specified by TIME or UNTIL has already past. This can't happen for INTERVAL or FOR.

 

INVREQ (aka eibresp=16)(aka abend AEIP) - (eibresp2=0) the delay exceeds the SIT MAXDELY setting.

Notes:

  • Pick only one of INTERVAL, TIME, FOR, or UNTIL.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(DELAYTST) for usage examples.
DELETE DATASET/FILE

Purpose:

The DELETE function removes a record from a file. The record may have been previously read by a READ function with the UPDATE argument, or the record may be retrieved and deleted in a single operation by the DELETE function. The file can be a VSAM KSDS or RRDS, or a path, but not an ESDS.

Syntax:

EXEC KICKS DELETE 

       DATASET(name) | FILE(name)
       RIDFLD(data-area) KEYLENGTH(data-value)
       GENERIC NUMREC(data-area) RRN RBA

END-EXEC

Arguments:

DATASET(name) | FILE(name) - the 1-8 character name by which the VSAM file is accessed. This name must match an entry in the KICKS FCT.


RIDFLD(data-area) - "key" defining the record to be deleted.

 

KEYLENGTH(data-value) - the PIC S9(4) COMP length of the RIDFLD that is to be used to identify record(s) to be deleted. If GENERIC is specified this should be less than key length in the idcams DEFINE for the file, otherwise it should be exactly equal to the key length for idcams. If keylength is omitted the key size from the file definition is used.


GENERIC - specifies that only part of the key (RIDFLD) is used to identify records to be deleted. All records whose first 'keylength' bytes match will be deleted.

 

NUMREC(data-area) - a PIC S9(4) COMP receiving field that will be set to the number of records actually deleted.

 

RRN - specified that the RIDFLD is a relative record number for a VSAM RRDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

 

RBA - specified that the RIDFLD is a relative byte address for a VSAM KSDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

Exceptional Conditions:

DSIDERR (aka FILENOTFOUND) - The DATASET | FILE is not defined in the FCT.

 

DISABLED - the DATASET | FILE is defined in the FCT, but it is 'disabled', probably because it previously failed to open

 

NOTOPEN - the DATASET | FILE did not open

RESP2 = 60  - open failed due to VSAM open error, causes file to be marked 'disabled'.

RESP2 = 99  - open failed due to enqueue failure, does NOT disable

ILLOGIC - VSAM error. See EIBRCODE bytes 2,3,4,5 for VSAM rplrtncd, rplerrcd, rplfuncd, and rplcmpon

RESP2 = 110 - undifferentiated.

RESP2 = -1  - should not happen

IOERROR - an I/O error occurred.

 

INVREQ - invalid request

RESP2 = 21  - delete from ESDS not supported

RESP2 = 22  - GENERIC specified, but file is RRDS

RESP2 = 25  - generic, given keylength > real keylength

RESP2 = 26  - not generic, given keylength != real keylength

RESP2 = 31  - RIDFLD not given, no prior "READ FOR UPDATE"

RESP2 = 42  - keylength < 0

RESP2 = 902 - should not happen (preprocessor allowed bad code?)

RESP2 = 903 - RBA specified, but file is RRDS

RESP2 = 904 - RRN specified, but file is KSDS

NOTFND - the specified record could not be located.

Notes:

  • KICKS does not report the DUPKEY condition as does CICS.

  • See the api test members TESTDKS, TESTDES, and TESTDRR (in HERC01.KICKSSYS.V1R5M0.TESTCOB) for usage examples.
DELETEQ TD

Purpose:

The DELETEQ TD function deletes the records in  transient data queue, reclaiming the space occupied by its records and removing any records that have not been read.

Syntax:

EXEC KICKS DELETEQ TD QUEUE(name) END-EXEC

Arguments:

QUEUE(name) - Specifies the one to four character name of the destination queue to be deleted.

Exceptional Conditions:

DISABLED - the queue is disabled.

 

INVREQ - the queue specifies an extrapartition queue. DELETEQ TD is only valid for intrapartition queues.

 

QIDERR - the queue isn't defined in the DCT.
DELETEQ TS

Purpose:

The DELETEQ TS function deletes a temporary storage queue, deleting any records remaining in the queue and reclaiming the space used by the queue.

Syntax:

EXEC KICKS DELETEQ TS QUEUE(name) END-EXEC

Arguments:

QUEUE(name) or QNAME(name) - Specifies the one to 16 character name of the temporary storage queue to be deleted.

Exceptional Conditions:

QIDERR - the queue doesn't exist.
DEQ

Purpose:

The DEQ function releases a user-defined resource that was reserved for exclusive use by an ENQ function issued by your task. Tasks of other KICKS users that have issued an ENQ function for the same resource will then be allowed to continue.

Syntax:

EXEC KICKS DEQ

       RESOURCE(data-area) [LENGTH(data-value)]
      [LUW | TASK | MAXLIFETIME(data-area)]

END-EXEC

Arguments:

RESOURCE(data-area) - identifies the resource to be released. If LENGTH is also specified the character string (up to 255 bytes) contained in the data-area is used to identify the resource. If LENGTH is omitted the address of the data-area identifies the resource.

 

LENGTH(data-value) - specifies a value indicating the length of the character sting specified in RESOURCE.

 

LUW - specifies that the resource was acquired with the LUW duration.

 

TASK - specifies that the resource was acquired with the TASK duration.

 

MAXLIFETIME(data-area) - specifies a value defining the acquired resource duration. Valid values are DFHVALUE(LUW)=246, and DFHVALUE(TASK)=233.

Exceptional Conditions:

INVREQ - the MAXLIFETIME value is invalid.

 

LENGERR - the LENGTH value is specified and is less than 1 or greater than 255.

Notes:

  • It is not an error to DEQ a resource that is not (or no longer) ENQ'ed.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(ENQDEQ) for usage examples.
DUMP

Purpose:

The DUMP function produces a storage dump but does not terminate the transaction.

Syntax:

EXEC KICKS DUMP

      DUMPCODE(data-value) | FROM(data-area)

    [ FLENGTH(data-value)  | LENGTH(data-value) ]

END-EXEC

Arguments:

DUMPCODE(data-value) - Specifies a 1-4 character name that identifies the dump.

 

FROM(data-area) - identifies a storage item that will be dumped and/or begins the storage to be dumped. If omitted a full transaction dump will be printed.

 

LENGTH(data-value)

FLENGTH(data-value) - specifies the number of bytes of storage to be dumped. If length is omitted  the preprocessor will pass the actual length of the FROM data-area.

Exceptional Conditions:

None

Notes:

  • DUMP does not cause an abend; the transaction continues after the dump is produced. To generate a dump and an abend use the ABEND function.

  • A transaction dump is produced automatically by most ABENDS, and much of the information in a transaction dump is available online using KEDF, so there is seldom a need to code a DUMP function.

  • Many other arguments valid in CICS are allowed but are taken only as comments.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(ENTRTST) for usage examples.
ENDBR

Purpose:

The ENDBR function terminates a browse operation.

Syntax:

EXEC KICKS ENDBR 

       DATASET(name) | FILE(name)

      [REQID(data-value)]

END-EXEC

Arguments:

FILE(name)

DATASET(name) - synonyms for the one to eight character name of the

dataset. The dataset must be defined in the FCT.

 

REQID(data-value) - specifies a PIC S9(4) COMP numeric value that identifies the browse operation. Normally used only when you need more than one browse active at a time. Default is zero.

Exceptional Conditions:

DSIDERR (aka FILENOTFOUND) - The DATASET | FILE is not defined in the FCT.

 

DISABLED - the DATASET | FILE is defined in the FCT, but it is 'disabled', probably because it previously failed to open

 

NOTOPEN - the DATASET | FILE did not open

RESP2 = 60  - open failed due to VSAM open error, causes file to be marked 'disabled'.

RESP2 = 99  - open failed due to enqueue failure, does NOT disable

INVREQ - not browsing, no STARTBR in effect...

Notes:

  • See the api test members TESTBKS, TESTBKP, TESTBES, TESTBEP and TESTBRR (in HERC01.KICKSSYS.V1R5M0.TESTCOB) for usage examples.
ENQ

Purpose:

The ENQ function reserves a user-defined resource for exclusive use by your task. All other KICKS users that issue an ENQ function for the same resource will be suspended until your task ends or does a DEQ function for the resource.

Syntax:

EXEC KICKS ENQ

       RESOURCE(data-area) [LENGTH(data-value)]
      [LUW | TASK | MAXLIFETIME(data-area)]

      [NOSUSPEND]

END-EXEC

Arguments:

RESOURCE(data-area) - identifies the resource to be reserved. If LENGTH is also specified the character string (up to 255 bytes) contained in the data-area is used to identify the resource. If LENGTH is omitted the address of the data-area identifies the resource.

 

LENGTH(data-value) - specifies a value indicating the length of the character sting specified in RESOURCE.

 

LUW - specifies that the resource should be held until the end of the current Logical Unit of Work. This is the default.

 

TASK - specifies that the resource should be held until the task ends.

 

MAXLIFETIME(data-area) - specifies a value defining how long the resource should be held. Valid values are DFHVALUE(LUW)=246, and DFHVALUE(TASK)=233.

 

NOSUSPEND - indicates that if the resource is already reserved, control is to be returned immediately to your program, with a failure notification

Exceptional Conditions:

ENQBUSY - indicates that another task has reserved the resource you specified

 

INVREQ - the MAXLIFETIME value is invalid.

 

LENGERR - the LENGTH value is less than 1 or greater than 255.

Notes:

  • It is not an error to ENQ a resource that your task already ENQ'ed. This simply increases your task's ENQ count for that resource. You should DEQ such resources the same number of times you ENQ'ed them.

  • KICKS won't actually be enqueing anything if you don't specify LENGTH. That's because since each KICKS users is in a different address space the RESOURCE addresses won't match, and there is only one task in the user's own KICKS system.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(ENQDEQ) for usage examples.
ENTER

Purpose:

The ENTER function writes a user trace entry in the KICKS trace table (and to the auxiliary trace file is it is open). The trace table is displayed when a transaction dump is produced and may also be examined using KEDF.

Syntax:

EXEC KICKS ENTER

       TRACENUM(data-value) | TRACEID(data-value)
       FROM(data-area) FROMLENGTH(data-area)

       RESOURCE(data-area) EXCEPTION

END-EXEC

Arguments:

TRACENUM(data-value)

TRACEID(data-value) - TRACENUM & TRACEID are synonyms for a number (1-199) that will be used as the trace identifier to associate with this user trace entry.

 

FROM(data-area) - a character field or literal that will be placed into the trace entry. Only the first 8 of these can be stored in the internal trace table entry, but up to 255 characters will be written to the auxiliary trace if it is available.

 

FROMLENGTH(data-area) - the length of the FROM field. If fromlength is omitted the preprocessor will pass the actual length of the FROM data-area or literal.

 

RESOURCE(data-area) - allowed as comments only, KICKS does not process.

 

EXCEPTION - allowed as comments only, KICKS does not process.

Exceptional Conditions:

None

Notes:

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(ENTRTST) for usage examples.
FORMATTIME

Purpose:

The FORMATTIME function accepts a time value in the absolute time format and returns a time value in any of several other formats.

Syntax:

EXEC KICKS FORMATTIME ABSTIME(data-value)

       DATESEP(data-value)

       TIMESEP(data-value)

       YYDDD(data-area)
       YYYYDDD(data-area)

       YYMMDD(data-area)
       YYYYMMDD(data-area)
       YYDDMM(data-area)

       YYYYDDMM(data-area)

       DDMMYY(data-area)

       DDMMYYYY(data-area)

       MMDDYY(data-area)
       MMDDYYYY(data-area)
       DAYCOUNT(data-area)

       DAYOFWEEK(data-area)

       DAYOFMONTH(data-area)
       MONTHOFYEAR(data-area)

       YEAR(data-area)

       TIME(data-area)
END-EXEC

Arguments:

ABSTIME(data-value) - specifies a PIC S9(15) COMP-3 field containing the number of milliseconds elapsed since midnight January 1, 1900. This is usually obtained using the ASKTIME function.

 

DATESEP(data-value) - specifies a 1 byte value to be used as a separator between the month, day, and year in data values. If you omit DATESEP no separator is used. In CICS the argument of DATESEP is optional; in KICKS it is not.

 

TIMESEP(data-value) - specifies a 1 byte value to be used as a separator between the hour, minute, and second in time values. If you omit TIMESEP no separator is used. In CICS the argument of TIMESEP is optional; in KICKS it is not.

 

YYDDD(data-area)
YYYYDDD(data-area)

YYMMDD(data-area)
YYYYMMDD(data-area)
YYDDMM(data-area)

YYYYDDMM(data-area)

DDMMYY(data-area)

DDMMYYYY(data-area

MMDDYY(data-area)
MMDDYYYY(data-area) - specifies a character field to contain the formatted date, format being as indicated. Day, month, and year values will be separated using DATESEP if that was also specified. Receiving field size should be as indicated plus the number of separators.


DAYCOUNT(data-area) - specifies a PIC S9(8) COMP field to contain the number of days that have passes since January 1, 1900, which is day 1.

 

DAYOFWEEK(data-area) - specifies a PIC S9(8) COMP field to contain the day of the week. Sunday is day 0, Monday is day 1, ...

 

DAYOFMONTH(data-area) - specifies a PIC S9(8) COMP field to contain the day of the month. The first is 1, the second is 2, ...


MONTHOFYEAR(data-area) - specifies a PIC S9(8) COMP field to contain the month of the year. January is 1, February is 2, ...

 

YEAR(data-area) - specifies a PIC S9(8) COMP field to contain the four digit year.

 

TIME(data-area) - specifies a character field to contain the formatted time, format being as hhmmss. Hours, minutes, and second values will be separated using TIMESEP if that was also specified. Receiving field size should be as indicated plus the number of separators.

Exceptional Conditions:

INVREQ - ABSTIME value is invalid (not a valid PIC S9(15) COMP-3 number or specifies an invalid value).

Notes:

  • One at a time! In CICS a single EXEC FORMATTIME can generate information up to all of the above, but KICKS requires that you code a separate EXEC FORMATTIME for each of those you need. Pick one of: DATESEP and any of the date formats, or TIMESEP and TIME.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(FORMATIM) for usage examples.
FREEMAIN

Purpose:

The FREEMAIN function releases storage that was previously acquired using the GETMAIN function.

Syntax:

EXEC KICKS FREEMAIN

       DATA(data-area) | DATAPOINTER(pointer-ref)

END-EXEC

Arguments:

DATA(data-area) - specifies the name of the variable to be freed.

 

DATAPOINTER(pointer-ref) - specifies a pointer to the variable to be freed.

Exceptional Conditions:

INVREQ - storage specified not GETMAIN'ed (or perhaps previously FREEMAIN'ed).

Notes

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(GETFREE) for usage examples.
GETMAIN

Purpose:

The GETMAIN function acquires a specified amount of storage that is held until a FREEMAIN function is issued to release it (or, in the case of storage acquired without the SHARED argument, end of task).

Syntax:

EXEC KICKS GETMAIN

       SET(pointer-ref)

       LENGTH(data-value)| FLENGTH(data-value)
      [INITIMG(data-value)]

      [SHARED] [BELOW] [NOSUSPEND] [USERKEY] [CICSKEY]

END-EXEC

Arguments:

SET(pointer-ref) - specifies a variable to contain the address of the storage acquired.

 

LENGTH(data-value)

FLENGTH(data-value) - specifies a variable or literal value to indicate the length of storage to be acquired.

 

INITIMG(data-value) - specifies a 1 byte field or literal value used to initialize the storage acquired. If omitted the storage will not be initialized to any particular value.

 

SHARED - specifies that the storage will not be automatically freed when the task ends. Instead it must be explicitly freed by a FREEMAIN function (by this task or by some future task).

 

NOSUSPEND - default in KICKS, accepted as comments.

 

BELOW

USERKEY

CICSKEY - these arguments are accepted as comments only

Exceptional Conditions:

LENGERR - The specified length is less than one


NOSTG - The requested storage is not available

Notes:

  • The NOSTG condition does not result in an abend. You must check EIBRESP to ensure storage was actually obtained.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(GETFREE) for usage examples.
HANDLE ABEND

Purpose:

The HANDLE ABEND function establishes an abend exit which receives control when an abend occurs.

Syntax:

EXEC KICKS HANDLE ABEND
       LABEL(label) | CANCEL | RESET
END-EXEC

Arguments:

LABEL(label) - specifies the paragraph or section name of a routine within the current program that is to be invoked (by GO TO) if the program abends.

 

CANCEL - specifies that the effect of a previously established HANDLE ABEND is to be cancelled.

 

RESET - specifies that a previously cancelled HANDLE ABEND should be reestablished.

Exceptional Conditions:

None

Notes:

  • Catches normal abends but not AICA, ASRA, or ASRB

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(LINKTST) for usage example.
HANDLE AID

Purpose:

The HANDLE AID function establishes routines that are invoked when an AID key is detected by a RECEIVE command.

Syntax:

EXEC KICKS HANDLE AID
       KEY-NAME(label) KEY-NAME(label) ...
END-EXEC

Arguments:

KEY-NAME(label) - specifies the name of the AID key to be handled and the name of a paragraph or section that is to receive control (by GO TO) when the specified AID key is detected. If no label is specified any existing HANDLE for that AID is cancelled. The function recognizes AID names ENTER, CLEAR, PA1-3, and PF1-24.

 

Exceptional Conditions:

None

Notes:

  • 1 to16 at a time

  • KEY-NAMEs being ENTER, CLEAR, PA1, PA2, PA3, PF1, PF2, ... PF9, PF10, ... PF24

  • To cancel a previously issued HANDLE AID that associated some key with some label, just issue another HANDLE AID specifying the key without any label - ie - "EXEC KICKS HANDLE AID SOMEKEY END-EXEC".

  • HANDLE AID is not supported in GCCMVS KICKS programs.

  • See any of HERC01.KICKS.V1R5M0.COB(TAC?????) for usage examples.
HANDLE CONDITION

Purpose:

The HANDLE CONDITION function establishes routines that are invoked when certain exceptional conditions are detected.

Syntax:

EXEC KICKS HANDLE CONDITION
       CONDITION-NAME(label) CONDITION-NAME(label) ...
END-EXEC

Arguments:

CONDITION-NAME(label) - specifies the name of the condition to be handled and the name of a paragraph or section that is to receive control (by GO TO) when the specified condition is detected. If no label is specified any existing HANDLE for that condition is cancelled. The function recognizes the same condition names as DFHRESP.

Exceptional Conditions:

None

Notes:

  • 1 to16 at a time

  • To cancel a previously issued HANDLE CONDITION that associated some condition with some label, just issue another HANDLE CONDITION specifying the condition without any label - ie - "EXEC KICKS HANDLE CONDITION SOMECONDITION END-EXEC".

  • HANDLE CONDITION is not supported in GCCMVS KICKS programs.

  • See any of HERC01.KICKS.V1R5M0.COB(TAC?????) for usage examples.
IGNORE CONDITION

Purpose:

The IGNORE CONDITION function specifies that when certain exceptional conditions are detected the usual system action is ignored and control is returned to your program as usual.

Syntax:

EXEC KICKS IGNORE CONDITION
       CONDITION-NAME CONDITION-NAME ...
END-EXEC

Arguments:

CONDITION-NAME - specifies the name of the condition to be ignored. The function recognizes the same condition names as DFHRESP.

Exceptional Conditions:

None

Notes:

  • 1 to 16 at a time

  • CONDITION-NAMEs same as HANDLE CONDITION

  • There is a difference between HANDLE CONDITION no-label and IGNORE CONDITION. The former turns off handling of the condition, which means your transaction will abend if the condition occurs. The latter turns off the default action (abend) for the condition, so that if the condition occurs your transaction will continue and must itself detect the condition and take appropriate action.

  • IGNORE CONDITION is not supported in GCCMVS KICKS programs.
LINK

Purpose:

The LINK function invokes a program and optionally passes data to it. When the invoked program ends control returns to the statement following the LINK function.

Syntax:

EXEC KICKS LINK PROGRAM(name)

      [COMMAREA(data-area) [LENGTH(data-value)]]
END-EXEC

Arguments:

PROGRAM(name) - specifies the one to eight character name of the program to be invoked. The name must be defined in the PPT.

 

COMMAREA(data-area) - specifies a data area that is passed to the invoked program as a communication area. The invoked program access the data via its DFHCOMMAREA field, so it is the same storage in the invoking program and the invoked program, therefore the invoked program may change the storage and the invoking program will see the changes.

 

LENGTH(data-value) - the length of the data area specified in the COMMAREA argument. If length is omitted  the preprocessor will pass the actual length of the COMMAREA data-area.

Exceptional Conditions:

PGMIDERR - The program is not in the PPT

 

DISABLED - The PPT entry for the program is disabled (happens for example if the program is not present in the KIKRPL library concatenation).

 

LENGERR - the LENGTH specified is to large.

Notes:

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(LINKTST) for usage example
LOAD

Purpose:

The LOAD function retrieves an object module and returns the entry point and length.

Syntax:

EXEC KICKS LOAD PROGRAM(name)
      [LENGTH(data-area) | FLENGTH(data-area]
      [ENTRY(pointer-ref) | SET(pointer-ref) ]

      [HOLD]
END-EXEC

Arguments:

PROGRAM(name) - specifies the one to eight character name of the object module to be loaded. The name must be defined in the PPT.

 

LENGTH(data-area) - specifies an S9(4) COMP variable that is set to the length of the object module.

 

FLENGTH(data-area) - specifies an S9(8) COMP variable that is set to the length of the object module.

 

ENTRY(pointer-ref) - specifies an S9(8) COMP variable that is set to the entry point of the loaded object module.

 

SET(pointer-ref) - specifies an S9(8) COMP variable that is set to the load point of the loaded object module.

 

HOLD - specifies that the loaded object module will be retained in storage until it is RELEASE'd. If HOLD is not specified the object module will be deleted from storage when the task ends.

Exceptional Conditions:

PGMIDERR - The program is not in the PPT

 

DISABLED - The PPT entry for the program is disabled (happens for example if the program is not present in the KIKRPL library concatenation).

Notes:

  • An object's entry point (where your program calls it) is not necessarily the same as it's load point (where it begins in storage).

  • Automatic deletion of a LOAD'd object module at task end (due to not coding HOLD) will only occur if your task's LOAD was responsible for bringing the module into storage. If it was previously LOAD'd with a HOLD and your task's LOAD only returned its address the module will remain in storage until RELEASE'd (ie, the original HOLD will continue to be honored).

  • See HERC01.KICKSSYS.V1R5M0.COB(KEDFPGM) for usage example (loading/modifying KEDFILTR).
READNEXT

Purpose:

The READNEXT function retrieves the next sequential record from a file during a browse operation. The file may be a VSAM KSDS, ESDS, RRDS, or a path.

Syntax:

EXEC KICKS READNEXT DATASET(name) | FILE(name)

       INTO(data-area) LENGTH(data-area)

       RIDFLD(data-area) KEYLENGTH(data-area)

      [RBA | RRN] [REQID(data-value)]

END-EXEC

Arguments:

FILE(name)

DATASET(name) - synonyms for the one to eight character name of the dataset. The dataset must be defined in the FCT.

 

INTO(data-area) - specifies the area that will contain the record being read.

 

LENGTH(data-area) - PIC S9(4) COMP length of the record. On entry it should be set to the size of the INTO argument. On return it will be the size of the record actually retrieved. If length is omitted the record size from the file definition is used, and of course there is no feedback of the size of the actual record read.

 

RIDFLD(data-area) - "key" defining the record to be read.

 

KEYLENGTH(data-value) - PIC S9(4) COMP length of RIDFLD that is to be used to identify record(s) to be read. If keylength is omitted the key size from the file definition is used.

 

RRN - specified that the RIDFLD is a relative record number for a VSAM RRDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

 

RBA - specified that the RIDFLD is a relative byte address for a VSAM KSDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

 

REQID(data-value) - specifies a PIC S9(4) COMP numeric value that identifies the browse operation. Normally used only when you need more than one browse active at a time. Default is zero.

Exceptional Conditions:

DSIDERR (aka FILENOTFOUND) - The DATASET | FILE is not defined in the FCT.

 

DISABLED - the DATASET | FILE is defined in the FCT, but it is 'disabled', probably because it previously failed to open

 

NOTOPEN - the DATASET | FILE did not open

RESP2 = 60  - open failed due to VSAM open error, causes file to be marked 'disabled'.

RESP2 = 99  - open failed due to enqueue failure, does NOT disable

ILLOGIC - VSAM error. See EIBRCODE bytes 2,3,4,5 for VSAM rplrtncd, rplerrcd, rplfuncd, and rplcmpon

RESP2 = 110 - undifferentiated.

RESP2 = -1  - should not happen

IOERROR - an I/O error occurred.

 

INVREQ - invalid request.

    RESP2 = 25  - GENERIC & KEYLENGTH given,

                  but given KEYLENGTH > real!

    RESP2 = 26  - GENERIC not given, KEYLENGTH given,

                  but KEYLENGTH <> real!

    RESP2 = 34  - REQID not found - no STARTBR?

    RESP2 = 37  - RBA/RRN does not match STARTBR

    RESP2 = 42  - GENERIC & KEYLENGTH given, but KEYLENGTH < 0

    RESP2 = 905 - KEYLENGTH given with RBA/RRN

 

LENGERR - the length of the record is longer than the LENGTH argument specifies.

 

DUPKEY - indicates that at least one more record of the same key exists. Occurs only when accessing the file via an alternate index path (that allows duplicate keys).

 

ENDFILE - indicates that there are no more records to read.

Notes:

  • See the api test members TESTBKS, TESTBKP, TESTBES, TESTBEP and TESTBRR (in HERC01.KICKSSYS.V1R5M0.COB) for usage examples.
READPREV

Purpose:

The READPREV function retrieves the previous sequential record from a file during a browse operation. In other words, READPREV reads records backwards. The file may be a VSAM KSDS, ESDS, RRDS, or a path.

Syntax:

EXEC KICKS READPREV DATASET(name) | FILE(name)

       INTO(data-area) LENGTH(data-area)

       RIDFLD(data-area) KEYLENGTH(data-area)

      [RBA | RRN] [REQID(data-value)]

END-EXEC

Arguments:

FILE(name)

DATASET(name) - synonyms for the one to eight character name of the

dataset. The dataset must be defined in the FCT.

INTO(data-area) - specifies the area that will contain the record being read.

 

LENGTH(data-area) - PIC S9(4) COMP length of the record. On entry it should be set to the size of the INTO argument. On return it will be the size of the record actually retrieved. If length is omitted the record size from the file definition is used, and of course there is no feedback of the size of the actual record read.

 

RIDFLD(data-area) - "key" defining the record to be read.

 

KEYLENGTH(data-value) - PIC S9(4) COMP length of RIDFLD that is to be used to identify record(s) to be read. If keylength is omitted the key size from the file definition is used.

 

RRN - specified that the RIDFLD is a relative record number for a VSAM RRDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

 

RBA - specified that the RIDFLD is a relative byte address for a VSAM KSDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

 

REQID(data-value) - specifies a PIC S9(4) COMP numeric value that identifies the browse operation. Normally used only when you need more than one browse active at a time. Default is zero.

Exceptional Conditions:

DSIDERR (aka FILENOTFOUND) - The DATASET | FILE is not defined in the FCT.

 

DISABLED - the DATASET | FILE is defined in the FCT, but it is 'disabled', probably because it previously failed to open

 

NOTOPEN - the DATASET | FILE did not open

RESP2 = 60  - open failed due to VSAM open error, causes file to be marked 'disabled'.

RESP2 = 99  - open failed due to enqueue failure, does NOT disable

ILLOGIC - VSAM error. See EIBRCODE bytes 2,3,4,5 for VSAM rplrtncd, rplerrcd, rplfuncd, and rplcmpon

RESP2 = 110 - undifferentiated.

RESP2 = -1  - should not happen

IOERROR - an I/O error occurred.

 

INVREQ - invalid request.

    RESP2 = 25  - GENERIC & KEYLENGTH given,

                  but given KEYLENGTH > real!

    RESP2 = 26  - GENERIC not given, KEYLENGTH given,

                  but KEYLENGTH <> real!

    RESP2 = 34  - REQID not found - no STARTBR?

    RESP2 = 37  - RBA/RRN does not match STARTBR

    RESP2 = 42  - GENERIC & KEYLENGTH given, but KEYLENGTH < 0

    RESP2 = 905 - KEYLENGTH given with RBA/RRN

 

LENGERR - the length of the record is longer than the LENGTH argument specifies.

 

DUPKEY - indicates that at least one more record of the same key exists. Occurs only when accessing the file via an alternate index path (that allows duplicate keys).

 

ENDFILE - indicates that there are no more records to read.

Notes:

  • See the api test members TESTBKS, TESTBKP, TESTBES, TESTBEP and TESTBRR (in HERC01.KICKSSYS.V1R5M0.COB) for usage examples.
READQ TD

Purpose:

The READQ TD function reads a record from a specified transient data queue (aka destination).

Syntax:

EXEC KICKS READQ TD QUEUE(name)

       INTO(data-area) LENGTH(data-area)

       NOSUSPEND

END-EXEC

Arguments:

QUEUE(name) - Specifies the one to four character name of the destination queue to be read.

 

INTO(data-area) - specifies the data area that will contain the record to be read.

 

LENGTH(data-area) - specifies the S9(4) COMP data area that, on entry, contains the maximum number of characters of data that will fit in the INTO data area. On return it contains the number of characters actually read into the data area. If length is omitted the size of the INTO area is used, and of course there is no feedback of the size of the actual record read.

 

NOSUSPEND - a required argument indicating immediate return (with RC) if the queue is not available (being used for output).

Exceptional Conditions:

NOTOPEN - the queue is not opened. This is reported only on first access, thereafter DISABLED is reported.

 

DISABLED - the queue is disabled.

 

INVREQ - the queue type is extrapartition and it is opened for output (so it can't be read).

 

QIDERR - the queue isn't defined in the DCT.

 

QBUSY - the queue is being used by another KICKS user.

 

QZERO - there are no (more) records in the queue. This is a normal 'end of file' condition.

Notes:

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(DCPTST) for usage examples.

  • NOSUSPEND is an optional argument in CICS, but is required in KICKS.

READQ TS

Purpose:

The READQ TS function reads a record from a specified temporary storage queue.

Syntax:

EXEC KICKS READQ TS QUEUE(name)

       INTO(data-area) LENGTH(data-area)

      [NUMITEMS(data-area)] [ITEM(data-value) | NEXT]
END-EXEC

 

Arguments:

QUEUE(name) or QNAME(name) - Specifies the one to 16 character name of the temporary storage queue to be read.

 

INTO(data-area) - specifies the data area that will contain the record to be read.

 

LENGTH(data-area) - specifies the S9(4) COMP data area that, on entry, contains the maximum number of characters of data that will fit in the INTO data area. On return it contains the number of characters actually read into the data area.If length is omitted the size of the INTO area is used, and of course there is no feedback of the size of the actual record read.

 

NUMITEMS(data-area) - specifies the S9(4) COMP data area that, on return, will contain the total number of records in the specified queue.

 

NEXT

ITEM(data-value) - specifies the S9(4) COMP data area that, on entry, contains the item number of the queue record to be retrieved, or, that the NEXT record should be retrieved.

Exceptional Conditions:

QIDERR - the queue doesn't exist.

 

ITEMERR - no record exists for the ITEM number requested. This is a normal 'end of file' condition.
READ DATASET/FILE

Purpose:

The READ function retrieves one record from a file, which can be a VSAM KSDS, ESDS, RRDS, or path.

Syntax:

EXEC KICKS READ DATASET(name) | FILE(name)

       INTO(data-area) LENGTH(data-area)

       RIDFLD(data-area) KEYLENGTH(data-area)

      [GENERIC] [RBA | RRN] [GTEQ | EQUAL] [UPDATE]

END-EXEC

Arguments:

FILE(name)

DATASET(name) - synonyms for the one to eight character name of the dataset. The dataset must be defined in the FCT.

 

INTO(data-area) - specifies the area that will contain the record being read.

 

LENGTH(data-area) - PIC S9(4) COMP length of the record. On entry it should be set to the size of the INTO argument. On return it will be the size of the record actually retrieved. If length is omitted the record size from the file definition is used, and of course there is no feedback of the size of the actual record read.

 

RIDFLD(data-area) - "key" defining the record to be read.

 

KEYLENGTH(data-value) - PIC S9(4) COMP length of RIDFLD that is to be used to identify record(s) to be read. If keylength is omitted the key size from the file definition is used.

 

RRN - specified that the RIDFLD is a relative record number for a VSAM RRDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

 

RBA - specified that the RIDFLD is a relative byte address for a VSAM KSDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

 

GENERIC - specifies that only part of the key in the RIDFLD argument should be used, as indicated by the KEYLENGTH argument.

 

EQUAL - specifies that the record whose key matches the RIDFLD exactly will be read.

 

GTEQ - specifies that the first record whose key is greater than or equal to the key specified in the RIDFLD argument will be read. This will always retrieve a record unless the specified key is greater than the largest in the file.

 

UPDATE - specifies your intent to update the retrieved record (by REWRITE'ing or DELETE'ing it). The record is held for your exclusive use (other tasks can't get it) until you do a REWRITE, DELETE, or UNLOCK for it - or until your task ends or you complete a logical unit of work (by issuing a SYNCPOINT).

Exceptional Conditions:

DSIDERR (aka FILENOTFOUND) - The DATASET | FILE is not defined in the FCT.

 

DISABLED - the DATASET | FILE is defined in the FCT, but it is 'disabled', probably because it previously failed to open

 

NOTOPEN - the DATASET | FILE did not open

RESP2 = 60  - open failed due to VSAM open error, causes file to be marked 'disabled'.

RESP2 = 99  - open failed due to enqueue failure, does NOT disable

ILLOGIC - VSAM error. See EIBRCODE bytes 2,3,4,5 for VSAM rplrtncd, rplerrcd, rplfuncd, and rplcmpon

RESP2 = 110 - undifferentiated.

RESP2 = -1  - should not happen

IOERROR - an I/O error occurred.

 

LENGERR - the length of the record is longer than the LENGTH argument specifies.

 

DUPKEY - indicates that at least one more record of the same key exists. Occurs only when accessing the file via an alternate index path (that allows duplicate keys).

 

NOTFND - indicates that there is no record with the required key.

 

INVREQ - invalid request.

RESP2 = 26  - not GENERIC and KEYLENGTH <> real key length.

RESP2 = 28  - read to file with update already pending.

RESP2 = 902 - can't RBA & RRN both, can't EQUAL & GTEQ both

RESP2 = 903 - can't RBA for RRDS.

RESP2 = 904 - can't RRN if not RRDS.

RESP2 = 905 - KEYLENGTH not allowed with ESDS, RRDS.

Notes:

  • See the api test members TESTDKS, TESTDES, and TESTDRR (in HERC01.KICKSSYS.V1R5M0.COB) for usage examples.
RECEIVE INTO

Purpose:

The RECEIVE function retrieves input data sent from a terminal. BMS mapping is not used so the format of the received data will be that of a raw 3270 input buffer (aka tioa, Terminal Input/Output Area).

Syntax:

EXEC KICKS RECEIVE
      [INTO(data-area)]
      [LENGTH(data-area)| FLENGTH(data-area)]
      [MAXLENGTH(data-value) | MAXFLENGTH(data-value)]
      [ASIS] [BUFFER] [CHECK]
END-EXEC

Arguments:

INTO(data-area) - specifies the name of the program variable that will contain the input data retrieved. If omitted a terminal read is still done, and the EIB is updated with the new aid and cursor address, but obviously no other data is made available.

 

LENGTH(data-area) - specifies the name of the program variable (PIC S9(4) COMP or short) that will contain the number of bytes retrieved.

 

FLENGTH(data-area) - specifies the name of the program variable (PIC S9(8) COMP or integer) that will contain the number of bytes retrieved.

 

MAXLENGTH(data-value)

MAXFLENGTH(data-value) - specifies the value or program variable that contains the maximum number of bytes to retrieve. If omitted, but LENGTH or FLENGTH is specified, the input value there is taken as the maximum number of bytes to retrieve. If neither MAXLENGTH/MAXFLENGTH nor LENGTH/FLENGTH is specified then the number of bytes to retrieve is taken to be zero.

 

ASIS - specifies that lower case letters are not be translated to upper case.

 

BUFFER - specifies that the complete 3270 buffer is returned, including the leading aid character and two character cursor address. If not specified these 3 characters are omitted (ie, returned data starts with the 4th character of the input buffer).

 

CHECK - specifies that no data is to be read, rather an indication of whether the terminal has data ready is to be returned. If data is ready EIBAID will be equal to 'R' after the call, otherwise it will be 'N'. The operation also includes a 1/10 second delay. When CHECK is specified all other arguments are ignored.

Exceptional Conditions:

LENGERR - available data exceeds MAXFLENGTH (or FLENGTH, see above. Not reported if INTO not specified.

Notes:

  • RECEIVE INTO is commonly used to retrieve data entered on the same line as the transaction id. One place you can see this is in the KEDF transaction, where it uses this command to see if you are doing a simple KEDF ON or a KEDF OFF before it puts up the full screen interface for a more complex interaction. RECEIVE MAP is much easier to use for other cases, primarily due to the complexity of the tioa's 3270 data structure.

  • LENGTH and MAXLENGTH (for use with S9(4) COMP or SHORT data items) not supported; use FLENGTH and MAXFLENGTH (for use with S9(8) COMP or INTEGER data items) instead.

  • NOTRUNCATE is not supported. Any data read but not returned due to MAXFLENGTH (etal) is lost

  • In CICS ASIS is ineffective on the first RECEIVE of a task (ie, the only RECEIVE of a pseudo conversational task) but in KICKS it works on all RECEIVE's where it is coded.

  • CHECK is a "KICKS only" argument not supported in CICS.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(SRTEXT) for usage examples; also HERC01.KICKSSYS.V1R5M0.COB(KSGMPGM) for use of the CHECK argument.
RECEIVE MAP

Purpose:

The RECEIVE MAP function reads data from a terminal and formats it using BMS map definitions.

Syntax:

EXEC KICKS RECEIVE MAP(name) MAPSET(name)
      [INTO(data-area)]
      [ASIS]
END-EXEC

Arguments:

MAP(name) - the one to seven character name of the bms map to be used to map the input data.

 

MAPSET(name) - the one to seven character name of the bms mapset that contains the map named in MAP(name). This object must be defined in the PPT.

 

INTO(data-area) - specifies the data area that will contain the mapped input data. This is usually the COPY'ed symbolic map generated by the MAPGEN procedure. If INTO is not specified the mapped area is assumed to be the MAP name suffixed by an "I".

 

ASIS - specifies that lower case letters are not to be made upper case.

Exceptional Conditions:

MAPFAIL - The data cannot be formatted

Notes:

  • RECEIVE MAP and SEND MAP can also generate Exceptional Conditions as documented under the LOAD function if the MAPSET is not in the PPT, is disabled, is not in the KIKRPL concatenation, etc.

  • In CICS ASIS is ineffective on the first RECEIVE of a task (ie, the only RECEIVE of a pseudo conversational task) but in KICKS it works on all RECEIVE's where it is coded.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(SRMAP) for usage examples.
RELEASE

Purpose:

The RELEASE function removes a previously LOAD'ed object module from storage.

Syntax:

EXEC KICKS RELEASE PROGRAM(name) END-EXEC

Arguments:

PROGRAM(name) - specifies the one to eight character name of the object module to be loaded. The name must be defined in the PPT.

Exceptional Conditions:

PGMIDERR - The program is not in the PPT
RESETBR

Purpose:

The RESETBR function resets the current position of a browse operation. It is, in effect, the same as an ENDBR for the file followed by a STARTBR with the same (as the RESETBR) arguments.

 

KICKS in fact implements RESETBR exactly as ENDBR followed by STARTBR.

Syntax:

EXEC KICKS RESETBR DATASET(name) | FILE(name)

       RIDFLD(data-area) KEYLENGTH(data-value)
      [GENERIC]] [RBA | RRN] [GTEQ | EQUAL]

      [REQID(data-value)]
END-EXEC

Arguments:

See STARTBR arguments...

Exceptional Conditions:

See ENDBR and STARTBR conditions...

Notes:

  • See the api test members TESTBKS, TESTBKP, TESTBES, TESTBEP and TESTBRR (in the TESTFILE VMARC file) for usage examples.
RETURN

Purpose:

The RETURN function terminates program execution; the invoking program regains control.

Syntax:

EXEC KICKS RETURN

      [TRANSID(name)

      [COMMAREA(data-area) LENGTH(data-value)]]

END-EXEC

Arguments:

TRANSID(name) - specifies the one to four character name of the transaction to be invoked when the terminal operator presses an AID key. The transaction id must be defined in the PCT.

 

COMMAREA(data-area) - specifies a data area that is passed to the next execution of a pseudo-conversational program.

 

LENGTH(data-value) - the length of the data area specified in the COMMAREA argument. If length is omitted  the preprocessor will pass the actual length of the COMMAREA data-area.

Exceptional Conditions:

INVREQ - TRANSID/COMMAREA given when the program returning is not 'at the highest level'. 

Notes:

  • When you LINK to a program it must do a simple RETURN (no TRANSID/COMMAREA). Only a program that ran as a result of a user transaction (or a program that was XCTL'ed to - not LINK'ed to - that program) may (but is not required to) use TRANSID/COMMAREA.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(LINKTST) for usage example.
REWRITE

Purpose:

The REWRITE function updates a record in a file. The record must have been previously read with a READ function with the UPDATE argument. The file may be a VSAM KSDS, ESDS, RRDS, or path.

Syntax:

EXEC KICKS REWRITE DATASET(name) | FILE(name)

       FROM(data-area) LENGTH(data-area)
END-EXEC

Arguments:

FILE(name)

DATASET(name) - synonyms for the one to eight character name of the

dataset. The dataset must be defined in the FCT.

 

FROM(data-area) - specifies the area that contains the record being written.

 

LENGTH(data-area) - PIC S9(4) COMP length of the record. On entry it should be set to the size of record to be written, not the length of the FROM argument (unless they are the same). If length is omitted the record size from the file definition is used.

Exceptional Conditions:

DSIDERR (aka FILENOTFOUND) - The DATASET | FILE is not defined in the FCT.

 

DISABLED - the DATASET | FILE is defined in the FCT, but it is 'disabled', probably because it previously failed to open

 

NOTOPEN - the DATASET | FILE did not open

RESP2 = 60 - open failed due to VSAM open error, causes file to be marked 'disabled'.

RESP2 = 99 - open failed due to enqueue failure, does NOT disable

ILLOGIC - VSAM error. See EIBRCODE bytes 2,3,4,5 for VSAM rplrtncd, rplerrcd, rplfuncd, and rplcmpon

RESP2 = 110 - undifferentiated.

RESP2 = -1  - should not happen

IOERROR - an I/O error occurred.

 

LENGERR - the LENGTH argument specifies a record longer than allowed for the file.

 

DUPKEY - the record contains an alternate key value that already exists or the alternate index does not allow duplicate keys and the alternate index is part of the file's upgrade set.

 

INVREQ - the request is invalid.

RESP2 = 30  - no prior READ with UPDATE.

RESP2 = 23  - the key does not match the old key (or the record is truncated short of the full key).

Notes:

  • A REWRITE may not change the primary key.

  • See the api test members TESTDKS, TESTDES, and TESTDRR (in HERC01.KICKSSYS.V1R5M0.TESTCOB) for usage examples.
SEND TEXT

Purpose:

The SEND TEXT function lets you send text to a terminal. A map is not used, instead BMS just writes the data to the screen as is.

 

NOTE that "TEXT" is optional, that is, you could say "SEND TEXT FROM()..." or just "SEND FROM()...".

Syntax:

EXEC KICKS SEND TEXT
       FROM(data-area)
       LENGTH(data-area) | FLENGTH(data-area)
      [STRFIELD]
      [ERASE] [ALARM] [FREEKB] [ALTERNATE] [DEFAULT]
      [CURSOR(data-value)]

END-EXEC

Arguments:

FROM(data-area) - specifies the data area containing the text to send.

 

LENGTH(data-area)

FLENGTH(data-area) - specifies the length of the FROM data-area. If length is omitted  the preprocessor will pass the actual length of the FROM data-area.

 

STRFIELD - specifies that the FROM field contains a complete 3270 data stream that should be sent exactly as is. If you specify STRFIELD you may not specify any of the following arguments (ERASE, ALARM, FREEKB, ALTERNATE, DEFAULT, or CURSOR) as those choices should be explicit in the FROM field.

 

ERASE - specifies that before writing the data the screen should be erased.

 

ALARM - specifies that the terminal alarm (bell?) should sound.

 

FREEKB - specifies that the terminal keyboard should be unlocked.

 

ALTERNATE - specifies that alternate screen size should be selected.

 

DEFAULT - specifies that default screen size should be selected. Documentation only, sometimes used to make it explicit when also using sends with ALTERNATE.

 

CURSOR(data-value) - specifies where the cursor is to be placed.

Exceptional Conditions:

None

Notes:

  • When using the STRFIELD argument the FROM field may contain a leading escape character (hex 27), but that is not required. It must contain the 3270 write command and the 3270 WCC sequence.

  • When NOT using the STRFIELD argument the characters of the FROM field are written to the screen in groups of 78 characters (for an 80 column screen, corresponding more for larger) per line. For example if you send 100 characters using ERASE, the first 78 characters will be on the first line, the remaining 22 characters on the 2nd line. This is a little different from CICS, which tries to assure 'words' are not broken in the line wrapping.

  • See HERC01.KICKSSYS.V1R5M0.COB(KSSFPGM) for an example of STRFIELD usage.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(SRTEXT) for an example of more common usage without STRFIELD.
SEND MAP

Purpose:

The SEND MAP function sends data to a terminal, mapping it according to the specifications in a BMS map.

Syntax:

EXEC KICKS SEND MAP(name) MAPSET(name)
      [FROM(data-area)]
      [ERASEAUP] [ERASE] [ALARM] [FREEKB] [FRSET]
      [MAPONLY] [DATAONLY] [ALTERNATE] [DEFAULT]
      [CURSOR(data-value)]
END-EXEC

Arguments:

MAP(name) - the one to seven character name of the bms map to be used to map the output data.

 

MAPSET(name) - the one to seven character name of the bms mapset that contains the map named in MAP(name). This object must be defined in the PPT.

 

FROM(data-area) - specifies the name of the program variable that contains the data to be sent. This is usually the COPY'ed symbolic map generated by the MAPGEN procedure. If FROM is not specified the mapped area is assumed to be the MAP name suffixed by an "O".

 

ERASEAUP - specifies that before writing the data all the unprotected fields already on the screen should be erased.

 

FRSET - specifies that the modified data tag (MDT) for each attribute character is reset to zero.

 

MAPONLY - specifies that only constant data from the map is sent; the FROM area is unused.

 

DATAONLY - specifies that the FROM area data is to be sent, but constant data from the map is not sent.

 

ERASE - specifies that before writing the data the screen should be erased.

 

ALARM - specifies that the terminal alarm (bell?) should sound.

 

FREEKB - specifies that the terminal keyboard should be unlocked.

 

ALTERNATE - specifies that alternate screen size should be selected.

 

DEFAULT - specifies that default screen size should be selected. Documentation only, sometimes used to make it explicit when also using sends with ALTERNATE.

 

CURSOR(data-value) - specifies where the cursor is to be placed.

Exceptional Conditions:

MAPFAIL - The data cannot be formatted.

Notes:

  • SEND MAP and RECEIVE MAP can generate Exceptional Conditions as documented under the LOAD function if the MAPSET is not in the PPT, is disabled, is not in the KIKRPL concatenation, etc.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(SRMAP) for usage examples.
SEND CONTROL

Purpose:

The SEND CONTROL function lets you send device control commands to a terminal. No mapped data is sent.

Syntax:

EXEC KICKS SEND CONTROL
      [ERASE] [ALARM] [FREEKB] [ALTERNATE] [DEFAULT]
      [ERASEAUP] [FRSET]
      [CURSOR(data-value)]
END-EXEC

Arguments:

ERASEAUP - specifies that before writing the data all the unprotected fields already on the screen should be erased.

 

FRSET - specifies that the modified data tag (MDT) for each attribute character is reset to zero.

 

ERASE - specifies that before writing the data the screen should be erased.

 

ALARM - specifies that the terminal alarm (bell?) should sound.

 

FREEKB - specifies that the terminal keyboard should be unlocked.

 

ALTERNATE - specifies that alternate screen size should be selected.

 

DEFAULT - specifies that default screen size should be selected. Documentation only, sometimes used to make it explicit when also using sends with ALTERNATE.

 

CURSOR(data-value) - specifies where the cursor is to be placed.

Exceptional Conditions:

 

Notes:

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(SRTEXT) for usage examples.
SIGNOFF

Purpose:

The SIGNOFF function initiates KICKS shutdown.

Syntax:

EXEC KICKS SIGNOFF END-EXEC

Arguments:

None

Exceptional Conditions:

None

Notes:

  • See the KSSFPGM COBOL program for usage examples.
STARTBR

Purpose:

The STARTBR function initiates a browse operation so that records can be retrieved using READNEXT and/or READPREV functions.

Syntax:

EXEC KICKS STARTBR DATASET(name) | FILE(name)

       RIDFLD(data-area) KEYLENGTH(data-value)
      [GENERIC] [RBA | RRN] [GTEQ | EQUAL]

      [REQID(data-value)]
END-EXEC

Arguments:

FILE(name)

DATASET(name) - synonyms for the one to eight character name of the

dataset. The dataset must be defined in the FCT.

 

RIDFLD(data-area) - "key" defining the record where the browse is to begin.

 

KEYLENGTH(data-value) - PIC S9(4) COMP length of RIDFLD argument. If keylength is omitted the key size from the file definition is used.

 

GENERIC - specifies that only part of the key in the RIDFLD argument should be used, as indicated by the KEYLENGTH argument.

 

RRN - specified that the RIDFLD is a relative record number for a VSAM RRDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

 

RBA - specified that the RIDFLD is a relative byte address for a VSAM KSDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

 

EQUAL - specifies that positioning will be established at the record whose key matches the RIDFLD exactly. If no such record exists the NOTFND condition is raised and the browse is not started.

 

GTEQ - specifies that positioning will be established at the first record whose key is greater than or equal to the key specified in the RIDFLD argument. This will always establish positioning in the file unless the specified key is greater than the largest in the file.

 

REQID(data-value) - specifies a PIC S9(4) COMP numeric value that identifies the browse operation. Normally used only when you need more than one browse active at a time. Default is zero.

Exceptional Conditions:

DSIDERR (aka FILENOTFOUND) - The DATASET | FILE is not defined in the FCT.

 

DISABLED - the DATASET | FILE is defined in the FCT, but it is 'disabled', probably because it previously failed to open

 

NOTOPEN - the DATASET | FILE did not open

RESP2 = 60 - open failed due to VSAM open error, causes file to be marked 'disabled'.

RESP2 = 99 - open failed due to enqueue failure, does NOT disable

ILLOGIC - VSAM error. See EIBRCODE bytes 2,3,4,5 for VSAM rplrtncd, rplerrcd, rplfuncd, and rplcmpon

RESP2 = 110 - undifferentiated.

RESP2 = -1  - should not happen

IOERROR - an I/O error occurred.

 

INVREQ - invalid request.

    RESP2 = 25  - GENERIC & KEYLENGTH given,

                  but given KEYLENGTH > real!

    RESP2 = 26  - GENERIC not given, KEYLENGTH given,

                  but KEYLENGTH <> real!

    RESP2 = 33  - REQID already used for active browse

    RESP2 = 42  - GENERIC & KEYLENGTH given, but KEYLENGTH < 0

    RESP2 = 901 - no space for another active REQID

    RESP2 = 902 - can't RBA & RRN both

    RESP2 = 903 - can't RBA for RRDS file

    RESP2 = 904 - can't RRN for non-RRDS file

    RESP2 = 905 - can't RBA for RRDS file

 

NOTFND - The specified record could not be located.

Notes:

A browse operation may be:

  • A direct browse of a key sequenced data set (KSDS) by record key.

  • A direct browse of an entry sequenced data set (ESDS) by relative byte address (RBA).

  • A direct browse of a relative record data set (RRDS) by relative record number (RRN).

  • A browse of a key sequenced data set (KSDS) using an alternate index path.

  • A browse of an entry sequenced data set (ESDS) using an alternate index path. In this case, an ESDS is browsed by key in the same way as a KSDS. Some of the options that are not valid for a direct ESDS browse are valid for an alternate index browse.

  • A browse of a KSDS by RBA.

The options specified on the STARTBR command define the characteristics that apply throughout the subsequent browse operation.

 

Specifically, if GENERIC or GTEQ are specified, they are used not only when determining the starting point of the browse, but also whenever the value of RIDFLD is changed before issuing a READNEXT command.

 

If you specify the RBA option, it applies to every READNEXT or READPREV command in the browse, and causes CICS to return the relative byte address of each retrieved record.

 

None of these options can be changed during a browse, except by means of the RESETBR command.

 

Positioning to read forward from the first record:

  • KSDS - use a key of low-values.

  • ESDS - use an RBA of +0.

  • RRDS - use an RRN of +1.

Positioning to read backward from the last record:

  • KSDS - use a key of high-values.

  • ESDS - use an RBA of high-values.

  • RRDS - use an RRN of high-values.

Reading forward or backward then is just a series of repeated READNEXT or READPREV's.

 

See the api test members TESTBKS, TESTBKP, TESTBES, TESTBEP and TESTBRR (in HERC01.KICKSSYS.V1R5M0.TESTCOB) for usage examples.
SPOOLOPEN OUTPUT

Purpose:

The SPOOLOPEN OUTPUT function opens a file for sysout (or, special case, the internal reader). It can be used to send output to printers or to submit jobs.

Syntax:

EXEC KICKS SPOOLOPEN OUTPUT
      TOKEN(data-area) NODE(data-value) [ CLASS(data-value) ]

      USERID(data-value) | WRITER(data-value)

END-EXEC

Arguments:

TOKEN(data-area) - specifies an 8 character field where KICKS will store a token that must be used in subsequent SPOOLWRITE and SPOOLCLOSE operations for this file.

 

NODE(data-value) - specifies an 8 character value used as a DESTINATION for the sysout.

 

CLASS(data-value) - specifies an 1 character sysout class. Default=A.

 

USERID

WRITER(data-value) - synonyms for an 8 character userid for the sysout. Code this as 'INTRDR  ' if you want to submit jobs instead of sending the output to a printer.

Exceptional Conditions:

NOTOPEN - the open failed

  RESP=19, RESP2=8,  to many sysouts already open

  RESP=19, RESP2=9,  intrdr allocation failed

  RESP=19, RESP2=10, normal allocation failed

  RESP=19, RESP2=11, allocated sysout open failed

Notes:

  • CICS implements the SPOOLxxx functions with a direct interface to the spooler, but KICKS simply uses dynamically allocated sysout's (including, as necessary, INTRDR sysout's).

  • SPOOLOPEN INPUT not supported. This means KICKS can send jobs or printout to JES, but can't retrieve items that are in the JES queues.

  • WRITER, as a synonym for USERID, is KICKS only (CICS doesn't use it).

  • USERID & NODE are both required. Use USERID('*') and NODE('*') for local output.

  • You can have several sysout files open at once (each with their own token).

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(DCPTST) for usage examples.
SPOOLWRITE

Purpose:

The SPOOLWRITE function writes records to a previously opened sysout.

Syntax:

EXEC KICKS SPOOLWRITE
      TOKEN(data-area) FROM(data-area) FLENGTH(data-value)
END-EXEC

Arguments:

TOKEN(data-area) - specifies an 8 character field where KICKS stored a SPOOLOPEN token.

 

FROM(data-area) - a data area containing the record to be written.

 

FLENGTH(data-value) - the length of the data area to be written. If flength is omitted the preprocessor will pass the actual length of the FROM data-area.

Exceptional Conditions:

NOTOPEN - the sysout was not opened.

 

LENGERR - invalid FLENGTH

  RESP=22, RESP2=0,  FLENGTH <0 or >32767

  RESP=22, RESP2<>0, FLENGTH is 'RESP2' characters to big

Notes:

  • SPOOLREAD not supported.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(DCPTST) for usage examples.
SPOOLCLOSE

Purpose:

The SPOOLCLOSE function closes a previously opened sysout file.

Syntax:

EXEC KICKS SPOOLCLOSE TOKEN(data-area) END-EXEC

Arguments:

TOKEN(data-area) - specifies an 8 character field where KICKS stored a SPOOLOPEN token.

Exceptional Conditions:

NOTOPEN - the sysout was not opened.

Notes:

  • Any open sysouts are automatically closed when at the end of a logical unit of work (task end or SYNCPOINT).

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(DCPTST) for usage examples.
SUSPEND

Purpose:

The SUSPEND function returns control to KICKS, ever so briefly. The purpose of doing so it to reassure KICKS that your program is still functioning properly so it doesn't generate an AICA (run away task, aka timeout) abend.

Syntax:

EXEC KICKS SUSPEND END-EXEC

Arguments:

None

Exceptional Conditions:

None
SYNCPOINT

Purpose:

The SYNCPOINT function announces the end of a logical unit of work within a task.

Syntax:

EXEC KICKS SYNCPOINT [ROLLBACK] END-EXEC

Arguments:

ROLLBACK - indicates that file and database changes in the current logical unit of work should not be committed, but instead discarded.

Exceptional Conditions:

None

Notes:

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(DELAYTST) for usage examples

  • Like CICS, no feedback is provided to your application as to the success (or failure) of the COMMIT or ROLLBACK.

  • The current version of KICKS does not itself attempt any action at all for a ROLLBACK request, however

  • a SYNCPOINT exit may be used for additional COMMIT and/or ROLLBACK processing, for example to automate database commits/rollbacks. This exit is also appropriately driven at task end (normal or abend). See HERC01.KICKSSYS.V1R5M0.COB(SYNCXIT) for a sample exit program.
UNLOCK

Purpose:

The UNLOCK function releases a record that was held by a READ with the UPDATE argument.

Syntax:

EXEC KICKS UNLOCK DATASET(name) | FILE(name)  END-EXEC

Arguments:

FILE(name)

DATASET(name) - synonyms for the one to eight character name of the

dataset. The dataset must be defined in the FCT.

Exceptional Conditions:

DSIDERR (aka FILENOTFOUND) - The DATASET | FILE is not defined in the FCT.

 

DISABLED - the DATASET | FILE is defined in the FCT, but it is 'disabled', probably because it previously failed to open

 

NOTOPEN - the DATASET | FILE did not open

RESP2 = 60 - open failed due to VSAM open error, causes file to be marked 'disabled'.

RESP2 = 99 - open failed due to enqueue failure, does NOT disable

ILLOGIC - VSAM error. See EIBRCODE bytes 2,3,4,5 for VSAM rplrtncd, rplerrcd, rplfuncd, and rplcmpon

RESP2 = 110 - undifferentiated.

RESP2 = -1  - should not happen

IOERROR - an I/O error occurred.

Notes:

  • It would seem UNLOCK should report an error when the file was not locked, but it does not...

  • See the api test members TESTDKS, TESTDES, and TESTDRR (in HERC01.KICKSSYS.V1R5M0.TESTCOB) for usage examples..
WRITE DATASET/FILE

Purpose:

The WRITE function writes one record to a file, which can be a VSAM KSDS, ESDS, RRDS, or path.

Syntax:

EXEC KICKS WRITE DATASET(name) | FILE(name)

       FROM(data-area) LENGTH(data-area)

       RIDFLD(data-area) KEYLENGTH(data-area)
      [RBA | RRN]
END-EXEC

Arguments:

FILE(name)

DATASET(name) - synonyms for the one to eight character name of the dataset. The dataset must be defined in the FCT.

 

FROM(data-area) - specifies the area that contains the record being written.

 

LENGTH(data-area) - PIC S9(4) COMP length of the record. On entry it should be set to the size of record to be written, not the length of the FROM argument (unless they are the same). If length is omitted the record size from the file definition is used.

 

RIDFLD(data-area) - "key" defining the record to be written.

 

KEYLENGTH(data-value) - PIC S9(4) COMP length of RIDFLD that is to be used to identify record(s) to be written. If keylength is omitted the key size from the file definition is used.

 

RRN - specified that the RIDFLD is a relative record number for a VSAM RRDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified). Note that the RRN for the 1st record is 1.

 

RBA - specified that the RIDFLD is a relative byte address for a VSAM KSDS, so RIDFLD should be defined as PIC S9(8) COMP and KEYLENGTH will default to 4 (it should not be specified).

Exceptional Conditions:

DSIDERR (aka FILENOTFOUND) - The DATASET | FILE is not defined in the FCT.

 

DISABLED - the DATASET | FILE is defined in the FCT, but it is 'disabled', probably because it previously failed to open

 

NOTOPEN - the DATASET | FILE did not open

RESP2 = 60 - open failed due to VSAM open error, causes file to be marked 'disabled'.

RESP2 = 99 - open failed due to enqueue failure, does NOT disable

ILLOGIC - VSAM error. See EIBRCODE bytes 2,3,4,5 for VSAM rplrtncd, rplerrcd, rplfuncd, and rplcmpon

RESP2 = 110 - undifferentiated.

RESP2 = -1  - should not happen

IOERROR - an I/O error occurred.

 

LENGERR - the LENGTH argument specifies a record longer than allowed for the file.

 

DUPKEY - a record already exists with that key. Can also occur if the record contains an alternate key value that already exists or the alternate index does not allow duplicate keys and the alternate index is part of the file's upgrade set.

 

NOSPACE - there isn't enough space in the file to hold the new record.

 

INVREQ - the request is invalid.

RESP2 = 23  - embedded key does not match RIDFLD.

RESP2 = 26  - not GENERIC and KEYLENGTH <> real key length.

RESP2 = 902 - can't RBA & RRN both, can't EQUAL & GTEQ both

RESP2 = 903 - can't RBA for RRDS.

RESP2 = 904 - can't RRN if not RRDS.

RESP2 = 905 - KEYLENGTH not allowed with ESDS, RRDS.

Notes:

  • A WRITE to a file cancels any pending READ UPDATE's.

  • See the api test members TESTDKS, TESTDES, and TESTDRR (in HERC01.KICKSSYS.V1R5M0.TESTCOB) for usage examples..
WRITE OPERATOR

Purpose:

The WRITE OPERATOR function sends a message to one or more system operator consoles, and, optionally, waits for a reply, and optionally, times out the reply.

Syntax:

EXEC KICKS WRITE OPERATOR
       TEXT(data-area) [TEXTLENGTH(data-value)]
      [ROUTECODES(data-area) [NUMROUTES)data-value)]]
      [ACTION(data-value) | EVENTUAL | IMMEDIATE | CRITICAL]
      [REPLY(data-area) MAXLENGTH(data-value)
       REPLYLENGTH(data-area) [TIMEOUT(data-value)]]
END-EXEC

Arguments

TEXT(data-area) - the message to be sent to the console(s).

 

TEXTLENGTH(data-value) - the length of the message (less than 160). If textlength is omitted the preprocessor will pass the actual length of the TEXT data-area.

 

ROUTCODES(data-area) - a list of 1 byte route codes that indicate to which operator(s) the message should be sent. Each route code is a binary number 1 - 28. The default is 2.

 

NUMROUTES(data-value) - the number of routes in ROUTCODES. 1 - 28. Required if ROUTCODES specified.

 

IMMEDIATE

EVENTUAL

CRITICAL

ACTION(data-value) - The Action code associated with the message. For ACTION the valid values are 2=IMMEDIATE, 3=EVENTUAL, 11=CRITICAL. The default is IMMEDIATE.

 

REPLY(data-area) - The message requires a reply, which will be placed in the data-area given.

 

MAXLENGTH(data-value) - the maximum length of the reply. If maxlength is omitted the preprocessor will pass the actual length of the REPLY data-area.

 

REPLYLENGTH(data-area) - the length of the reply the operator typed.

 

TIMEOUT(data-value) - the number of seconds the operator has to reply before KICKS times out the reply and returns EXPIRED.

Exceptional Conditions:

INVREQ - one of the values ROUTECODES, NUMROUTES or ACTION was invalid.

 

EXPIRED - The reply timeout expired without operator reply.

Notes:

  • A wait for operator reply could be while. so you should consider using SYNCPOINT to release held resources before use WRITE OPERATOR w/REPLY.

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(WTOTST) for usage examples.
WRITEQ TD

Purpose:

The WRITEQ TD function writes a record to a transient data queue (aka destination).

Syntax:

EXEC KICKS WRITEQ TD QUEUE(name)

       FROM(data-area) LENGTH(data-area)
END-EXEC

Arguments:

QUEUE(name) - Specifies the one to four character name of the destination queue to be written.

 

FROM(data-area) - specifies the data area that will contains the record to be written.

 

LENGTH(data-area) - specifies the S9(4) COMP data area that contains the number of characters to write from the FROM data area. If length is omitted the preprocessor will pass the actual length of the FROM data-area.

Exceptional Conditions:

NOTOPEN - the queue is not opened. This is reported only on first access, thereafter DISABLED is reported.

 

DISABLED - the queue is disabled.

 

INVREQ - the queue type is extrapartition and it is opened for input (so it can't be written).

 

QIDERR - the queue isn't defined in the DCT.

 

LENGERR - the length specified is greater than the maximum allowed for this queue.

 

NOSPACE - there is not enough space left in the queue to write the record.

Notes:

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(DCPTST) for usage examples.
WRITEQ TS

Purpose:

The WRITEQ TS function writes a record to the specified temporary storage queue.

Syntax:

EXEC KICKS WRITEQ TS QUEUE(name)

       FROM(data-area) LENGTH(data-area)

      [ITEM(data-value) [REWRITE]]
      [NUMITEMS(data-area)]

      [MAIN | AUXILIARY] NOSUSPEND
END-EXEC

Arguments:

QUEUE(name) or QNAME(name) - Specifies the one to 16 character name of the temporary storage queue to be written.

 

FROM(data-area) - specifies the data area that contains the record to be written.

 

LENGTH(data-area) - specifies the S9(4) COMP data area that contains the number of characters to write from the FROM data area. If length is omitted the preprocessor will pass the actual length of the FROM data-area.

 

NUMITEMS(data-area) - specifies the S9(4) COMP data area that, on return, will contain the total number of records in the specified queue (including the one just written).

 

ITEM(data-value) - specifies, on entry, the S9(4) COMP data area that contains the item number of the queue record to be written (only if REWRITE specified). On return contains the item number written.

 

REWRITE - specifies that the record should be rewritten.

 

MAIN

AUXILIARY - these arguments are accepted as comments only.

 

NOSUSPEND - a required argument indicating immediate return (with RC) if space is not available to write the data.

Exceptional Conditions:

ITEMERR - the item number exists and REWRITE was not given, or, the item number does not exist and REWRITE was given.

 

QIDERR - the queue doesn't exist (for REWRITE only).

 

LENGERR - the length specified is greater than the maximum allowed for this queue.

 

NOSPACE - there is not enough space left in the queue to write the record.

Notes:

  • NOSUSPEND is an optional argument in CICS, but is required in KICKS.
XCTL

Purpose:

The XCTL function terminates the running program and invokes the specified program. Data can be passed to the invoked program.

Syntax:

EXEC KICKS XCTL PROGRAM(name)

      [COMMAREA(data-area) [LENGTH(data-value)]]
END-EXEC

Arguments:

PROGRAM(name) - specifies the one to eight character name of the program to be invoked. The name must be defined in the PPT.

 

COMMAREA(data-area) - specifies a data area that is passed to the invoked program as a communication area. The invoked program access the data via its DFHCOMMAREA field, so it is the same storage in the invoking program and the invoked program, therefore, since the invoking program is going away, this storage better not be inside it!

 

LENGTH(data-value) - the length of the data area specified in the COMMAREA argument. If length is omitted  the preprocessor will pass the actual length of the COMMAREA data-area.

Exceptional Conditions:

PGMIDERR - The program is not in the PPT

 

DISABLED - The PPT entry for the program is disabled (happens for example if the program is not present in the KIKRPL library concatenation).

 

LENGERR - the LENGTH specified is to large.

Notes:

  • Control does not normally return to the invoking program. However, if the XCTL itself fails (a PGMIDERR condition for example) it will.

  • Since the invoking program will go away the COMMAREA it passes to the invoked program better not be in the invoking program's WORKING-STORAGE!! Usually it will be the COMMAREA that was originally passed to the invoking program...

  • See HERC01.KICKSSYS.V1R5M0.TESTCOB(LINKTST) for usage example.

 

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.

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

Nothing special here. Press ENTER to advance to the next source line.

 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

Notice we have skipped the blue lines and are at the IF. Since we know this is the initial invocation of DFXX, we expect that EIBCALEN will be zero. Press ENTER to see confirmation in that the EXEC KICKS will be next.

 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

Here we are at the ABOUT TO EXECUTE COMMAND for the SEND TEXT we saw earlier, but this time the SEND TEXT is shown in-line with the souce. PRESS ENTER to see what happens next.

 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

Two things to note: previously when we looked at an api call we saw both a before (aka ABOUT TO EXECUTE) and an after (aka COMMAND COMPLETE). This time there was no 'after'. The source trace suppresses the 'after' when the result is normal (that is, when EIBRESP=0). The next thing to notice is that quite a few source statements have been bypassed (this being, as line 3 of the screen shows, line 136 of the source, the previous screen showing line 74 or the source). If you were to use the PF7 key to page back on this screen you would see that's due to the preceding lines being part of a large nested IF. Press ENTER to see what happens next.

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.

Since the last KEDF screen was for a RETURN TRANSID it should be no surprise to see the DFXX menu next. At this point please press PF6 to follow the path of the earlier discussion.

 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

Back to the PROCEDURE DIVISION entry for the new task 000C. Press ENTER to see what happens next.

 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

Nothing special here. Press ENTER to advance to the next source line.

 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

Nothing special here either. Since this is NOT the first entry we do not expect EIBCALEN to be zero. Press ENTER to advance.

 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

As expected the SEND TEXT didn't happen, and the program is in the middle of the string of nested IF's checking to see if a PF key was pressed. Notice that the ELSE is in blue, meaning it will not trace and will not support a breakpoint. When the statements that the preprocessor needs to add to cause a line to trace cannot be added without changing the program logic the preprocessor does not add them, so they show up in blue. ELSE is a very common example, but not the only one.

 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

Of course we know we pressed PF6, so it's no suprise the next few screens will display checks for PF keys we did not press. So just press ENTER again to advance.

 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

Just press ENTER again to advance.

 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

Just press ENTER again to advance.

 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

Just press ENTER again to advance.

 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

Finally we get to the IF statement matching what we typed. Press ENTER to advance.

 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

And sure enough the program's about to execute the bad read. Press ENTER to advance.

 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

The last time we saw an api call there was no 'after'. This time there is, because the last response is not zero. Since as you can see neither RESP nor NOHANDLE was coded we know this is going to result in a transaction abend, so press ENTER to see it.

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.

Copyright © Mike Noel, 2008-2014; last updated 3/7/2015