Patch Workflow (Part 1)

Overview

Patching a system is a complicated process which requires considerable caution and preparation. This workflow is not prescriptive but illustrates a reliable path to success.

Preparation

Before applying any patches, we need to know a few things:

Target Account
Target Filename
- + Target Filetype
Contents of the patch
A Current and Complete Backup.

Target Account

This element is critical because it may prescribe special treatment of the file. Some accounts have special meaning, purpose, or controls.

Account	Is special because …
system	Principal container of all privileged files, lessons and is the core of the running system
s0nver	Principal container of all system lessons under development.
s0over	Principal container of all backup (last resort) copies of system lessons
s0sup	System Support files.
s0files	Special system files which are generally independent of `version` controls
s0cond	PLATO Condenser sources.
s0exec	PLATO Executor sources.
s0fram	PLATO Framer sources.
s0mast	PLATO Mass Storage manager sources.
s0ppus	PLATO specific peripheral processing unit sources.
s0util	PLATO Utility programs.
publis`x`	Published courseware.

The primary accounts with which we are concerned are those noted in bold above: the system account and those starting with s0.

Target Filename

The target filename is important because (especially for system files) there are properties outside of the file that determine functionality.

The checklist associated with the filename is:

Determine the filetype:
1. Some files cannot be patched using this method.
2. No filename may begin with the numbers 5 through 9,
3. Filenames must consist of alpha-numeric values only.
System Lesson Status
1. Check to see if the lesson

Patchable File Types

This is the list of all known PLATO filetypes:

File Type	Type Letter	Description	Patchable
`tutor`	`a`	normal tutor lesson	Yes
`instruct`	`a`	instructor file	Yes
`router`	`a`	router lesson	Yes
`binary`	`b`	lesson binary	No
`curric`	`c`	curriculum file	No
`data`	`d`	student data file	No
`compass`	`e`	system source file	Yes
`ppt`	`e`	system source file	Yes
`group`	`f`	group file	No
`dataset`	`g`	dataset	No
`plmcurr`	`h`	CLM curriculum file	No
`pnotes`	`h`	old-style pnotes file	No
`gnotes`	`i`	group notes	No
`mailbox`	`j`	nameset-type pnotes (NN)	No
`unknown`	`j`	unknown format (utility)	No
`namesete`	`k`	named-record dataset (ext)	No
`nameset`	`k`	named-record dataset	No
`account`	`l`	account	No
`catalog`	`m`	catalog file	No
`notesfile`	`n`	graphics notes file	No
`notes`	`n`	notes file	No
`module`	`o`	CLM module file	No
`pnotes`	`p`	personal notes	No
`document`	`q`	documentor file	No
`ccd3`	`r`	CCD3 course file	No
`pcd3`	`r`	PLATO CD3 course file	No
`lessonset`	`s`	nameset-type lesson (NN)	No
`unknown`	`s`	unknown format (utility)	No
`mailfile`	`t`	graphics mail file (old)	No
`account`	`t`	nameset-type account file (NN)	No
`exambase`	`u`	exambase file (CYBIS)	No
`archive`	`/`	archive file	No
`retrieval`	`(`	dummy file awaiting archive retrieval	No
`backup`	`)`	dummy file awaiting backup retrieval	No
`pholder`	`$`	dummy place holder file	No
`packdir`	`;`	pack directory (specially handled)	No

Patchable Block Types

Not all Block Types are Patchable using this patch system:

Block Type	Patchable
`access`	No
`binary`	No
`charset`	Yes
`common`	Yes
`data`	No
`leslist`	Yes
`lines`	No
`listing`	Yes
`micro`	No
`source`	Yes
`text`	Yes
`vocab`	No

About Unpatchable Types

Unpatchable block types are ignored/skipped by the patch system when editing the target.

System Lessons

It is important to know whether or not a lesson is on the list of System Lessons. System Lessons are treated differently than ordinary lessons in that they can invoke privileged commands to manipulate files at a low-level, access system resident / sensitive memory locations, and more.

System Lesson List

Lesson s0syslst can tell you the status of the currently known system lessons:

System Lesson Attributes

Not only is it important to know which lessons are System Lessons, but it is also important to know what type of system lesson it is. Some system lessons are built into PLATO itself (Type=Release). Some lessons are assigned privileges by the local site's systems staff (Type=Local).

Knowing these differences informs what prerequisites need to be met before a patch file can be applied. Case in point is lesson notesys.

Some system lessons may not have proper attributes set after patching. A patch for lesson notesys requires the ability to write to Central Memory and ECS ¹⁾. As distributed by VCampus, notesys did not have that privilege assigned and system lesson attributes built into PLATO cannot be assigned privileged attributes dynamically through lesson s0syslst. Therefore, a modification had to be made to PLATO itself, to enable this functionality.

It is for the above reasons (and more) that all of this information be discovered prior to applying any patches or making modifications to system lessons.

Attribute	Functionality Enabled
bin	(high priority condensing)
sys	(system lesson)
ppt	(ppt commands)
s1p	(stop1 protected)
wrt	(can write to cm/ecs)
jmp	(jumpout from non-system lessons)
acc	(generate usage accounting data)
nio	(can use -netio- commands)
pca	(no longer in use)
mas	(can use -masreq- commands)
mpsys	(micro plato system lesson)
d3	(lesson can be deleted while in use)
nv	(n-version lesson can be used)
sysnv	(n-version on dev. system only)

Contents of Patch

The utility GetMinPartCounts.ps1 (Powershell ²⁾) script summarizes the contents of the patch before it is applied:

For example, processing the patch file for -account2- results in the following information:

pf.lesson.account2      Contains account2    BlkCount=0091  MinParts=013
       <FullPathTo>\CybdevPatches\pf.lesson.account2.txt
       (*directory)1 Blocks
       source      90 Blocks

The first line indicates:

the name of the patch file
the original filename from which the patch was taken
the number of blocks found in the patch file
the minimum number of parts required to successfully apply the patches

The second line contains the full path to the patch file.

The third line is always present and contains the default assumption for the number of directory blocks in the file (it is always 1).

The fourth and subsequent lines, indicate the number of patched blocks found, by type, in the file.

Source of GetMinPartCounts.ps1

GetMinPartCounts.ps1

#requires -PSEdition Core
"   PLATO Target File Size Estimator"
 
$line = $null
 
# $PSVersionTable.PSVersion
 
$PatchFolder = $PSScriptRoot + "\CybdevPatches"
if ($args[0]) {
    $PatchFolder = $args[0]
}
Get-ChildItem $PatchFolder -Filter "pf.*.*.txt" |
Foreach-Object {
    $content = Get-Content $_.FullName
    $blkcount = 1
    $typecounts = [ordered]@{"(*directory)" = 1}
    foreach($line in $content) {
        if($line -match "CTL[+|-].*SEQ"){
            $filename = $line.Substring(8,10)
            $blocknum = $line.Substring($line.IndexOf("SEQ") + 3)
            $blocknum = [convert]::ToInt32($blocknum)
            $type = $line.Substring($line.IndexOf("TYP") + 3, 10).Trim()
 
            switch ($type){
                "charset" {
                    #   At least one block
                }
                "common" {
                    #   Wait for a length
                }
                default {
                    $blkcount += 1
                    $typecounts.$type += 1
                }
            }
 
        }
        $lcommon = $line.Substring(0,11)
        if ($type -eq "common" -and $lcommon -eq "TXTlcommon=") {
            $nwords = [convert]::ToInt32($line.Substring(11))
            $nblocks = [convert]::ToInt32($nwords / 320)
            if ([convert]::ToInt32($nwords % 320 -gt 0)) {
                $nblocks += 1
            }
            $blkcount += $nblocks 
            $typecounts.$type += $nblocks            
        }
        $txtchar = $line.Padright(14).Substring(0,14)
        if ($type -eq "charset" -and $txtchar -eq "TXTchar    127") {
            $blkcount += 1
            $typecounts.$type += 1            
        }
        if ($type -eq "charset" -and $txtchar -eq "TXTchar    128") {
            $blkcount += 1
            $typecounts.$type += 1            
        }
    }
 
    $nparts = [Math]::Ceiling($blkcount  / 7)
 
    $_.BaseName.PadRight(24) + `
    "Contains " + $filename.PadRight(" ",10) + `
        "  BlkCount=" + $blkcount.ToString("0000") + `
        "  MinParts=" + $nparts.ToString("000")
 
    "       " + $_.FullName
 
    foreach($type in $typecounts.Keys){
        "       " + $type.PadRight(12) + $typecounts.$type + " Blocks"
    }
 
}

COMMON Warning

Some patches may modify common blocks. This must be done judiciously or the entire system could be rendered inoperable.

Limitations of Patching

Patch files may have some errors. This is especially true of files whose original file had individually partialed-out blocks within a range of like-named blocks.

Example:

1-a *directory 1-b thisblock - 1-c thisblock (partialed out) 1-d thatblock 1-e thisblock 1-f thisblock

The patch system gathers all blocks of the same name as if they were contiguous. If the first block of a series is not partialed-out all blocks are incorporated into the patch as if they were not partialed-out. Therefore block 1-c (partialed out) will erroneously remain active.

This is one of MANY reasons why patches need to be carefully applied and tested prior to deployment.

Next Steps

Once you have a good command of the above, continue learning more in Article Patch Workflow (Part 2).

¹⁾

Extended Core Storage

²⁾

Platform agnostic scripting language

Retro1.org codex

Table of Contents