Add README.md
[pdp8.git] / sw / kermit / k12 / k12mit.dsk
CommitLineData
81e70d48
PH
1 KERMIT-12 Release Disk Information File a/o 28-Oct-1991.
2
3 Description of files on RT-11 format double-density (RX02) diskettes.
4
5Diskette #1 Source Files
6
7 Name Size Block Date
8K12MIT.PAL 453 14 6-Sep-90
9K12PCH.PAL 50 467 6-Sep-90
10K12ENC.PAL 59 517 30-Aug-90
11K12DEC.PAL 60 576 30-Aug-90
12K12PRM.PAL 3 636 6-Sep-90
13K12CLR.PAL 2 639 30-Aug-90
14K12ENB.PAL 47 641 1-Oct-91
15K12DEB.PAL 45 688 22-Oct-91
16K12IPL.PAL 19 733 6-Oct-91
17K12IPG.PAL 23 752 8-Oct-91
18<Unused> 213 775
19
20 10 files in 761 blocks, 213 free blocks.
21
22Diskette #2 Documentation and Support Files
23
24 Name Size Block Date
25K12MIT.ANN 41 14 21-Oct-91
26K12MIT.UPD 23 55 21-Oct-91
27K12MIT.DOC 135 78 6-Sep-90
28K12MIT.NOT 33 213 18-Oct-91
29K12MIT.ENC 24 246 6-Sep-90
30K12PL8.ENC 24 270 30-Aug-90
31K12CRF.ENC 17 294 30-Aug-90
32K12GLB.ENC 6 311 5-Sep-90
33K12MIT.LST 30 317 6-Sep-90
34K12MIT.DSK 52 347 28-Oct-91
35K12ENC.DOC 24 399 31-Aug-90
36K12MIT.BWR 69 423 28-Oct-91
37K12MIT.BOO 18 492 1-Oct-91
38K12PL8.BOO 18 510 1-Oct-91
39K12CRF.BOO 12 528 1-Oct-91
40K12GLB.BOO 4 540 1-Oct-91
41K12IPL.DOC 9 544 6-Oct-91
42K12FL0.IPL 18 553 8-Oct-91
43K12FL1.IPL 18 571 8-Oct-91
44K12IP0.ODT 4 589 6-Oct-91
45K12IP1.ODT 4 593 6-Oct-91
46<Unused> 391 597
47
48 21 files in 583 blocks, 391 free blocks.
49
50 Description of individual files.
51
52 K12MIT.PAL
53
54 This is the current release of KERMIT-12 in source form. The
55 beginning of this file contains much information about setting up
56 various hardware (KL-8, etc.) and software settings for KERMIT-12
57 internal operation; the first 30-35 pages of the listing file created
58 by PAL8 are available as a stopgap user guide in the form of
59 K12MIT.DOC. It is extremely important to read the section on assembly
60 instructions for K12MIT, as non-default switches must be set for
61 proper assembly.
62
63 Due to the sorry state of the predecessor source (K08MIT) this
64 file is based on, it has taken an extreme amount of effort to overcome
65 many former limitations on many levels; there are still many problems
66 which only development time (when available) will overcome. There is
67 also a lot of inconsistency of implementation, i.e., some features are
68 totally finalized (or are so written in such a way that only a
69 non-existent section of code could "wake up" the feature), while
70 others are bound to be "bodily replaced" (such as the low-level
71 protocol implementation which can "blow up" when dealing with certain
72 atypical (though perfectly reasonable) KERMIT implementations which
73 pass data such as lower-case file name characters, etc.) when time is
74 available.
75
76 Approx. 2/3 of the source code and 80% of the current file
77 contents have been written by Charles Lasner taking advantage of over
78 20 years of PDP-8 hacking and "cook-book" methods, etc., including
79 some never-before-seen techniques "borrowed" from P?S/8 (P?S/8 is an
80 alternate PDP-8 operating system and is copyright CLA Systems). Every
81 new piece of code added to KERMIT-12 usually represents an exemplary
82 method for handling a given task, often producing "quantum leap"
83 improvements over the former code; see the built-in edit history for
84 details.
85
86 It should be noted that KERMIT-12 runs on the minimum OS/8 family
87 configuration of 8K 12-bit words total main memory (including the
88 operating system; this could change in future versions!) and is
89 probably the smallest known (in terms of total executable binary code)
90 KERMIT implementation. (If a P?S/8 KERMIT is written, it will run on
91 a smaller machine, only 4K 12-bit words!)
92
93 A rough table of improvements (wish list?) includes:
94
95 a) 100% rewrite of the command parser to conform to accepted
96 guidelines of most KERMITs.
97
98 b) 100% rewrite of the protocol-related features to allow for a
99 robust (though minimal) KERMIT implementation that should work
100 in all cases.
101
102 c) Adding in local feature improvements (Connect mode parity
103 support, VT-100 terminal support, command files, etc.) which
104 depend on the better command processor to implement
105 efficiently.
106
107 d) Adding in protocol improvements such as negotiated parameters
108 (eight-bit, repeat-count compression, file attributes, server
109 mode, etc.) and session statistics (internally and visually
110 on-line).
111
112 e) Additional "frills" such as scripting language, macros, etc.,
113 as well as anything else someone can add to this list.
114
115 K12PCH.PAL
116
117 This is the official "patch" file for K12MIT.PAL. All relevant
118 customizing can be accomplished within K12PCH.PAL, as all conditional
119 parameters and their consequences have been copied to K12PCH.PAL,
120 leaving only the "pure" code behind in K12MIT.PAL.
121
122 A standard assembly of K12MIT.PAL producing K12MIT.BN (or
123 K12MIT.SV via ABSLDR.SV) can be overlaid by K12PCH.BN to accomplish
124 any relevant changes to configure a custom version. If any parameter
125 causes this convention to be violated, please notify Charles Lasner,
126 as this specification must be met to support the ability for a minimal
127 system to configure KERMIT-12 from K12MIT.SV and K12PCH.BN on modest
128 hardware (such as one pair of RX01 only).
129
130 Use of K12PCH.PAL mandates a local banner message for the running
131 KERMIT.SV which should be locally modified as necessary. The default
132 message is "Insert Local User Message Here" to encourage
133 customization.
134
135 K12ENC.PAL
136
137 This is an encoding program (aka ENCODE) to convert OS/8 files in
138 any format to a "printable" ASCII format suitable for transmission
139 through any medium which doesn't "mangle" the printing ASCII
140 characters from 0 through 9, and A through V (or a through v).
141 Several binary files are distributed in ENCODE format (see elsewhere).
142
143 All characters outside of the printing ASCII character set are
144 ignored except for the necessity for "white-space" to exist between
145 the two fields of the optional (FILE XXXXXX.XX) command, which
146 specifies the name of the original (un-encoded) file. Several other
147 optional commands are supported; see K12MIT.ENC as an example of all
148 of them. When properly decoded (see K12DEC.PAL description below),
149 the original file is totally restored except for additional
150 information words from the directory (not really in the file itself!),
151 thus only the creation date (if the directory is setup to support it)
152 is lost. Users of ENCODE are encouraged to use the (REMARK .....)
153 command to help in the restoration of the file. Assembly instructions
154 as well as usage examples are provided in the source file. NOTE:
155 output files created by this program can overwrite existing files with
156 identical names; use this utility carefully!
157
158 The format used by ENCODE (and DECODE) was designed by Charles
159 Lasner and Frank da Cruz to allow seven-bit ASCII transmission of
160 arbitrary binary files (any file where the eight-bit representation
161 must be maintained, such as OS/8 files unpacked/packed as strings of
162 eight-bit bytes) through "hostile environments," such as seven-bit
163 ASCII-only KERMIT (alas, the current sorry state of KERMIT-12), or
164 various network E-mailers. An optional checksum feature (supported on
165 the PDP-8 version) will ensure against data corruption. The format is
166 robust enough to allow extraneous "white-space" (<space> <HT> <VT>
167 <FF>, <CR>/<LF>, etc.) to be introduced by various intermediate
168 "editors" with no loss.
169
170 It is hoped that this format is adopted on many systems, as it was
171 designed to overcome some of the limitations of the former (albeit
172 extremely popular) UUENCODE and .BOO formats used elsewhere.
173
174 K12DEC.PAL
175
176 This is an auxiliary utility (aka DECODE) to decode the encoded
177 binary files created by ENCODE into their original form. (See
178 description of K12ENC.PAL.) The files can be recreated with any
179 arbitrary file name including the original file name if embedded
180 within the encoded file (embedded file name commands are optional to
181 the encoded file format.), and can be directed to any OS/8
182 file-structured device.
183
184 Since this utility is potentially to be used on systems with
185 "ancient" assemblers, the source file has been restricted in the use
186 of "frill" features, so it can be assembled by virtually any known
187 standard released version of PAL8 associated with any release of PS/8,
188 PS/12, OS/8, OS/12, OS/78, OS/278, etc., and should be used to decode
189 K12PL8.ENC and K12CRF.ENC into PAL8.SV AND CREF.SV respectively, which
190 will then allow further assemblies with the latest PAL8 and CREF
191 (Version B0). Assembly instructions as well as usage examples are
192 contained within the source file. NOTE: output files created by this
193 program can overwrite existing files with identical names; use this
194 utility carefully!
195
196 K12PRM.PAL
197
198 This is an example of a custom parameter file ("PARAM" in the
199 documentation) for use with either K12MIT.PAL or K12PCH.PAL. It sets
200 most of the common parameters to their likely (possibly default)
201 values. VT-78-specific parameters are given for SLU2 support; a
202 VT-78-specific banner message is created as an example of a
203 user-defined banner message.
204
205 K12CLR.PAL
206
207 This file is a simple memory-clearing file. All KERMIT-12 loading
208 memory is pre-cleared by loading K12MIT.BN over the binary file
209 K12CLR.BN derived from this file. This yields "cleaner" core-image
210 files which will compress better when encoded with ENCODE (K12ENC) or
211 ENBOO (K12ENB).
212
213 K12ENB.PAL
214
215 This file is a utility program to encode any OS/8 file into .BOO
216 format for distribution via any "ASCII" path much the same as the
217 ENCODE utility. While not as robust as ENCODE format, .BOO files are
218 generally smaller, which may be desirable. This implementation uses
219 length correction bytes at the end of any file requiring it. The
220 ultimate decoding program must support this aspect of the format to
221 ensure reliable file recreation.
222
223 This utility, as well as the companion K12DEB (see below) use the
224 standard OS/8 unpacking scheme internally to ensure proper file
225 representation on other systems. This allows ASCII (albeit
226 "delicate") files to be encoded/decoded between systems. This allows
227 exchange of such files as TECO macros without loss.
228
229 K12DEB.PAL
230
231 This file is a utility program to decode .BOO format files back
232 into their original (binary) form. Length correction bytes are
233 supported to ensure proper file decoding. Any file encoded with ENBOO
234 (aka K12ENB) will decode perfectly back into the original form as long
235 as the file's contents are intact other than white-space and other
236 insignificent "cosmetic" considerations.
237
238 Files not originating from OS/8 (not an exact multiple of 384
239 bytes) will be padded with null bytes to fill the rest of an entire
240 OS/8 record. Files stored this way and then encoded again will
241 reflect these extra null bytes. This implementation doesn't check for
242 line terminations, so files delivered without proper <CR>/<LF> line
243 termination are acceptable.
244
245 K12IPL.PAL
246
247 This file is a utility program to load portions of KERMIT-12
248 directly into memory without any error checking or recovery method.
249 It is used to create K12MIT.SV "from the ground up." Once K12MIT.SV
250 has been created, this utility should be abandoned in favor of
251 K12MIT.SV to acquire all further files. Use this utility only if no
252 other method is available, as it is inherently unreliable. The safest
253 way to use it is with a local dedicated connection to another machine
254 via null modem.
255
256 K12MIT.SV is available split into single-field encoded files to be
257 loaded by this program. Documentation on the entire loading process
258 is contained within the source file. The binary version(s) of this
259 program can be directly keyed into ODT if desired as the shortest way
260 to load K12MIT.SV if desired. (See K12IP0.ODT and K12IP1.ODT
261 description below.)
262
263 K12IPG.PAL
264
265 This file is a utility program to generate the .IPL format files
266 (K12FL0.IPL and K12FL1.IPL from K12MIT.SV) meant to be loaded with
267 IPL0.SV and IPL1.SV as created by the user from K12IPL.PAL. It is
268 primarily a development tool and must be modified if K12MIT.SV is
269 enlarged to occupy an additional memory field.
270
271 K12MIT.ANN
272
273 This is the release announcement file for KERMIT-12.
274
275 K12MIT.UPD
276
277 This is the release update file for KERMIT-12.
278
279 K12MIT.DOC
280
281 This is a collection of hints and kinks, etc. regarding
282 KERMIT-12, including hardware-specific recommendations for customizing
283 and assembling KERMIT-12 for a variety of configurations. The edit
284 history of KERMIT-12 is also included. (This file is the beginning of
285 the file K12MIT.PAL. It is intended for those who do not obtain
286 K12MIT.PAL, the main source code, which is much longer and beyond the
287 filing capabilities of some of the smaller (though supported) systems.
288 By using the information in K12MIT.DOC, KERMIT-12 can be created by
289 merely obtaining all of the files except K12MIT.PAL.)
290
291 K12MIT.NOT
292
293 This is a collection of release notes for the latest version. New
294 issues raised or solved by this release will be collected here. Old,
295 but open issues may be retained in this file also.
296
297 K12MIT.ENC
298
299 This is the standard assembly of the distributed K12MIT.PAL (using
300 PAL8 Version B0) into K12MIT.BN which is then loaded (using ABSLDR.SV)
301 over K12CLR.BN to produce K12MIT.SV which is then converted to ENCODE
302 format (using ENCODE.SV (aka K12ENC.SV) as described above). All
303 parameters are set to their normal defaults including those parameters
304 which cause the local banner message to be generated as a valid null
305 message (in case K12PCH.BN is not loaded over K12MIT.SV). This file
306 should first be decoded with DECODE.SV (aka K12DEC.SV) into K12MIT.SV
307 and then overlaid by K12PCH.BN to create a customized local version.
308 The resultant customized version should be named KERMIT.SV (or any
309 other appropriate file name), and not be named K12MIT.SV, to avoid
310 confusion with the standard release file of KERMIT-12; it is likely
311 all future releases will use this naming convention.
312
313 K12PL8.ENC
314
315 This is PAL8 Version B0 from the "official" release of OS/278
316 Version 2, i.e., the version available as DECUS DM-101, in ENCODE
317 format. It has no actual dependencies on any cpu hardware extensions
318 beyond the classic PDP-8 (as was originally intended). PAL8 Version
319 B0 and its companion CREF Version B0 (see below) will run on any OS/8
320 family member system.
321
322 There is a minor quirk of PAL8 Version B0 documented in K12MIT.PAL
323 regarding interaction with the TTY: handler of operating systems
324 prior to OS/278, but in all other respects this should be treated as a
325 replacement for all prior PAL8 releases. This version supports 128k
326 assembly as do several prior versions; the listing format will
327 truncate one column earlier on wide source file input lines.
328 K12MIT.PAL requires the use of PAL8 Version B0 (or essentially any
329 2-digit release just prior to Version B0; in any case no versions
330 prior to Version 10A) for proper assembly. PAL8 Version B0 is
331 distributed as a convenience to KERMIT-12 users.
332
333 K12CRF.ENC
334
335 This is CREF Version B0 from the "official" release of OS/278
336 Version 2, i.e., the version available as DECUS DM-101, in ENCODE
337 format. It has no actual dependencies on any hardware extensions
338 beyond the classic PDP-8 (as was originally intended). Besides fixing
339 several long-standing bugs of CREF, this version is the required
340 companion to PAL8 Version B0. This is the only known CREF version
341 that will format 128k-capable assembly output correctly, which was a
342 major sore point for three prior releases, preventing their proper
343 use; many users have had to stick with PAL8 V10A and CREF V3 until
344 this release. CREF Version B0 is distributed as a convenience to
345 KERMIT-12 users.
346
347 K12GLB.ENC
348
349 This is a TECO macro K12GLB.TEC (aka GLOBAL.TEC) which maintains
350 the concordance between K12MIT.PAL and K12PCH.PAL. It is distributed
351 in ENCODE format to protect the rigid format requirements of a TECO
352 macro. All global symbols required by K12PCH.PAL are equated within
353 K12MIT.PAL in a special format required by GLOBAL.TEC. The OS/8 MUNG
354 command is used to update K12PCH.PAL whenever KERMIT-12 development
355 (within K12MIT.PAL) dictates. KERMIT-12 developers must fully
356 understand how to use this utility.
357
358 K12MIT.LST
359
360 This file is a symbol-table listing of K12MIT.PAL minus the code
361 listing. It is needed by K12GLB.TEC for the maintenance of
362 K12PCH.PAL. K12MIT.LST can be created from K12MIT.PAL merely by
363 assembling K12MIT.PAL as documented within K12GLB.TEC; it is provided
364 in the distribution for those unable to obtain the main source
365 (K12MIT.PAL) due to its size.
366
367
368 K12MIT.DSK
369
370 This file, which explains the KERMIT-12 distribution files as they
371 appear on the RT-11-format RX02 release diskettes.
372
373 K12ENC.DOC
374
375 This is a description of the encoding format used for the ENCODed
376 binary files (.ENC) in the KERMIT-12 release. Related issues and file
377 considerations are also discussed to foster future encoding formats,
378 since the format is subject to possible change.
379
380 K12MIT.BWR
381
382 This file documents known problems with the current release of
383 KERMIT-12 and related utilities. Possible workarounds are also
384 discussed.
385
386 K12MIT.BOO
387
388 This is the standard assembly of the distributed K12MIT.PAL (using
389 PAL8 Version B0) into K12MIT.BN which is then loaded (using ABSLDR.SV)
390 over K12CLR.BN to produce K12MIT.SV which is then converted to .BOO
391 format (using ENBOO.SV (aka K12ENB.SV) as described above). All
392 parameters are set to their normal defaults including those parameters
393 which cause the local banner message to be generated as a valid null
394 message (in case K12PCH.BN is not loaded over K12MIT.SV). This file
395 should first be decoded with DEBOO.SV (aka K12DEB.SV) into K12MIT.SV
396 and then overlaid by K12PCH.BN to create a customized local version.
397 The resultant customized version should be named KERMIT.SV (or any
398 other appropriate file name), and not be named K12MIT.SV, to avoid
399 confusion with the standard release file of KERMIT-12; it is likely
400 all future releases will use this naming convention.
401
402 It is conceivable that distribution "paths" may be "hostile" to
403 .BOO format thus making K12MIT.SV (or other files) undeliverable when
404 encoded in .BOO format. For example, some users acquire KERMIT-12 via
405 a path including WPS and WPFLOP.SV. .BOO files cannot reliably pass
406 through this process. In this or any other "troublesome" case, the
407 ENCODE format equivalent file is recommended for distribution.
408
409 K12PL8.BOO
410
411 This is PAL8 Version B0 from the "official" release of OS/278
412 Version 2, i.e., the version available as DECUS DM-101, in .BOO
413 format. It has no actual dependencies on any cpu hardware extensions
414 beyond the classic PDP-8 (as was originally intended). PAL8 Version
415 B0 and its companion CREF Version B0 (see below) will run on any OS/8
416 family member system.
417
418 There is a minor quirk of PAL8 Version B0 documented in K12MIT.PAL
419 regarding interaction with the TTY: handler of operating systems
420 prior to OS/278, but in all other respects this should be treated as a
421 replacement for all prior PAL8 releases. This version supports 128k
422 assembly as do several prior versions; the listing format will
423 truncate one column earlier on wide source file input lines.
424 K12MIT.PAL requires the use of PAL8 Version B0 (or essentially any
425 2-digit release just prior to Version B0; in any case no versions
426 prior to Version 10A) for proper assembly. PAL8 Version B0 is
427 distributed as a convenience to KERMIT-12 users.
428
429 K12CRF.BOO
430
431 This is CREF Version B0 from the "official" release of OS/278
432 Version 2, i.e., the version available as DECUS DM-101, in .BOO
433 format. It has no actual dependencies on any hardware extensions
434 beyond the classic PDP-8 (as was originally intended). Besides fixing
435 several long-standing bugs of CREF, this version is the required
436 companion to PAL8 Version B0. This is the only known CREF version
437 that will format 128k-capable assembly output correctly, which was a
438 major sore point for three prior releases, preventing their proper
439 use; many users have had to stick with PAL8 V10A and CREF V3 until
440 this release. CREF Version B0 is distributed as a convenience to
441 KERMIT-12 users.
442
443 K12GLB.BOO
444
445 This is a TECO macro K12GLB.TEC (aka GLOBAL.TEC) which maintains
446 the concordance between K12MIT.PAL and K12PCH.PAL. It is distributed
447 in .BOO format to protect the rigid format requirements of a TECO
448 macro. All global symbols required by K12PCH.PAL are equated within
449 K12MIT.PAL in a special format required by GLOBAL.TEC. The OS/8 MUNG
450 command is used to update K12PCH.PAL whenever KERMIT-12 development
451 (within K12MIT.PAL) dictates. KERMIT-12 developers must fully
452 understand how to use this utility.
453
454 K12IPL.DOC
455
456 This file is a description of the encoding format for .IPL files
457 as used in the direct loading method of acquiring K12MIT.SV.
458
459 K12FL0.IPL
460
461 This file is the field zero data of K12MIT.SV encoded into .IPL
462 format for use with IPL0.SV (from K12IPL.PAL).
463
464 K12FL1.IPL
465
466 This file is the field one data of K12MIT.SV encoded into .IPL
467 format for use with IPL1.SV (from K12IPL.PAL).
468
469 K12IP0.ODT
470
471 This file is a sample of an ODT session used to create IPL0.SV
472 using manual entry into ODT and a SAVE command only. Some values
473 shown are default and may need to be customized according to
474 parameters documented in K12IPL.PAL. Using IPL0.SV (and IPL1.SV from
475 K12IP1.ODT as described below) is the shortest way possible to obtain
476 K12MIT.SV when no other method is available.
477
478 K12IP1.ODT
479
480 This file is the field one companion to K12IP0.ODT used to create
481 IPL1.SV using similar means to those described for IPL0.SV. Both
482 IPL0.SV and IPL1.SV are required to directly obtain K12MIT.SV.
483
484[end of file]