home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / ibm370 / ikxker.ins < prev    next >
Text File  |  2020-01-01  |  35KB  |  735 lines
  1. IBM System/370 CICS Kermit 4.3.n installation instructions
  2.                      (1997 September)
  3.  
  4. CICS is commonly run under both MVS and VSE, and CICS Kermit may differ
  5. slightly between the two systems.  Indeed, the installation procedures
  6. differ substantially between the two, but the same basic pattern holds.
  7. In the following procedure, parallel instructions will be given for both
  8. systems wherever the operation differs.  There is, as yet, no procedure
  9. for installation under VM.  Kermit-CICS has been installed and run under
  10. versions 1.6, 1.7, 2.1, 3.1, and 3.3 of CICS; it is not known what
  11. changes, if any, are necessary to run it under other versions.
  12.  
  13.                   * * Installation Procedure * *
  14.  
  15. 1) Allocate disk storage to contain the source and executable code.
  16.  
  17.                         V S E   o n l y
  18.    The procedure described here assumes that two VSE sublibraries will
  19.    be used.  One sublibrary, called the "base" library, will contain
  20.    unmodified Kermit source, as received from Columbia.  The other
  21.    sublibrary, called the "work" library, will contain copies of the
  22.    base library modules to be modified by the LIBR "UPDATE" command.
  23.    Both libraries may be used for other purposes, since the Kermit
  24.    maintenance affects only the named modules.  It is strongly
  25.    recommended that the work library be set up for automatic space reuse
  26.    (the default), as the update process produces interim copies of each
  27.    module, which are successively replaced.
  28.  
  29.    The Kermit update file (IKXKER.UPD) and the VSE update convertor
  30.    (IKXTRN.ASM) can be stored in either of these libraries or in a third
  31.    library; or they can be submitted as SYSIPT data from an external
  32.    system.  The Kermit executable phase itself must also, of course, be
  33.    stored in a library; again, this may be the same as one of the others
  34.    already discussed.  The JCL given below assumes that both IKXTRN.ASM
  35.    and IKXKER.UPD are stored in VSE libraries.
  36.  
  37.                         M V S   o n l y
  38.    The allocation sizes here are based on "typical" disk models; each
  39.    dataset should be roughly 200K in extent.  You may wish the primary
  40.    space parameter to match that size.  However, if you wish to reuse
  41.    either dataset for successive test versions or new releases, you must
  42.    be sure to make a generous space allocation.  Both libraries may be
  43.    compressed from time to time to make "dead" storage available, but
  44.    the load library will tend to grow as new releases are added.  The
  45.    load library must be included in the DFHRPL concatenation, since it
  46.    will contain the Kermit load module.  If you have TSO available, it
  47.    is convenient to use the following commands to allocate the datasets.
  48.    Note: throughout these instructions, the block size used for objects
  49.    is 1680, the traditional maximum -- feel free to change it to the
  50.    customary value at your site.
  51.  
  52.    ATTR K1OBJ RECFM(FB) LRECL(80) BLKSIZE(1680) DSORG(PO)
  53.    ALLOC DSN(KERMIT.CICS.OBJ) USING(K1OBJ) SPACE(20,20) TRACKS DIR(5)
  54.    ATTR K1LOD RECFM(U) BLKSIZE(6144) DSORG(PO)
  55.    ALLOC DSN(KERMIT.CICS.LOAD) USING(K1LOD) SPACE(20,20) TRACKS DIR(10)
  56.  
  57.    The corresponding JCL is:
  58.  
  59.    //     EXEC PGM=IEFBR14
  60.    //K1OBJ  DD DCB=(RECFM=FB,LRECL=80,BLKSIZE=1680,DSORG=PO),
  61.    //          DSN=<user>.KERMIT.CICS.OBJ,SPACE=(TRK,(20,20,5)),
  62.    //          DISP=(NEW,CATLG),UNIT=whatever
  63.    //K1LOD  DD DCB=(RECFM=U,BLKSIZE=6144,DSORG=PO),
  64.    //          DSN=<user>.KERMIT.CICS.LOAD,SPACE=(TRK,(20,20,10)),
  65.    //          DISP=(NEW,CATLG),UNIT=whatever
  66.  
  67. 2) Get the necessary files from the Kermit distribution tape or from
  68.    BITNET KERMSRV or elsewhere into your disk area.  Note that many of
  69.    the files are generic for Kermit-370 and may already be available to
  70.    you.  As distributed by Columbia, the files are named as follows,
  71.    almost all with prefix IKX or IK0 (I K Zero).  Note that nearly all
  72.    of these files have records no longer than 80 bytes.  The one
  73.    exception is IKXKER.HLP, which has 100-byte records.
  74.  
  75.    IKXKER.BWR  A "beware" file, listing known bugs, problems, and fixes
  76.    IKXKER.DOC  CICS Kermit User's Guide, plain text
  77.    IKXKER.HLP  Kermit-CICS online help files
  78.    IKXKER.INS  Kermit-CICS installation instructions (this file)
  79.    IKXKER.UPD  Updates for CICS version of Kermit-370
  80.    IKXMAC.ASM  Assembler source for CICS-specific macros
  81.    IKXUTL.ASM  Assembler source for CICS-specific routines
  82.    IK0CMD.ASM  Assembler source for command handler
  83.    IK0COM.ASM  Assembler source for global code
  84.    IK0DEF.ASM  Assembler source for parameter definitions
  85.    IK0DOC.ASM  Assembler source with brief history
  86.    IK0KAN.ASM  Assembler source for Kanji character translation
  87.    IK0MAC.ASM  Assembler source for generic Kermit macros
  88.    IK0MAI.ASM  Assembler source for storage initialization
  89.    IK0PRO.ASM  Assembler source for generic routines
  90.  
  91.    If you are installing CICS Kermit in CICS/VSE, you will also need the
  92.    following files.
  93.  
  94.                         V S E   o n l y
  95.    IKXTRN.ASM  Assembler source for the update translation utility
  96.  
  97.    If you are installing CICS Kermit in CICS/MVS, you probably already
  98.    have the materials necessary for installing TSO Kermit on your
  99.    system.  If you do not, you will also need the following files.
  100.  
  101.                         M V S   o n l y
  102.    IKTDYN.ASM  Assembler source for DYNALC subroutine
  103.    IKTGUP.ASM  Assembler source for MVS-specific part of GUPI
  104.    IKTGUP.HLP  GUPI help file, TSO HELP format
  105.    IKTKER.INS  Kermit-TSO installation instructions
  106.    IKTMAC.ASM  Assembler source for TSO-specific macros
  107.    IK0GUP.ASM  Assembler source for generic update program GUPI
  108.  
  109.    The following files are not necessary for installation, but may be of
  110.    some interest.
  111.  
  112.    IKCACT.ASM  Assembler source for optional accounting exit routine
  113.    IKXBIM.ASM  I/O "pipe" driver for BIM-EDIT (sample)
  114.    IKXDYN.HLP  Specifications for I/O drivers
  115.    IKXHDR.MSS  Scribe source for producing IKXKER.DOC
  116.    IKXKER.ANN  Text of Kermit-CICS announcement for current version
  117.    IKXKER.LPT  Paged equivalent of IKXKER.DOC
  118.    IKXKER.MSS  Scribe source for CICS part of IKXKER.DOC
  119.    IKXKER.PS   PostScript equivalent of IKXKER.DOC
  120.    IK0AAA.HLP  Kermit-370 implementation notes, supported environments
  121.    IK0CON.HLP  Notes on supporting other terminal controllers
  122.    IK0KER.ANN  Text of generic Kermit-370 4.3 announcement
  123.    IK0KER.MSS  Scribe source for generic part of IKXKER.DOC
  124.    IK0KER.UPD  Update history for Kermit-370
  125.    IK0POR.HLP  Notes on porting Kermit-370 to other systems
  126.    IK0VCS.PKT  Czech-language version of Kermit-370 source (updates)
  127.    IK0VDE.PKT  German-language version of Kermit-370 source (updates)
  128.    IK0VER.FOR  Comparison program for generating update decks
  129.    IK0VES.PKT  Spanish-language version of Kermit-370 source (updates)
  130.    IK0VFI.PKT  Finnish-language version of Kermit-370 source (updates)
  131.    IK0VFR.PKT  French-language version of Kermit-370 source (updates)
  132.    IK0VIT.PKT  Italian-language version of Kermit-370 source (updates)
  133.    IK0VNL.PKT  Dutch-language version of Kermit-370 source (updates)
  134.    IK0VPL.PKT  Polish-language version of Kermit-370 source (updates)
  135.    IK0VPT.PKT  Portuguese-language version of Kermit-370 source (updates)
  136.    IK0VRU.PKT  Russian-language version of Kermit-370 source (updates)
  137.  
  138. 3) Rename and reformat, if necessary, the source files on disk.  Collect
  139.    all the source files (those with extensions of ".ASM") in your disk
  140.    area using names as shown above, and make sure that each one has
  141.    RECFM=FB,LRECL=80, and that all have the same block size.  Under VSE,
  142.    the file extensions for the sources should be changed to ".A".  You
  143.    will also need IKXKER.UPD, and any local updates or optional updates
  144.    chosen from IKXKER.BWR should also be collected into one or more
  145.    files for application to the source; the JCL given below (both for
  146.    VSE and MVS) uses the name IKXKER.LCLUPD as an example for such
  147.    optional updates.  You may have as many separate files of updates
  148.    as you wish.
  149.  
  150. 4) Define a VSAM KSDS in your CICS to hold Help and TAKE files.  It
  151.    should have the following attributes:
  152.  
  153.        DEFINE CLUSTER DATA( KEYS(21 0) RECSZ(80 256) )
  154.  
  155.        DFHFCT TYPE=DATASET,DATASET=KERMFSF,ACCMETH=VSAM,
  156.               RECFORM=(VARIABLE,BLOCKED),SERVREQ=(READ,ADD,DELETE)
  157.  
  158.    Note: in older versions of CICS, the last parameter would be
  159.  
  160.               SERVREQ=(GET,NEWREC,DELETE)
  161.  
  162.    Copy IKXKER.HLP into KERMFSF using VSAM REPRO so that Kermit-CICS's
  163.    built-in HELP subcommand can find it.  This has the side effect of
  164.    initializing the KSDS.
  165.  
  166.    Special note: with version 4.2.4 of Kermit-CICS, the key size grew
  167.    from 17 to 21.  This requires that the KSDS, if already installed,
  168.    be recreated when migrating to 4.2.4.  If the old KSDS contains any
  169.    files other than the Help files, they can be backed up and reinserted
  170.    into the new KSDS by something like the following procedure.
  171.  
  172.    a) Copy the entire KSDS to a sequential file using VSAM REPRO.
  173.  
  174.    b) Remove all the Help files (all lines with 0000 in columns 1-4 and
  175.       the word HELP somewhere within columns 5-12).  If there are no
  176.       lines left, the KSDS contained only the original Help files.
  177.  
  178.    c) Insert four blanks at column 5 in all the remaining lines of the
  179.       sequential file, moving everything over to make room, and save the
  180.       result.
  181.  
  182.    d) Merge the saved file with IKXKER.HLP and sort on the key (columns
  183.       1-21).  Use this sorted file to load the KSDS instead of the
  184.       "vanilla" IKXKER.HLP.
  185.  
  186.    The most comprehensive documentation is the pair of chapters of the
  187.    Kermit User's Guide dealing with CICS, namely, the generic Kermit-370
  188.    chapter and the CICS-specific one.  These two are bundled together in
  189.    IKXKER.DOC and also in IKXKER.PS; the PostScript is suitable only for
  190.    printing, but the DOC file could also be stored wherever you keep
  191.    online documentation files, renamed appropriately.
  192.  
  193. 5) The "true" source for Kermit consists of the concatenation of the
  194.    individual ASM modules plus a number of updates found in IKXKER.UPD.
  195.    The method of applying these updates depends on the operating system.
  196.    Also, it depends on the decision of whether to support Japanese Kanji
  197.    text translation.  IK0KAN.ASM is optional.  Including it adds about
  198.    32 Kbytes to the Kermit program.
  199.  
  200.                         V S E   o n l y
  201.    The translator program IKXTRN converts the update information in
  202.    IKXKER.UPD into directives for the library maintenance utility LIBR
  203.    and submits a batch job to apply the updates.  The following JCL
  204.    assembles, links, and runs IKXTRN for that purpose.  In order to
  205.    avoid making assumptions about the type of scratch disk available,
  206.    IKXTRN and the JCL are set up to punch a cascading series of jobs
  207.    into the POWER internal reader, with input data taken from SYSIPT and
  208.    output written to SYSPCH.  You must tailor the job to your site,
  209.    primarily by filling in the variables denoted in the JCL by lower-
  210.    case words enclosed in angle brackets "<>".  Some of these variables
  211.    are self-explanatory, but others are described in some detail below.
  212.    Note: in the following JCL, the normal system libraries are assumed
  213.    to be universally searchable and are not explicitly mentioned.
  214.  
  215.    <sliname>
  216.        Since some sites may require additional JCL to complete the
  217.        information normally placed in the standard label area, provision
  218.        is made for including local JCL via POWER 'SLI' statements at
  219.        appropriate places in the distributed JCL.  If such supplemental
  220.        JCL is not required, statements with the <sliname> variable may
  221.        be deleted from the JCL.
  222.  
  223.    <class>
  224.        Replace this variable with the designation of the partition you
  225.        want each job to run in.
  226.  
  227.    <lst specs>
  228.        Replace this variable with the POWER LST card information needed
  229.        to route SYSLST output according to local custom.
  230.  
  231.    <lib.sublibn>
  232.        Several versions of this variable occur in the JCL.  When "n" has
  233.        the same value for two different occurrences, both occurrences
  234.        must identify the same sublibrary.  In fact, you may use the same
  235.        sublibrary for more than one "n"; the only distinction that
  236.        absolutely must be kept is between n=0 and n=1.  The following
  237.        values of "n" are defined:
  238.  
  239.        0 - The base library for unmodified Kermit Source.
  240.        1 - The work library for modified Kermit Source.
  241.        2 - The sublibrary where IKXTRN.A is stored.
  242.        3 - The sublibrary where IKXUPD.UPD is stored.
  243.        4 - The sublibrary where the Kermit phase is to be cataloged.
  244.  
  245.    <phasename>
  246.        Replace this variable with the phase name to be given Kermit,
  247.        consistent with local CICS naming conventions.  KERMIT is a
  248.        good choice.
  249.  
  250.    <v.r>
  251.        Replace this with the current CICS release number at your site.
  252.  
  253. * $$ JOB JNM=<jobname>,CLASS=<n>,DISP=D
  254. * $$ LST <lst specs>
  255. * $$ PUN DISP=I,CLASS=<n>
  256. // JOB <jobname> SUBMIT KERMIT UPDATES TO IKXTRN PROGRAM
  257. * $$ SLI <sliname>
  258. // OPTION LINK,NODUMP,DECK
  259. // EXEC ASSEMBLY
  260.    PUNCH '* $$ LST <lst specs>'
  261.    PUNCH '* $$ PUN DISP=I,CLASS=<n>'
  262.    PUNCH '// JOB IKXTRN CONVERT KERMIT UPDATES TO VSE LIBR'
  263.    PUNCH '* $$ SLI <sliname>'
  264.    PUNCH '   LIBDEF SOURCE,SEARCH=<lib.sublib2>'
  265.    PUNCH '// OPTION LINK,NODUMP'
  266.    PUNCH '// EXEC ASSEMBLY,SIZE=256K'
  267.    PUNCH '   COPY IKXTRN'
  268.    PUNCH '/*'
  269.    PUNCH '// EXEC LNKEDT,SIZE=128K'
  270.    PUNCH '// EXEC ,SIZE=128K'
  271.    PUNCH 'BASELIBR=<lib.sublib0>'
  272.    PUNCH 'WORKLIBR=<lib.sublib1>'
  273.    PUNCH 'LOCALLST=<lst specs>'
  274.    PUNCH 'LOCALSLI=<sliname>'   (optional)
  275.    PUNCH '00001000=IK0DOC.A'
  276.    PUNCH '00300000=IK0MAC.A'
  277.    PUNCH '00800000=IKXMAC.A'
  278.    PUNCH '01400000=IK0DEF.A'
  279.    PUNCH '01500000=IK0MAI.A'
  280.    PUNCH '01800000=IK0COM.A'
  281.    PUNCH '03000000=IK0CMD.A'
  282.    PUNCH '05000000=IKXUTL.A'
  283.    PUNCH '07000000=IK0KAN.A'      (optional)
  284.    PUNCH '07500000=IK0PRO.A'
  285.    END
  286. /*
  287. // EXEC LIBR
  288.    ACCESS SUBLIB=<lib.sublib3>
  289.    PUNCH IKXKER.UPD     FORMAT=NOHEADER EOF=NO
  290.    PUNCH IKXKER.LCLUPD  FORMAT=NOHEADER EOF=NO
  291. /*
  292. // EXEC ASSEMBLY
  293.    PUNCH '/*'
  294.    PUNCH '/&&'
  295.    PUNCH '* $$ EOJ'
  296.    END
  297. /*
  298. /&
  299. * $$ EOJ
  300.  
  301.    When the foregoing job has completed successfully, the updated Kermit
  302.    source modules will be found in the <lib.sublib1> sublibrary, where
  303.    they can be kept either until the installation is complete or until
  304.    the next installation.  To assemble and link Kermit, the following
  305.    JCL should be run.  Tailoring is the same as for the update job,
  306.    including the possibility of removing IK0KAN if desired.
  307.  
  308. * $$ JOB JNM=<jobname>,CLASS=<n>,DISP=D
  309. * $$ LST <lst specs>
  310. * $$ PUN DISP=I,CLASS=<n>
  311. // JOB LEVEL1 KERMIT TRANSLATE/ASSEMBLE/LINK
  312. * $$ SLI <sliname>
  313. // OPTION DECK
  314. // EXEC ASSEMBLY
  315.  PUNCH '* $$ LST <lst specs>'
  316.  PUNCH '* $$ PUN DISP=I,CLASS=<n>'
  317.  PUNCH '// JOB LEVEL2 KERMIT TRANSLATE/ASSEMBLE/LINK'
  318.  PUNCH '* $$ SLI <sliname>'
  319.  PUNCH '// OPTION DECK'
  320.  PUNCH '// EXEC ASSEMBLY'
  321.  PUNCH ' PUNCH ''* $$ LST <lst specs>'''
  322.  PUNCH ' PUNCH ''// JOB LEVEL3 KERMIT TRANSLATE/ASSEMBLE/LINK'''
  323.  PUNCH ' PUNCH ''* $$ SLI <sliname>'''
  324.  PUNCH ' PUNCH ''// LIBDEF *,SEARCH=<lib.sublib1>'''
  325.  PUNCH ' PUNCH ''// OPTION CATAL,SYSPARM=''''<v.r>'''''''
  326.  PUNCH ' PUNCH ''   PHASE <phasename>,*'''
  327.  PUNCH ' PUNCH ''   INCLUDE DFHEAI'''
  328.  PUNCH ' PUNCH ''// EXEC ASSEMBLY'''
  329.  PUNCH ' END'
  330.  PUNCH '/*'
  331.  PUNCH '// EXEC DFHEAP1$,SIZE=384K'
  332.  PUNCH '* ASM XOPTS(NOPROLOG,NOEPILOG)'
  333.  END
  334. /*
  335. // EXEC LIBR
  336.    ACCESS SUBLIB=<lib.sublib1>
  337.    PUNCH IK0DOC.A FORMAT=NOHEADER EOF=NO
  338.    PUNCH IK0MAC.A FORMAT=NOHEADER EOF=NO
  339.    PUNCH IKXMAC.A FORMAT=NOHEADER EOF=NO
  340.    PUNCH IK0DEF.A FORMAT=NOHEADER EOF=NO
  341.    PUNCH IK0MAI.A FORMAT=NOHEADER EOF=NO
  342.    PUNCH IK0COM.A FORMAT=NOHEADER EOF=NO
  343.    PUNCH IK0CMD.A FORMAT=NOHEADER EOF=NO
  344.    PUNCH IKXUTL.A FORMAT=NOHEADER EOF=NO
  345.    PUNCH IK0KAN.A FORMAT=NOHEADER EOF=NO
  346.    PUNCH IK0PRO.A FORMAT=NOHEADER EOF=NO
  347. /*
  348. // EXEC ASSEMBLY
  349.  PUNCH '/*'
  350.  PUNCH '// EXEC ASSEMBLY'
  351.  PUNCH ' PUNCH ''/*'''
  352.  PUNCH ' PUNCH ''// LIBDEF *,CATALOG=<lib.sublib4>'''
  353.  PUNCH ' PUNCH ''// EXEC LNKEDT,SIZE=128K'''
  354.  PUNCH ' PUNCH ''/*'''
  355.  PUNCH ' PUNCH ''/&&&&'''
  356.  PUNCH ' PUNCH ''* $$ EOJ'''
  357.  PUNCH ' END'
  358.  PUNCH '/*'
  359.  PUNCH '/&&'
  360.  PUNCH '* $$ EOJ'
  361.  END
  362. /*
  363. /&
  364. * $$ EOJ
  365.  
  366.                         M V S   o n l y
  367.    The Generic Update Program for IBM-370 (GUPI) handles standard update
  368.    information in the format found in IKXKER.UPD.  Like Kermit itself,
  369.    GUPI is composed of a generic part and a system-specific part.  The
  370.    former consists of IK0GUP.ASM plus parts of IK0MAC.ASM.  There is,
  371.    however, no CICS version of GUPI, and if your CICS runs under MVS,
  372.    you must use the MVS (TSO) GUPI.  See the instructions in IKTKER.INS
  373.    for creating MVS GUPI if it has not already been installed in
  374.    connection with TSO Kermit.  The MVS- and TSO-specific parts of GUPI
  375.    consist of IKTGUP.ASM plus some macros from IKTMAC.ASM.
  376.  
  377.    The following batch job uses GUPI to apply the available updates to
  378.    Kermit and then creates the executable load module KERMIT.  Although
  379.    the job is as generic as possible, there may be local variations.
  380.    You must tailor the job to your site by
  381.    (a) supplying an appropriate JOB card (the JOB card should insure, if
  382.        necessary, a region of at least 2M to allow execution of the
  383.        assembler and GUPI),
  384.    (b) changing the string "<user>" into the top-level qualifier of your
  385.        disk area and "<prefix>" into the top level for CICS,
  386.    (c) selecting the proper CICS macro library name and inserting the
  387.        current CICS release number in the definition of proc KXASM,
  388.    (d) changing the string "<CICSlib>" into the name of the library
  389.        containing the CICS command-level translator (or removing the
  390.        STEPLIB from the KXASM.TRN step),
  391.    (e) changing, if necessary, the name of the assembler, perhaps to
  392.        IFOX00, and selecting the right DDNAME for the object output,
  393.    (f) specifying, if necessary, a generous print limit to allow the
  394.        13,000 or more lines generated by the job,
  395.    (g) un-commenting, if desired, the reference to the optional local
  396.        update data set for input to GUPI (in step KRMUPD) or adding
  397.        any other desired update data sets to the concatenation under
  398.        ddname SYSIN,
  399.    (h) un-commenting, if desired, the references to the optional Kermit
  400.        accounting exit routine KACCT,
  401.    (i) commenting out, if desired, the reference to IK0KAN.ASM,
  402.    (j) selecting a name for the Kermit program and modifying the NAME
  403.        statement, if necessary, in the last step,
  404.    (k) choosing the proper block size for SYSLIN on the KRMLNK step, if
  405.        necessary, to be as large as that of the Kermit object library,
  406.    (l) possibly adding the SP option to step KXASM.TRN for CICS 4.1
  407.        and above.
  408.  
  409. //JOBLIB   DD DSN=<user>.KERMIT.LOAD,DISP=SHR
  410. //* INPUT:  <user>.IK*.ASM, <user>.IKXKER.UPD, <user>.KERMIT.LOAD
  411. //* OUTPUT: <user>.KERMIT.CICS.LOAD, <user>.KERMIT.CICS.OBJ
  412. //************************
  413. //* Note: CICSREL must be updated appropriately, e.g., 1.7, 2.1, etc
  414. //KXASM  PROC PRM=,MEMBER=NULL,CICSREL='v.r'
  415. //TRN    EXEC PGM=DFHEAP1$,REGION=1M,PARM='NOPROLOG,NOEPILOG'
  416. //STEPLIB  DD DSN=<CICSlib>,DISP=SHR
  417. //SYSIN    DD DSN=&SOURCE,DISP=(OLD,PASS)
  418. //SYSPRINT DD SYSOUT=*
  419. //SYSPUNCH DD DSN=&SYSCIN,DISP=(NEW,PASS),UNIT=SYSDA,
  420. //            SPACE=(TRK,(30,30)),DCB=BLKSIZE=6160
  421. //ASM    EXEC PGM=IEV90,REGION=1M,
  422. //            PARM='RENT,NODECK,OBJECT,SYSPARM(&CICSREL),&PRM'
  423. //SYSIN    DD DSN=&SYSCIN,DISP=(OLD,DELETE)
  424. //SYSLIB   DD DSN=<prefix>.CICS.MACLIB,DISP=SHR
  425. //SYSLIN   DD DSN=<user>.KERMIT.CICS.OBJ(&MEMBER),DISP=(OLD,PASS)
  426. //SYSPRINT DD SYSOUT=*
  427. //SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(2,2))
  428. //       PEND
  429. //************************
  430. //KXLINK PROC
  431. //LNK    EXEC PGM=IEWL,REGION=1M,PARM='REUS,LET'
  432. //SYSLIB   DD DSN=<prefix>.CICS.LOADLIB,DISP=SHR
  433. //SYSLMOD  DD DSN=<user>.KERMIT.CICS.LOAD,DISP=SHR
  434. //SYSPRINT DD SYSOUT=*
  435. //SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(5,2))
  436. //       PEND
  437. //************************
  438. //*   Create updated Kermit ...
  439. //KRMUPD EXEC PGM=GUPI,REGION=2M
  440. //SYSIN    DD DSN=<user>.IKXKER.UPD,DISP=SHR
  441. //*        DD DSN=<user>.IKXKER.LCLUPD,DISP=SHR  Optional
  442. //SYSPRINT DD SYSOUT=*
  443. //SYSUT1   DD DSN=<user>.IK0DOC.ASM,DISP=SHR
  444. //         DD DSN=<user>.IK0MAC.ASM,DISP=SHR
  445. //         DD DSN=<user>.IKXMAC.ASM,DISP=SHR
  446. //         DD DSN=<user>.IK0DEF.ASM,DISP=SHR
  447. //         DD DSN=<user>.IK0MAI.ASM,DISP=SHR
  448. //         DD DSN=<user>.IK0COM.ASM,DISP=SHR
  449. //         DD DSN=<user>.IK0CMD.ASM,DISP=SHR
  450. //         DD DSN=<user>.IKXUTL.ASM,DISP=SHR
  451. //         DD DSN=<user>.IK0KAN.ASM,DISP=SHR        (optional)
  452. //         DD DSN=<user>.IK0PRO.ASM,DISP=SHR
  453. //SYSUT2   DD DSN=&&UPDSRC,DISP=(NEW,PASS),SPACE=(CYL,(1,1)),
  454. //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160),UNIT=SYSDA
  455. //*
  456. //* KACASM EXEC KXASM,SOURCE='<user>.KACCT.ASM',MEMBER=KACCT
  457. //KRMASM EXEC KXASM,SOURCE='&&UPDSRC',MEMBER=KERMIT,COND=(0,LT,KRMUPD)
  458. //KRMLNK EXEC KXLINK,COND=((0,LT,KRMUPD),(4,LT,KRMASM.ASM))
  459. //SYSLIN   DD DSN=<prefix>.CICS.MACLIB(DFHEILIA),DISP=SHR
  460. //*            DCB=BLKSIZE=1680              In case BLKSIZE is smaller
  461. //         DD DSN=<user>.KERMIT.CICS.OBJ(KERMIT),DISP=SHR
  462. //*         DD DSN=<user>.KERMIT.CICS.OBJ(KACCT),DISP=SHR  Optional
  463. //         DD *
  464.          NAME KERMIT(R)
  465. //
  466.  
  467.    Note 1: If you prefer, you may elect to keep the source files in a
  468.    PDS.  If so, be sure to use RECFM=FB,LRECL=80.  Also change the DSN
  469.    references in the preceding job accordingly.
  470.  
  471.    Note 2: The procedure given above assumes the availability of sources
  472.    contemporaneous with this file, i.e., release 4.3 of Kermit-370.
  473.  
  474.    Note 3: The procedure given above preserves the sequence numbers in
  475.    columns 73-80 of the source files.  If you elect to use an editor to
  476.    merge files, be absolutely sure that you don't inadvertently lose the
  477.    original sequence numbers (something editors are prone to do).
  478.  
  479. 6) You must add Kermit to the PPT and to the PCT to allow Kermit to be
  480.    run as a transaction under CICS.  Here are suggested entries.  The
  481.    program name may be something other than KERMIT, but it must agree
  482.    with the name used in the installation job above.
  483.  
  484.          DFHPPT TYPE=ENTRY,PROGRAM=KERMIT,PGMLANG=ASSEMBLER
  485.          DFHPCT TYPE=ENTRY,PROGRAM=KERMIT,TRANSID=KERM,DUMP=NO
  486.  
  487. 7) If you plan to have a global Kermit initialization file (common to
  488.    all users), you must define an extra-partition input TD queue called
  489.    KSYS to contain the initialization subcommands.  The necessary DCT
  490.    entry should have a definition something like this:
  491.  
  492.          DFHDCT TYPE=SDSCI,DSCNAME=KSYSNIT,TYPEFLE=INPUT,
  493.                RECFORM=VARBLK,RECSIZE=84,BLKSIZE=nnnn
  494.          DFHDCT TYPE=EXTRA,DESTID=KSYS,DSCNAME=KSYSNIT
  495.  
  496.    where "nnnn" is any suitable block size.  The DSCNAME value refers to
  497.    the DOS/VSE DLBL name or the MVS DD name that defines the data set;
  498.    it may be any suitable value, as long as both DFHDCT entries match.
  499.    Be sure the data set actually exists, even if it contains no more
  500.    than a comment line, such as:
  501.  
  502.       * CICS Kermit global initialization file.
  503.  
  504.    You may add Kermit subcommands to the file as needed.
  505.  
  506. 8) To run Kermit-CICS, simply type "KERMIT" or "KERM" to CICS.  Also,
  507.    Kermit may be executed by other programs non-interactively.
  508.  
  509.                      * * Alternate Languages * *
  510.  
  511. Kermit-370 now can be installed in a variety of languages.  The messages
  512. within Kermit have been gathered into a few places in the code, and they
  513. can all be replaced during installation with those of a chosen language.
  514. The replacements are contained in distribution files with names like
  515. ik0vXX.pkt, where "XX" is the two-letter language code according to ISO
  516. 639.  These files contain the messages in an encoded form using only the
  517. character repertoire of ASCII, so that even the extended characters can
  518. pass successfully through a variety of transmission mechanisms.
  519.  
  520. Here are the instructions for applying the changes:
  521.  
  522. 1. Use Kermit itself to decode the language-specific update file into
  523.    the proper IBM code page.  To do this, start Kermit (4.2.6 or
  524.    higher) and then select the desired code page, e.g.,
  525.  
  526.          SET FILE CHARACTER-SET CP500
  527.  
  528.    Then tell Kermit to use ik0vXX.pkt, via
  529.  
  530.          SIMULATE IK0Vxx.PKT
  531.          RECEIVE
  532.  
  533.    Kermit will then quickly decode and (attempt to) store the file with
  534.    the name ik0vXX.upd.  If you already have a file of that name, the
  535.    FILE COLLISION setting will determine what happens (overwrite the
  536.    original, pick a new name for the new file, or whatever).
  537.  
  538. 2. ik0vXX.upd contains the updates for all four major variants of
  539.    Kermit-370, and you must edit the file to remove the parts that
  540.    are not needed.  The edited file should be combined with the
  541.    other updates and applied after the official updates for the
  542.    current release of the variant you are installing.
  543.  
  544. 3. Concatenate the CICS and generic parts of ik0vXX.upd to the normal
  545.    updates and re-install.
  546.  
  547.                        * * Data Security * *
  548.  
  549. If you wish to use the optional exits for data security, you must
  550. first code the routine(s) according to the needs at your site and then
  551. create the object(s) and link explicitly with Kermit.  There are three
  552. separate exit routines that may be included, all with the same Type-I
  553. OS linkage conventions:
  554.  
  555.    R13 -> 18-word save area,
  556.    R14 -> return location,
  557.    R15 -> called entry point,
  558.    R1 -> parameter list.
  559.  
  560. In each case, the exit routine is called immediately before Kermit is to
  561. perform some possibly forbidden task, and the return code (in R15) tells
  562. Kermit whether to proceed.  A zero value indicates permission, and any
  563. non-zero value forbids the task.  If a given routine is not linked with
  564. Kermit, the effect is the same as if the return code were always zero.
  565. The three exit routines are summarized below.
  566.  
  567.   Exit    Parameter   Explanation
  568.   ------  ----------- -------------------------------------------------
  569.  
  570.   KVALID  FAB         FABFNAM has the file name, FABFLGS the type of
  571.                       file, and FABCOMM the operation (See FABD macro).
  572.  
  573.      Possible operations are CWD, DELETE, OPEN I, OPEN O, and TEST.
  574.      KVALID must decide whether the specified access is allowed.
  575.      Note: the parameter list consists of the FAB itself, rather than
  576.      a pointer to it.
  577.  
  578.   KHIDE  ->descriptor TSUTE or DCT or KFSBLK for a queue/file
  579.          ->FABFLGS    flags indicating the type of data object
  580.  
  581.      KHIDE must decide whether the name of the object in question may
  582.      be revealed to the user.  This exit routine is invoked during
  583.      execution of the DIR subcomand with any wildcard specification.
  584.      A non-zero return code indicates that the very existence of the
  585.      file is secret.  However, if the user supplies the exact name,
  586.      KHIDE is not called, and DIR will supply the associated
  587.      information.
  588.  
  589.   KHOST  ->pgm name   8-byte string (name of program to be invoked)
  590.          ->command    string to be passed to the program in COMMAREA
  591.          ->length     (fullword) length of command string in bytes
  592.  
  593.      KHOST must decide whether the named program may be invoked with
  594.      the given string.
  595.  
  596.                       * * Userid Routine * *
  597.  
  598. There is a fourth optional exit routine which may be used to set the
  599. userid for the purposes of selecting the default directory for I/O to
  600. filetype "TAKE".  To use this exit routine, you must set the global
  601. symbol &USER to the value 'OTHER' in macro SSYMS (see IKXKER.BWR for
  602. the update to accomplish that).
  603.  
  604.   Exit    Parameter   Explanation
  605.   ------  ----------- -------------------------------------------------
  606.  
  607.   KUSER   KUSERID     KUSERID is a eight-character string to be filled
  608.                       with the default file directory name.
  609.  
  610.      KUSER must fill the string (and pad with blanks, if necessary).
  611.      There is no provision for any error conditions.  KUSER will be
  612.      called only once at the beginning of execution.  In addition to
  613.      the explicit parameter block (the four-byte string), there is an
  614.      implicit passing of the command-level data storage area via R11.
  615.  
  616.      Note: the userid must not begin with either an apostrophe or an
  617.      asterisk.
  618.  
  619.                     * * Accounting Routine * *
  620.  
  621. If you wish to use the optional accounting exit routine with Kermit,
  622. you must create the object for it and link it explicitly with Kermit.
  623. The sample currently available was written for CMS and must be adapted
  624. to run under CICS.  Any user who does so is urged to contribute the
  625. CICS version for inclusion in the Kermit distribution under the name
  626. IKXACT.ASM.  Even when such a CICS-specific sample is available, you
  627. should examine the source and customize it to your installation's needs
  628. before using it.  The tailored version is assumed to be called KACCT.ASM
  629. in the relevant lines of MVS JCL above (currently all commented out).
  630.  
  631.                        * * Configuration * *
  632.  
  633. The IBM mainframe and its communications front end (3705, 7171, etc.)
  634. usually require that parity be used by any asynchronous ASCII device
  635. that wishes to communicate with it.  Exactly which kind of parity is
  636. site-dependent.  At Columbia, the 3705 requires Mark parity, and the
  637. 7171 requires Even parity.  Make sure your users know to use the
  638. appropriate parity setting, as well as any other settings required for
  639. IBM mainframe communication (see p.36-39 of the Kermit book).
  640.  
  641. For linemode transfers, the ASCII/EBCDIC translation in the front end is
  642. a key factor.  Kermit-CICS uses an ASCII/EBCDIC translation table which
  643. conforms to the one given in the IBM System/370 Reference Summary.  If
  644. your site's translation table is incompatible with the one Kermit uses,
  645. then enter the appropriate SET ATOE/ETOA/TATOE/TETOA subcommands in the
  646. system KERMINI file.  As long as the system tables are invertible with
  647. respect to the printable ASCII characters (even if the A-to-E and E-to-A
  648. tables are not the inverses of each other), the SET subcommands can
  649. compensate.  However, if your system's ASCII/EBCDIC tables are not
  650. invertible, Kermit will not and cannot work unless you change your
  651. system's tables.  Refer to the generic Kermit-370 chapter of the User's
  652. Guide for a step-by-step customization procedure (see the section on
  653. translation tables).
  654.  
  655. Kermit-CICS operation is possible for many types of protocol converters;
  656. it requires only that the converter have some kind of transparent mode.
  657. Be sure the converter is configured so that the graphics or transparent
  658. mode, whatever it is called, is enabled.  See IK0AAA.HLP for a list of
  659. front ends that are known to work and for a collection of notes and
  660. special warnings about some of them.  Some further installation details
  661. follow for specific devices.
  662.  
  663. When CICS Kermit is to be used with a 7171, make sure the 7171 is set up
  664. with its "keyboard lock delay" parameter set to 0.  Otherwise, the
  665. "terminal" will hang whenever CICS Kermit clears the screen.  This
  666. happens consistently when the parameter is set to 10, and not at all
  667. when set to 0.  For numbers in between, the higher the number, the more
  668. it happens.
  669.  
  670. There is another problem in the 7171 that can cause Kermit file
  671. transfers to abort after a flurry of retransmissions if XON/XOFF flow
  672. control is used by the receiving Kermit, or even by hardware in between
  673. the 7171 and the receiver.  To prevent this problem, set the 7171 flags
  674. so that XOFF is not a valid terminator of a transparent read.  See page
  675. 4-20 of "IBM 7171 Reference Manual and Programming Guide" (IBM
  676. publication number GA27-0021).
  677.  
  678. Kermit operation is possible through an IBM 3708 front end in two
  679. different configurations.  In the first, the terminal line must be set
  680. for either "protocol enveloping" or "dynamic" mode, and a session must
  681. be set for line-at-a-time operation for Kermit to work.  Other important
  682. details of the terminal configuration are: (1) the terminal must be
  683. specified as a TWX device, (2) the SSCP format should be set to USSNTO,
  684. (3) the terminal type ID should be set to 05, (4) the line should be set
  685. for 8, or possibly 7, data bits and 1 stop bit, (5) there should be no
  686. "read prompt", and (6) the so-called "alternate" translation table
  687. (number 3) should be selected.  Kermit-CICS may also need to be
  688. configured because some models of the 3708 (or some environments) do not
  689. pass the normal packet character SOH (code 1, CTRL-A).  A suitable
  690. substitute is HT (code 9, CTRL-I).  Alternatively, or additionally, it
  691. may help to set the 3708 "interface type" to 0.
  692.  
  693. The second possible 3708 configuration is "protocol conversion" mode and
  694. makes use of the FULLSCREEN type in Kermit, which is also suitable for
  695. many other kinds of protocol converter.  The basic setup consists of the
  696. following Kermit subcommands.
  697.  
  698.      .... mainframe .....        ....... PC .........
  699.      SET CONTROLLER FULL         set send start 62
  700.      SET RECEIVE START 62        set receive start 62
  701.      SET SEND START 62           set block b
  702.      SET BLOCK B                 set handshake none
  703.      SET HANDSHAKE 0
  704.  
  705. The 62's (Greater-than sign) may be replaced by some other decimal code
  706. for a printable character.  For best results, choose a character that
  707. seldom appears in the files you will be transferring.  In particular,
  708. avoid the Control, Eighth-bit, and Repeat prefixes.  Packet sizes are
  709. automatically restricted by Kermit-CICS, so you needn't set them unless
  710. conditions require packets shorter than the default (77).  Flow control
  711. may be needed to keep up with the data rate on some equipment.  The
  712. block check type should be set to "B" only if the protocol converter is
  713. overzealous in optimizing the data stream -- there are hazards in using
  714. any type other than "1" because of all the packet echoing.  Refer to
  715. IK0AAA.HLP for such details.  Note that the translation of characters
  716. imposes the same setup requirements on FULLSCREEN mode as on the
  717. traditional TTY mode (linemode).  See the DOC.
  718.  
  719. Kermit-CICS supports file transfers through the IBM 3174 AEA with B2 or
  720. higher microcode, but support is restricted to terminals with the ASCII
  721. Graphics capability in three ways that may require compensating
  722. installation:
  723.  
  724. a) The terminal type must be defined in the 3174 to support graphics
  725.    (only the built-in VT241 and Tektronix 4205 types plus suitable
  726.    user-defined terminal types).  IBM's AEA Reference describes how
  727.    to set up terminal tables.
  728.  
  729. b) The line must be defined without a Host Addressable Printer.  This
  730.    restriction may not apply if the AEA microcode is at level B4.0 or
  731.    higher.
  732.  
  733. c) If the 3174 is owned by VTAM, the connection must be made with a
  734.    logmode that allows the Read Partition Query (such as M2SDLCQ).
  735.