Multics Technical Bulletin                                MTB-626
The config deck editor for Bootload Multics

To:       Distribution

From:     Keith Loepere

Date:     06/07/83

Subject:  The config deck editor for Bootload Multics

Abstract

        As  part  of  replacing  BOS  with  the  Bootload Multics
environment, a new config deck  editor is needed.  The new config
deck  editor  is a  subset of  qedx that  allows the  operator to
perform normal  text editing operations on  the config deck (such
as,  "s/off/on/" to  configure a box  on) in  an environment that
understands the format of config decks.  A certain level of error
checking is performed by the new config deck editor on the config
deck.  The  editor's functioning was made  different from that of
qedx where this is convenient for editing config decks.

Comments on this MTB should be sent to the author -

     via Multics mail to:

          Loepere.Multics

     via telephone to:

          (HVN)-261-9332
          (617)-492-9332

_________________________________________________________________

Multics  project  internal  working  documentation.   Not  to  be
reproduced or distributed outside the Multics project.


Multics Technical Bulletin                                MTB-626
The config deck editor for Bootload Multics

Introduction:

        The new config deck editor is  a subsystem for use in the
Bootload Multics  environment (although it also  works at Multics
command level).   It keeps the  config deck in an  ascii form and
allows,  through  a qedx-like  interface, relatively  normal text
editing operations  to be performed on  the deck.  However, since
the editor  knows the format  of config cards  (as it must  to be
able  to read  and write them  in their binary  form), the config
deck editor can allow input of  and searching for config cards in
more meaningful and convenient forms  than would be possible in a
regular text editor  or was possible in the  previous config deck
editor.  Also, some validation of the config cards is possible.

        The new  config deck editor  allows a more  symbolic form
for config  cards.  In this form,  the fields of the  card may be
labeled and therefore appear in  any order.  A typical card might
be:

        iom -tag a -port 0 -model nsa -state on

Fields may  also be unlabeled;  in this case they  must appear in
the correct order for the particular card.  Labeled and unlabeled
fields may be mixed at will.  Depending on the circumstances, the
data  type of  a field  is determined from  the label,  if one is
present,  or  from the  appearance  of the  data value.   The old
convention  that fields  ending in a  period are  decimal and the
rest are octal (or strings) is kept.

        Config decks are normally read and written in their ascii
form.   Thus,  the user  visible  form of  the config  deck (with
fields  having symbolic  labels) is maintained.   When the config
deck is  written to the  real (binary) config  deck, however, the
labels  obviously disappear.   Any time  the config  deck is read
from the real config deck, and therefore converted from binary to
ascii form,  all of the  fields are given labels  for those cards
that are recognizable by the config deck editor.

1.  Structure

        The config deck editor (config_deck_edit_) is designed to
be called through the Bootload Multics simulated ssu_ environment
calling   sequence.    It  can   also   be  called   through  the
config_deck_edit Multics command.   The routine config_deck_edit_
itself is not ssu_ based because the syntax of requests and basic
operation  is  not  proper  for  ssu_.   The  routine  takes  one
argument, the deck to edit.  If no argument is supplied, the live
config deck  is read and  converted to fully  labeled ascii form;


Multics Technical Bulletin                                MTB-626
The config deck editor for Bootload Multics

otherwise,  a  file from  the Multics  hierarchy or  the Bootload
Multics file system is read, depending on the environment.

        The user is  then placed at request level  where he types
relatively normal looking qedx  requests.  The line addresses are
extracted from the request and  found, then the command character
dispatches to  the appropriate place  to perform the  action.  If
the request causes a line to  be printed from the config deck, it
is also validated  so the user knows what  to fix.  Requests that
modify  the  buffer post  a  modified flag  for it.   Writing the
entire buffer posts it as unmodified.

        The format  of config cards is  described through a bunch
of  tables;  no  information  on the  structure  of  any  card is
committed to  code.  Unknown card  formats are allowed;  you just
aren't  allowed to  label any  of the  fields (since  field names
would be  unknown).  Also, for  a card format which  is known but
for  which you  wish to supply  different ordering  of values and
types   (possibly  during   a  system  change),   placing  a  dot
immediately  before  the config  card  name causes  it not  to be
interpreted (and can then not have any labeled fields).

2.  Conversion from ascii to binary form

        The  conversion from  ascii to  binary forms  of a config
card  starts  by  separating  the unlabeled  and  labeled fields.
Labeled fields without a value generate an error.  Looking at the
fields,  the type  of config card  ("cpu", "prph  dsk", etc.)  is
determined.   A card  that is  unrecognizable or  whose card name
starts with a dot is considered  to be of type "user".  (The user
card type is described as  having no restrictions on its format.)
Given the card type, we can  tell from our tables what fields are
needed or allowed, and what they are called.

        We then take the labeled fields  and match them up to the
known names for  this card's fields.  This is done  in such a way
that the order of the labeled  fields on the user's card does not
matter but  where multiple occurrences of  the same labeled field
(such as more  than one "-chn" field) are kept  in the same order
that  the  user supplied.   Labeled  fields whose  label  are not
appropriate  for the  card (and there  are no labels  valid for a
user formatted card) are flagged as an error.

        As  a  result  of  the  labeled  field  match,  some  not
necessarily contiguous collection of fields have not been filled.
The  unlabeled fields  are put  into these  empty spaces,  in the
order supplied.


Multics Technical Bulletin                                MTB-626
The config deck editor for Bootload Multics

        The resultant card is then  checked to be sure that there
are no  holes left in  the card (a  field near the  end filled in
without  filling the  intermediate ones).  We  convert the user's
values  to binary  by first using  the type we  believe that they
should be, and,  if this fails, we convert  them according to the
type implied by the appearance of the user's value.

        The result of the above is that a user may say:

        iom a on -model nsa -port 0

and this will correctly turn into:

        iom a 0 nsa on

3.  Conversion of binary to ascii form

        Converting  a  config  card   from  binary  to  ascii  is
relatively simple  at the base level.   Each binary card contains
the  various fields,  in order, along  with a  tag specifying the
data type of  the field.  We determine the config  card type in a
manner similar to the method used for ascii to binary conversion.
Given  the  type, we  can determine  what labels  to give  to the
fields as we  convert them, given the data  type specified in the
card.   Cards of  an unrecognized  type are  given no  labels for
their fields.

        We  would  expect this  card  so formed  should  be good.
However, even  if the type  of this card was  recognizable to us,
its format may have changed without the change being reflected in
our tables.  A possibility we can't detect would be if two fields
of the  same data type were  rearranged so that we  have ended up
giving the wrong  names to the fields.  What we  expect to see in
cases  of  config  card  change, though,  is  for  the  data type
specified in the  binary card to produce an  ascii value which is
not what we  expected for the field.  (We did  not use our tables
to validate the  data types in the binary  to ascii conversion to
avoid duplicating code already in  the ascii to binary conversion
routines.)  To  validate the data  types, and to  cover any other
possible apparent misconformity, we take the ascii card generated
and parse it back to binary.   That is, we gave the fields labels
according to our tables but took the  card at its word as to what
data  types we  had.  We now  use our  tables to see  if the data
types are what we think they should be.  If we get any errors, we
assume the format has changed and  convert the card as if it were
a user  format card, putting a  dot in front of  the card name to
prevent errors from being flagged  later when the card is printed
or written back.


Multics Technical Bulletin                                MTB-626
The config deck editor for Bootload Multics

4.  Operation of the new config deck editor

        The  config deck  editor is  invoked either  from Multics
command  level with  the command  config_deck_edit (cde)  or from
Bootload  Multics  level  by   an  appropriate  name.   Also,  if
performing a  cold boot, the  config deck editor  is invoked with
the current  config deck as  an argument automatically  since you
must  type in  an initial  config deck.   The config  deck editor
takes either zero or one argument; if  one, it is the name of the
config  deck to  use (either a  Multics storage system  file or a
Bootload  Multics file,  depending on the  environment); if none,
the current (live) config deck is  used.  The config deck is read
into an internal  buffer; the binary config deck  is converted to
ascii as it is read.  The user is then put at request level.

        A current line pointer is  kept.  This points to the last
line  printed or  operated upon by  the config  deck editor.  The
first line in the buffer is numbered one.  Operations that add or
delete lines dynamically renumber the lines in the buffer.

        Any request that prints a  line also prints any errors in
it.

        Requests  follow  the  usual  qedx  syntax:   one  or two
addresses  followed  by  the  command  character.   This  may  be
followed by other arguments to  the request.  Another request may
follow this one on the same line.

        When no line addresses are  supplied, the default for the
requests is the same as for  qedx.  We allow both one address and
two address forms; for two addresses, the separator may be either
a comma or a semi-colon with the same meaning as in qedx.

        Line addresses  may take several forms.   A number refers
to the line so numbered.  A line address of the form .  or .+n or
.-n refers  to the line n  lines away from the  current line.  An
address of the form $ or $-n refers to the line n lines away from
the last line in the buffer.   Finally, /str/ or |str| or /str/+n
or /str/-n or |str|+n or |str|-n causes a string search to occur.
The /str/ form  performs a normal string search.   The |str| form
takes the  string apart as if  it were a config  card.  A card is
searched  for that  has all  the labeled  fields from  the search
string,  in  any order,  and  all the  unlabeled fields  from the
string, in order, but not necessarily contiguous.  Thus,

        |cpu -state on|


Multics Technical Bulletin                                MTB-626
The config deck editor for Bootload Multics

will match all cpu cards that are specified to be on in this way.
Null strings  may be supplied  which implies the  previously used
string.  Also, the qedx perverted forms //n and .n are allowed.

        The request  set and their  actions are the  same as qedx
except as  noted below.  In particular,  we support the following
requests:

- print lines (p) request
- string searching (a search string specified for an address with
        either no request character or the p request specified)
- append (a), insert  (i) and change (c) lines  requests using f
        to denote end of insertion
- delete lines (d) request
- print line number (=) request
- buffer status (x) request (prints the number of config cards)
- read config deck (r) request
- write config deck (w) request
- substitute string (s) request
- quit (q) request
- global and exclude (gp, gd, g=, vp, vd and v=) requests

We differ from qedx in the following:

- All whitespace converts to a single blank between fields.
- We do not allow regular expressions in search strings.
- Although  the  value of  // and  || are  saved, the  values are
        different.  (Specifying || uses  the last value of |str|,
        not the last value of /str/.)
- We do not recognize ampersand substitution forms.
- The old string in the substitute request must be of the form //
        or /str/.   |str| forms are  not allowed.  Slash  must be
        the delimiter.
- We do not  support multiple  buffers or  anything suggestive of
        them.
- We do not support line escapes since their is no need for them.
- A read or write with no file name specified does not follow the
        qedx  default action.   Instead, we  use the  live config
        deck.   Note that  this is the  only way to  refer to the
        live config  deck.  (One cannot write  to the live config
        deck during Multics normal operation.)
- Escape to command level is not supported.
- Quitting with  a modified buffer  causes a query.   One may not
        quit during cold boot until the deck has been written.

5.  Cards currently recognized


Multics Technical Bulletin                                MTB-626
The config deck editor for Bootload Multics

        The card formats currently recognized follow.

chnl -subsys  <str> -iom  <tag1> -chn  <number1> -nchan <number2>
        {...  -iom <tag4> -chn <number7> -nchan <number8>}

clok -delta <number1> -zone <str> -boot_delta <number2>

cpu -tag <tag1> -port <number1> -state <str1> -type <str2> -model
        <number2> -exp_port <tag2>

fnp -tag <tag1> -iom <tag2> -chn <number>

iom -tag <tag> -port <number> -model <str1> -state <str2>

mem -port <tag> -size <number> -state <str>

mpc -ctlr  <str>  -model  <number1>  -iom  <tag1>  -chn <number2>
        -nchan <number3> {...  -iom  <tag4> -chn <number8> -nchan
        <number9>}

parm <parms> (no restrictions are placed on names or order)

part -part <str1> -subsys <str2> -drive <number>

prph -device ccuN -iom <tag> -chn <number1> -model <number2>

prph -subsys  dskN  -iom  <tag> -chn  <number1>  -nchan <number2>
        -model   <number3>   -number   <number4>   {...    -model
        <number11> -number <number12>}

prph -device opc -iom <tag> -chn <number1> -model <number2>

prph -device  prtN  -iom  <tag> -chn  <number1>  -model <number2>
        -train <number3> {-ll <number4>}

prph -device punN -iom <tag> -chn <number1> -model <number2>

prph -device rdrN -iom <tag> -chn <number1> -model <number2>

prph -subsys  tapN  -iom  <tag> -chn  <number1>  -nchan <number2>
        -model   <number3>   -number   <number4>   {...    -model
        <number11> -number <number12>}

root -subsys <str1> -drive <number1>  {...  -subsys <str7> -drive
        <number7>}

salv <parms> (no restrictions are put on salv card options)

schd -wsf <number1>  -tefirst <number2> -telast  <number3> -timax
        <number4>  {-mine  <number5>  {-maxe  <number6> {-maxmaxe
        <number7>}}}


Multics Technical Bulletin                                MTB-626
The config deck editor for Bootload Multics

sst -4k <number1> -16k <number2> -64k <number3> -256k <number4>

tbls <parms> (no restrictions are put on tbls card fields)

tcd -apt <number1> -itt <number2>

udsk -subsys  <str>  -nchan  <number1>  -drive  <number2> -number
        <number3> {...  -drive <number12> -number <number13>}

<user defined> <fields>  (no restrictions are put  on user format
        cards)

6.  Equivalences for old functions

        Currently, in  BOS, there are  two ways to  edit a config
deck,  with  the  BOS editor  and  with the  BOS  CONFIG command.
Although there is really no comparison between the old methods of
editing a config deck in BOS and the new way, we will list a way,
in the new  config deck editor, to perform  the same operation as
in the old methods.

- BOS EDIT N {n} becomes +{n}n (one  can leave off the final n to
        get the line to print)
- BOS EDIT - {n} becomes -{n}n
- BOS EDIT P {n+1} becomes .,+{n}p
- BOS EDIT I becomes i
- BOS EDIT T  becomes 1n (although T  really positions before the
        first line)
- BOS EDIT B {lines} {empty line} becomes $a {lines} f
- BOS EDIT D {n+1} becomes .,+{n}d
- BOS EDIT Q becomes q followed by  answering no to the query "Do
        you wish to quit with a modified buffer?"
- BOS EDIT W {name} becomes w{name} followed by q
- CONFIG  L  {cards}  QUIT  becomes  1,$da  {cards}  f (assuming
        throughout that you are in the config deck editor)
- CONFIG  L  {name} was  performed  as a  result of  entering the
        config deck editor
- CONFIG SAVE {name} becomes w{name}
- CONFIG A {cards} QUIT becomes $a {cards} f
- CONFIG  C  {cards}  QUIT or  CONFIG  R {cards}  QUIT  becomes a
        collection of  |{card}| searches with  c or s  requests -
        performing an s request is  probably what the user wanted
        to do with the CONFIG C command
- CONFIG P {card names} becomes a set of gp|{card name}|
- CONFIG  D  {card  names}  becomes  a  set  of  gd|{card  name}|
        (although the usual use of  this, to delete all mem cards
        before  retyping  the  new   order,  can  now  be  better
        performed)