home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / ibm370 / iktker.ins < prev    next >
Text File  |  2020-01-01  |  25KB  |  510 lines
  1. IBM System/370 MVS/TSO Kermit 4.3.n Installation Instructions
  2.                      (1998 February)
  3.  
  4. The following instructions cover the installation of two command
  5. processors under MVS, namely, GUPI and KERMIT.  GUPI could be installed
  6. for its own sake but is included here primarily because it is a tool
  7. needed in installing KERMIT.  Indeed, GUPI is used for installing not
  8. only MVS/TSO Kermit, but also CICS/OS/VS Kermit.
  9.  
  10.                   * * Installation Procedure * *
  11.  
  12. 1) Get the necessary files from the Kermit distribution tape or from
  13.    BITNET KERMSRV or elsewhere into your disk area.  Note that many of
  14.    the files are generic for Kermit-370 and may already be available to
  15.    you from a local CMS site.  As distributed by Columbia, the files are
  16.    named as follows, all with prefix IKT or IK0 (I K Zero):
  17.  
  18.    IKTAUX.CMD  Sample CLIST's PC, KERMAIL, etc.
  19.  * IKTDYN.ASM  Assembler source for DYNALC subroutine
  20.  * IKTGUP.ASM  Assembler source for TSO-specific part of GUPI
  21.  * IKTGUP.HLP  GUPI help file, TSO HELP format
  22.    IKTKER.BWR  A "beware" file, listing known bugs, problems, and fixes
  23.    IKTKER.DOC  TSO Kermit User Guide, plain text
  24.    IKTKER.HLP  Kermit-TSO help file, TSO HELP format
  25.  * IKTKER.INS  Kermit-TSO installation instructions (this file)
  26.    IKTKER.UPD  Updates for TSO version of Kermit-370
  27.  * IKTMAC.ASM  Assembler source for TSO-specific macros
  28.    IKTUTL.ASM  Assembler source for TSO-specific routines
  29.    IK0CMD.ASM  Assembler source for command handler
  30.    IK0COM.ASM  Assembler source for global code
  31.    IK0DEF.ASM  Assembler source for parameter definitions
  32.    IK0DOC.ASM  Assembler source with brief history
  33.  * IK0GUP.ASM  Assembler source for generic update program GUPI
  34.    IK0KAN.ASM  Assembler source for Kanji character translation
  35.  * IK0MAC.ASM  Assembler source for generic Kermit macros
  36.    IK0MAI.ASM  Assembler source for storage initialization
  37.    IK0PRO.ASM  Assembler source for generic routines
  38.  
  39.    The files marked with asterisks are the ones necessary for installing
  40.    GUPI.  Those, along with the rest, are needed for KERMIT.
  41.  
  42.    The following files are not necessary for installation, but may be of
  43.    some interest.
  44.  
  45.    IKCACT.ASM  Assembler source for optional accounting exit routine
  46.    IKTHDR.MSS  Scribe source for producing IKTKER.DOC
  47.    IKTKER.ANN  Text of Kermit-TSO announcement for current version
  48.    IKTKER.LPT  Paged equivalent of IKTKER.DOC
  49.    IKTKER.MSS  Scribe source for TSO part of IKTKER.DOC
  50.    IKTKER.PS   PostScript equivalent of IKTKER.DOC
  51.    IKTMVS.HLP  Description of TSO-specific features
  52.    IK0AAA.HLP  Kermit-370 implementation notes, supported environments
  53.    IK0CON.HLP  Notes on supporting other terminal controllers
  54.    IK0KER.ANN  Text of generic Kermit-370 4.3 announcement
  55.    IK0KER.MSS  Scribe source for generic part of IKTKER.DOC
  56.    IK0KER.UPD  Update history for Kermit-370
  57.    IK0POR.HLP  Notes on porting Kermit-370 to other systems
  58.    IK0VCS.PKT  Czech-language version of Kermit-370 source (updates)
  59.    IK0VDE.PKT  German-language version of Kermit-370 source (updates)
  60.    IK0VER.FOR  Comparison program for generating update decks
  61.    IK0VES.PKT  Spanish-language version of Kermit-370 source (updates)
  62.    IK0VFI.PKT  Finnish-language version of Kermit-370 source (updates)
  63.    IK0VFR.PKT  French-language version of Kermit-370 source (updates)
  64.    IK0VIT.PKT  Italian-language version of Kermit-370 source (updates)
  65.    IK0VNL.PKT  Dutch-language version of Kermit-370 source (updates)
  66.    IK0VPL.PKT  Polish-language version of Kermit-370 source (updates)
  67.    IK0VPT.PKT  Portuguese-language version of Kermit-370 source (updates)
  68.    IK0VRU.PKT  Russian-language version of Kermit-370 source (updates)
  69.  
  70. 2) Allocate datasets to contain the assembled and executable code as
  71.    follows.  The allocation sizes here are based on "typical" disk
  72.    models; each dataset should be roughly 200K in extent.  You may wish
  73.    to specify the primary space parameter so as to match that require-
  74.    ment.  However, if you wish to reuse either dataset for successive
  75.    test versions or new releases, you must be sure to make a generous
  76.    space allocation.  Both libraries may be compressed from time to time
  77.    to make "dead" storage available, but the load library will tend to
  78.    grow as new releases are added.  It is probably most convenient to
  79.    use the following TSO commands to allocate the datasets.  Note:
  80.    throughout these instructions, the block size used for objects is
  81.    1680, the traditional maximum -- feel free to change it to the
  82.    customary value at your site.
  83.  
  84.    ATTR K1OBJ RECFM(FB) LRECL(80) BLKSIZE(1680) DSORG(PO)
  85.    ALLOC DSN(KERMIT.OBJ) USING(K1OBJ) SPACE(20,20) TRACKS DIR(5)
  86.    ATTR K1LOD RECFM(U) BLKSIZE(6144) DSORG(PO)
  87.    ALLOC DSN(KERMIT.LOAD) USING(K1LOD) SPACE(20,20) TRACKS DIR(10)
  88.  
  89.    The corresponding JCL is:
  90.  
  91.    //     EXEC PGM=IEFBR14
  92.    //K1OBJ  DD DCB=(RECFM=FB,LRECL=80,BLKSIZE=1680,DSORG=PO),
  93.    //          DSN=<user>.KERMIT.OBJ,SPACE=(TRK,(20,20,5)),
  94.    //          DISP=(NEW,CATLG),UNIT=whatever
  95.    //K1LOD  DD DCB=(RECFM=U,BLKSIZE=6144,DSORG=PO),
  96.    //          DSN=<user>.KERMIT.LOAD,SPACE=(TRK,(20,20,10)),
  97.    //          DISP=(NEW,CATLG),UNIT=whatever
  98.  
  99. 3) Rename and reformat, if necessary, the source files on disk.  Collect
  100.    all the source files (those with extensions of ".ASM") in your disk
  101.    area with names as shown above, and make sure that all have the same
  102.    block size, record length, and record format.  The initial values for
  103.    these parameters will depend on the way you obtained the files.  They
  104.    need not follow the traditional pattern for assembler sources
  105.    (RECFM=FB,LRECL=80); any format compatible with QSAM is acceptable.
  106.    You will also need IKTKER.UPD, and any local updates or optional
  107.    updates chosen from IKTKER.BWR should also be collected into one or
  108.    more files for application to the source; the JCL given below uses
  109.    the name IKTKER.LCLUPD as an example for such optional updates.  If
  110.    there are multiple update files, they must all have the same DCB
  111.    parameters, though not necessarily the same as the source files.
  112.    In particular, they must not be reformatted to a fixed record length
  113.    unless the short records are extended with blanks in the process.
  114.    These files are all "raw" materials that will be combined to form the
  115.    source actually supplied to the assembler.
  116.  
  117. 4) Copy IKTKER.HLP into the system Help library with a member name of
  118.    KERMIT so that the TSO HELP KERMIT command and Kermit-TSO's built-in
  119.    HELP subcommand can find it.  Similarly, copy IKTGUP.HLP into member
  120.    GUPI.
  121.  
  122.    The most comprehensive documentation is the pair of chapters of the
  123.    Kermit User Guide dealing with TSO, namely, the generic Kermit-370
  124.    chapter and the TSO-specific one.  These two are bundled together in
  125.    IKTKER.DOC and also in IKTKER.PS; the PostScript is suitable only for
  126.    printing, but the DOC file could also be stored wherever you keep
  127.    online documentation files, renamed appropriately.
  128.  
  129. 5) The Generic Update Program for IBM-370 (GUPI) handles standard update
  130.    information in the format found in IKTKER.UPD.  Like Kermit itself,
  131.    GUPI is composed of a generic part and a TSO-specific part.  The
  132.    former consists of IK0GUP.ASM plus parts of IK0MAC.ASM, and the
  133.    latter similarly consists of IKTGUP.ASM plus parts of IKTMAC.ASM.
  134.    Unlike Kermit, GUPI is both a TSO command processor and an ordinary
  135.    batch program.
  136.  
  137.    The following batch job creates the executable program GUPI and uses
  138.    it to apply the available updates to Kermit and then creates the
  139.    executable load module KERMIT.  Although the job is as generic as
  140.    possible, there may be local variations.  You must tailor the job to
  141.    your site by
  142.    (a) supplying an appropriate JOB card (the JOB card should insure, if
  143.        necessary, a region of at least 2560K to allow execution of the
  144.        assembler and GUPI),
  145.    (b) changing the string "<user>" into the top-level qualifier of your
  146.        disk area,
  147.    (c) changing, if necessary, the name of the assembler, perhaps to
  148.        IFOX00, and selecting the right DDNAME for the object output
  149.        (note that MVS/XA and MVS/ESA both generally require that you use
  150.        IEV90 because of petty changes in SYS1.MACLIB, but MVS/SP does
  151.        not ordinarily have IEV90),
  152.    (d) specifying, if necessary, a generous print limit to allow the
  153.        15,000 or more lines generated by the job,
  154.    (e) changing, if necessary, the BLKSIZE of the macro library for GUPI
  155.        (defined by DD statement GUPLIB.SYSUT2) to be as large as that of
  156.        SYS1.MACLIB,
  157.    (f) un-commenting, if necessary, the references to SYS1.AMODGEN and
  158.        SYS1.MODGEN for access to the STATUS and OBTAIN macros in
  159.        assembling GUPI and Kermit,
  160.    (g) un-commenting, if desired, the reference to the optional local
  161.        update data set for input to GUPI (in step KRMUPD) or adding
  162.        any other desired update data sets to the concatenation under
  163.        ddname SYSIN,
  164.    (h) un-commenting, if desired, the references to the optional Kermit
  165.        accounting exit routine KACCT, and
  166.    (i) commenting out, if desired, the reference to IK0KAN.ASM
  167.        (including it adds about 32 Kbytes to the Kermit load module).
  168.  
  169.    An abbreviated form of the job may be run to apply additional updates
  170.    after the initial installation (simply omit job steps CNVASM through
  171.    GUPLNK).  You will also wish to use a new NAME for each new version
  172.    of the load module.
  173.  
  174.    On the other hand, another abbreviated form of the job may be run for
  175.    just the purpose of installing (or reinstalling) GUPI.  For that,
  176.    simply omit all steps after GUPLNK.
  177.  
  178. //JOBLIB   DD DSN=<user>.KERMIT.LOAD,DISP=OLD
  179. //* INPUT:  <user>.IK*.ASM, <user>.IKTKER.UPD
  180. //* OUTPUT: <user>.KERMIT.LOAD, <user>.KERMIT.OBJ  (both pre-allocated)
  181. //*
  182. //KASM   PROC PRM=,USRMAC='SYS1.MACLIB',MEMBER=NULL,
  183. //            USRMAC2='SYS1.MACLIB'
  184. //ASM    EXEC PGM=IEV90,PARM='NORLD,NODECK,OBJECT,&PRM'
  185. //SYSIN    DD DSN=&SOURCE,DISP=(OLD,PASS)
  186. //* SYSGO    DD DDNAME=SYSLIN      (uncomment if assembler wants SYSGO)
  187. //SYSLIB   DD DSN=&USRMAC,DISP=(SHR,PASS)
  188. //         DD DSN=&USRMAC2,DISP=(SHR,PASS)
  189. //         DD DSN=SYS1.MACLIB,DISP=SHR
  190. //SYSLIN   DD DSN=<user>.KERMIT.OBJ(&MEMBER),DISP=(OLD,PASS)
  191. //SYSPRINT DD SYSOUT=*
  192. //SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(5,2))
  193. //SYSUT2   DD UNIT=(SYSDA,SEP=SYSUT1),SPACE=(CYL,(5,2))
  194. //SYSUT3   DD UNIT=(SYSDA,SEP=SYSUT1),SPACE=(CYL,(5,2))
  195. //       PEND
  196. //KLINK  PROC
  197. //LNK    EXEC PGM=IEWL,PARM='REUS,LET'
  198. //SYSLMOD  DD DSN=<user>.KERMIT.LOAD,DISP=OLD
  199. //SYSPRINT DD SYSOUT=*
  200. //SYSUT1   DD UNIT=SYSDA,SPACE=(CYL,(5,2))
  201. //       PEND
  202. //*
  203. //* ---------------- CUT HERE AFTER 1ST SUBMISSION ----------------
  204. //*        Create exit routine for IEBGENER
  205. //CNVASM EXEC KASM
  206. //SYSIN    DD *
  207. UPDCNV0  START
  208.          SAVE  (14,12),,*
  209.          USING UPDCNV0,15
  210.          LM    1,2,0(1)      Get parms
  211.          LH    3,82(2)       LRECL
  212.          LH    4,62(2)       BLKSI
  213.          AR    4,1           End of buffer
  214.          TM    36(2),X'40'   RECFM=V?
  215.          BO    QUIT          Yes, error
  216. CVTLP    CLC   =C'*COPY ',0(1)
  217.          BNE   NOTCOPY
  218.          CLC   5(48,1),6(1)
  219.          BNE   NOTCOPY
  220.          MVC   0(12,1),=C'./ ADD NAME='
  221.          MVC   12(8,1),54(1) Copy name into ADD stmt
  222. NOTCOPY  AR    1,3           Space over record
  223.          CR    1,4
  224.          BL    CVTLP         Finish block
  225.          SR    15,15
  226. QUIT     RETURN (1,12),RC=(15)
  227.          END   UPDCNV0
  228. //SYSLIN   DD DSN=&&UPDC,DISP=(NEW,PASS),UNIT=SYSDA,SPACE=(CYL,(1,1)),
  229. //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=1680)
  230. //*   Link into job library
  231. //CNVLNK EXEC KLINK
  232. //SYSLIN   DD DSN=&&UPDC,DISP=(OLD,DELETE)
  233. //         DD *
  234.          NAME UPDCNV0(R)
  235. //*   Assemble DYNALC
  236. //DYNCPY EXEC PGM=IEBGENER
  237. //SYSIN    DD DUMMY
  238. //SYSPRINT DD DUMMY
  239. //SYSUT1   DD DSN=<user>.IKTDYN.ASM,DISP=SHR
  240. //SYSUT2   DD DSN=&&DYN,DISP=(NEW,PASS),UNIT=SYSDA,SPACE=(CYL,(1,1)),
  241. //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160)
  242. //DYNASM EXEC KASM,SOURCE='&&DYN',MEMBER=DYNALC
  243. //*   Create sequential file for GUPI macro library
  244. //GUPCPY EXEC PGM=IEBGENER
  245. //SYSIN    DD *
  246.      GENERATE
  247.         EXITS DATA=UPDCNV0
  248. //SYSPRINT DD DUMMY
  249. //SYSUT1   DD DSN=<user>.IK0MAC.ASM,DISP=SHR
  250. //         DD DSN=<user>.IKTMAC.ASM,DISP=SHR
  251. //         DD DSN=<user>.IKTGUP.ASM,DISP=SHR
  252. //SYSUT2   DD DSN=&&GUP,DISP=(NEW,PASS),UNIT=SYSDA,SPACE=(CYL,(1,1)),
  253. //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=2400)
  254. //*   Create GUPI macro library
  255. //GUPLIB EXEC PGM=IEBUPDTE,PARM=NEW
  256. //SYSIN    DD DSN=&&GUP,DISP=(OLD,DELETE)
  257. //SYSPRINT DD DUMMY
  258. //SYSUT2   DD DSN=&&GUPMAC,DISP=(NEW,PASS),UNIT=SYSDA,
  259. //            SPACE=(TRK,(1,1,10),RLSE),
  260. //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160)
  261. //*   Assemble and link GUPI
  262. //GUPCPX EXEC PGM=IEBGENER
  263. //SYSIN    DD DUMMY
  264. //SYSPRINT DD DUMMY
  265. //SYSUT1   DD DSN=<user>.IK0GUP.ASM,DISP=SHR
  266. //SYSUT2   DD DSN=&&GUPX,DISP=(NEW,PASS),UNIT=SYSDA,SPACE=(CYL,(1,1)),
  267. //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160)
  268. //GUPASM EXEC KASM,SOURCE='&&GUPX',MEMBER=GUPI,
  269. //            USRMAC='&&GUPMAC'
  270. //*            ,USRMAC2='SYS1.MODGEN'   May be needed for OBTAIN
  271. //GUPLNK EXEC KLINK
  272. //SYSLIN   DD DSN=<user>.KERMIT.OBJ(GUPI),DISP=SHR
  273. //         DD DSN=<user>.KERMIT.OBJ(DYNALC),DISP=SHR
  274. //         DD *
  275.          NAME GUPI(R)
  276. //*   Assemble optional accounting exit
  277. //* ACTASM EXEC KASM,SOURCE='<user>.KACCT.ASM',MEMBER=KACCT
  278. //* ---------------------- END OF CUT ------------------------
  279. //*
  280. //* --------------- STOP HERE IF ONLY INSTALLING GUPI -------------
  281. //*   Create updated Kermit ...
  282. //KRMUPD EXEC PGM=GUPI,REGION=2560K
  283. //SYSIN    DD DSN=<user>.IKTKER.UPD,DISP=SHR
  284. //*        DD DSN=<user>.IKTKER.NUP,DISP=SHR           Optional
  285. //*        DD DSN=<user>.IKTKER.LCLUPD,DISP=SHR        Optional
  286. //SYSPRINT DD SYSOUT=*
  287. //SYSUT1   DD DSN=<user>.IK0DOC.ASM,DISP=SHR
  288. //         DD DSN=<user>.IK0MAC.ASM,DISP=SHR
  289. //         DD DSN=<user>.IKTMAC.ASM,DISP=SHR
  290. //         DD DSN=<user>.IK0DEF.ASM,DISP=SHR
  291. //         DD DSN=<user>.IK0MAI.ASM,DISP=SHR
  292. //         DD DSN=<user>.IK0COM.ASM,DISP=SHR
  293. //         DD DSN=<user>.IK0CMD.ASM,DISP=SHR
  294. //         DD DSN=<user>.IKTUTL.ASM,DISP=SHR
  295. //         DD DSN=<user>.IK0KAN.ASM,DISP=SHR            Optional
  296. //         DD DSN=<user>.IK0PRO.ASM,DISP=SHR
  297. //SYSUT2   DD DSN=&&UPDSRC,DISP=(NEW,PASS),SPACE=(CYL,(2,1)),
  298. //            DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160),UNIT=SYSDA
  299. //*
  300. //KRMASM EXEC KASM,SOURCE='&&UPDSRC',MEMBER=KERMIT,COND=(0,LT,KRMUPD)
  301. //*            ,USRMAC='SYS1.AMODGEN'   May be needed for STATUS
  302. //*            ,USRMAC2='SYS1.MODGEN'   May be needed for OBTAIN
  303. //KRMLNK EXEC KLINK,COND=((0,LT,KRMUPD),(4,LT,KRMASM.ASM))
  304. //SYSLIN   DD DSN=<user>.KERMIT.OBJ(KERMIT),DISP=SHR
  305. //         DD DSN=<user>.KERMIT.OBJ(DYNALC),DISP=SHR
  306. //*        DD DSN=<user>.KERMIT.OBJ(KACCT),DISP=SHR     Optional
  307. //         DD *
  308.         ALIAS KERMIT
  309.          NAME KERM432(R)
  310. //
  311.  
  312.    Note 1: If you prefer, you may elect to keep the source files in a
  313.    PDS.  If so, change the DSN references in the job accordingly.
  314.  
  315.    Note 2: The procedure given above assumes the availability of sources
  316.    contemporaneous with this file, i.e., release 4.3 of Kermit-370.
  317.  
  318.    Note 3: The procedure given above preserves the sequence numbers in
  319.    columns 73-80 of the source files. If you elect to use an editor to
  320.    merge files, be absolutely sure that you don't inadvertently lose the
  321.    original sequence numbers (something editors are prone to do).
  322.  
  323.    Note 4: The resulting load library KERMIT.LOAD must be placed in the
  324.    link list so that the KERMIT load module will be treated as a COMMAND
  325.    PROCESSOR (if not in SYS1.LINKLIST, then either concatenated to the
  326.    STEPLIB for the default LOGON PROC or made known to all potential
  327.    Kermit users, so that they can do the concatenation themselves).  One
  328.    way of testing a newly installed Kermit is to invoke it under TEST
  329.    with the CP option.
  330.  
  331.    Note 5: The suggested scheme of naming Kermit load modules is
  332.    indicated in the above job.  Version 4.3.0 would be named KERM430,
  333.    4.3.1 would be KERM431, and so on.  The latest version would have
  334.    an alias of KERMIT.  If old versions are kept indefinitely, the
  335.    load library will, of course, grow.
  336.  
  337. 6) Install any desired auxilliary commands from IKTAUX.CMD.  These are
  338.    sample CLIST's and may need to be tailored to your site.  The PC
  339.    command, for example, assumes that the TERMINALS macro is defined in
  340.    your PC Kermit as "SERVER,CONNECT".  KERMAIL and KERMPRT must be set
  341.    up according to the local options and facilities for e-mail and
  342.    print, respectively.
  343.  
  344. 7) To run Kermit-TSO, simply type "KERMIT" to the TSO system prompt.
  345.  
  346.                    * * Alternate Languages * *
  347.  
  348. Kermit-370 now can be installed in a variety of languages.  The messages
  349. within Kermit have been gathered into a few places in the code, and they
  350. can all be replaced during installation with those of a chosen language.
  351. The replacements are contained in distribution files with names like
  352. ik0vXX.pkt, where "XX" is the two-letter language code according to ISO
  353. 639.  These files contain the messages in an encoded form using only the
  354. character repertoire of ASCII, so that even the extended characters can
  355. pass successfully through a variety of transmission mechanisms.
  356.  
  357. Here are the instructions for applying the changes:
  358.  
  359. 1. Use Kermit itself to decode the language-specific update file into
  360.    the proper IBM code page.  To do this, start Kermit (4.2.6 or
  361.    higher) and then select the desired code page, e.g.,
  362.  
  363.          SET FILE CHARACTER-SET CP500
  364.  
  365.    Then tell Kermit to use ik0vXX.pkt, via
  366.  
  367.          SIMULATE IK0Vxx.PKT
  368.          RECEIVE
  369.  
  370.    Kermit will then quickly decode and (attempt to) store the file with
  371.    the name ik0vXX.upd.  If you already have a file of that name, the
  372.    FILE COLLISION setting will determine what happens (overwrite the
  373.    original, pick a new name for the new file, or whatever).
  374.  
  375. 2. ik0vXX.upd contains the updates for all four major variants of
  376.    Kermit-370, and you must edit the file to remove the parts that
  377.    are not applicable.  The edited file should be combined with the
  378.    other updates for the current release of the variant you are
  379.    installing.
  380.  
  381. 3. Concatenate the TSO and generic parts of ik0vXX.upd to the normal
  382.    updates in the installation batch job and re-run it.
  383.  
  384.                     * * Accounting Routine * *
  385.  
  386. If you wish to use the optional accounting exit routine with Kermit,
  387. you must create the object for it and load it explicitly with Kermit.
  388. The sample currently available was written for CMS and must be adapted
  389. to run under MVS/TSO.  Any user who does so is urged to contribute the
  390. TSO version for inclusion in the Kermit distribution under the name
  391. IKTACT.ASM.  Even when such a TSO-specific sample is available, you
  392. should examine the source and customize it to your installation's needs
  393. before using it.  The tailored version is assumed to be called KACCT.ASM
  394. in the relevant lines of the batch job above (currently all commented
  395. out).
  396.  
  397.                        * * Configuration * *
  398.  
  399. The IBM mainframe and its communications front end (3705, 7171, etc.)
  400. usually require that parity be used by any asynchronous ASCII device
  401. that wishes to communicate with it.  Exactly which kind of parity is
  402. site-dependent.  At Columbia, the 3705 requires Mark parity, and the
  403. 7171 requires Even parity.  Make sure your users know to use the
  404. appropriate parity setting, as well as any other settings required for
  405. IBM mainframe communication (see p.36-39 of the Kermit book).
  406.  
  407. For linemode transfers, the ASCII/EBCDIC translation in the front end is
  408. a key factor.  Kermit-TSO uses an ASCII/EBCDIC translation table which
  409. conforms to the one given in the IBM System/370 Reference Summary.  If
  410. your site's translation table is incompatible with the one Kermit uses,
  411. then enter the appropriate SET ATOE/ETOA/TATOE/TETOA subcommands in the
  412. system KERMINI file.  As long as the system tables are invertible with
  413. respect to the printable ASCII characters (even if the A-to-E and E-to-A
  414. tables are not the inverses of each other), the SET subcommands can
  415. compensate.  However, if your system's ASCII/EBCDIC tables are not
  416. invertible, Kermit will not and cannot work unless you change your
  417. system's tables.  Refer to the generic Kermit-370 chapter of the User's
  418. Guide for a step-by-step customization procedure (see the section on
  419. translation tables).
  420.  
  421. Kermit may also need to be configured because of a problem with VTAM for
  422. line-mode terminals -- in some versions of VTAM, there is no standard
  423. mode for transmitting the normal packet character SOH (code 1, CTRL-A),
  424. even though Kermit-TSO automatically detects the presence of VTAM and
  425. switches from TTY to VTAMTTY.  A suitable substitute packet character is
  426. HT (code 9, CTRL-I).  Alternatively, installing the VTAM exit routine
  427. IKTWTX1 will give local control over selection of characters to pass
  428. through to the terminal.
  429.  
  430. Kermit-TSO operation is possible for most types of protocol converters;
  431. for best results, the converter should have a transparent mode.  If
  432. possible, be sure the converter is configured so that the graphics or
  433. transparent mode, whatever it is called, is enabled.  See IK0AAA.HLP for
  434. a list of front ends that are known to work and for a collection of
  435. notes and special warnings about some of them.  Some further
  436. installation details follow for specific devices.
  437.  
  438. When TSO Kermit is to be used with a 7171, make sure the 7171 is set up
  439. with its "keyboard lock delay" parameter set to 0.  Otherwise, the
  440. "terminal" will hang whenever TSO Kermit clears the screen.  This
  441. happens consistently when the parameter is set to 10, and not at all
  442. when set to 0.  For numbers in between, the higher the number, the more
  443. it happens.
  444.  
  445. There is another problem in the 7171 that can cause Kermit file
  446. transfers to abort after a flurry of retransmissions if XON/XOFF flow
  447. control is used by the receiving Kermit, or even by hardware in between
  448. the 7171 and the receiver.  To prevent this problem, set the 7171 flags
  449. so that XOFF is not a valid terminator of a transparent read.  See page
  450. 4-20 of "IBM 7171 Reference Manual and Programming Guide" (IBM
  451. publication number GA27-0021).
  452.  
  453. Kermit operation is possible through an IBM 3708 front end in two
  454. different configurations.  In the first, the terminal line must be set
  455. for either "protocol enveloping" or "dynamic" mode, and a session must
  456. be set for line-at-a-time operation for Kermit to work.  Other important
  457. details of the terminal configuration are: (1) the terminal must be
  458. specified as a TWX device, (2) the SSCP format should be set to USSNTO,
  459. (3) the terminal type ID should be set to 05, (4) the line should be set
  460. for 8, or possibly 7, data bits and 1 stop bit, (5) there should be no
  461. "read prompt", and (6) the so-called "alternate" translation table
  462. (number 3) should be selected.  Kermit-TSO may also need to be
  463. configured because some models of the 3708 (or some environments) do not
  464. pass the normal packet character SOH (code 1, CTRL-A).  A suitable
  465. substitute is HT (code 9, CTRL-I).  Alternatively, or additionally, it
  466. may help to set the 3708 "interface type" to 0.  CONTROLLER must be set
  467. to TTY (or VTAMTTY if connected through TSO/VTAM without the IKTWTX1
  468. exit), but those are the defaults.
  469.  
  470. The second possible 3708 configuration is "protocol conversion" mode and
  471. makes use of the FULLSCREEN type in Kermit, which is also suitable for
  472. many other kinds of protocol converter.  The basic setup consists of the
  473. following Kermit subcommands.
  474.  
  475.      .... mainframe .....        ....... PC .........
  476.      SET CONTROLLER FULL         set send start 62
  477.      SET RECEIVE START 62        set receive start 62
  478.      SET SEND START 62           set block b
  479.      SET BLOCK B                 set handshake none
  480.      SET HANDSHAKE 0
  481.  
  482. The 62's (Greater-than sign) may be replaced by some other decimal code
  483. for a printable character.  For best results, choose a character that
  484. seldom appears in the files you will be transferring.  In particular,
  485. avoid the Control, Eighth-bit, and Repeat prefixes.  Packet sizes are
  486. automatically restricted by Kermit-TSO, so you needn't set them unless
  487. conditions require packets shorter than the default (77).  Flow control
  488. may be needed to keep up with the data rate on some equipment.  The
  489. block check type should be set to "B" only if the protocol converter is
  490. overzealous in optimizing the data stream -- there are hazards in using
  491. any type other than "1" because of all the packet echoing.  Refer to
  492. IK0AAA.HLP for such details.  Note that the translation of characters
  493. imposes the same setup requirements on FULLSCREEN mode as on the
  494. traditional TTY or VTAMTTY modes (linemode).  See the DOC.
  495.  
  496. Kermit-TSO supports file transfers through the IBM 3174 AEA with B2 or
  497. higher microcode, but support is restricted to terminals with the ASCII
  498. Graphics capability in three ways that may require compensating
  499. installation:
  500.  
  501. a) The terminal type must be defined in the 3174 to support graphics
  502.    (only the built-in VT241 and Tektronix 4205 types plus suitable
  503.    user-defined terminal types).  IBM's AEA Reference describes how
  504.    to set up terminal tables.
  505.  
  506. b) The line must be defined without a Host Addressable Printer.
  507.  
  508. c) If the 3174 is owned by VTAM, the connection must be made with a
  509.    logmode that allows the Read Partition Query (such as M2SDLCQ).
  510.