(* >>>> HELPER.TEXT  **************************************************)

(*$I-*)
(*$R-*)
(*$S+*)
(*$V-*)

UNIT helper;      INTRINSIC  CODE 22;


INTERFACE

USES  kermglob,
      kermutil;

PROCEDURE help;

IMPLEMENTATION

PROCEDURE help;


const  scrpr   = 'resp. on screen or on the printer.';
       numpar  = 'Takes a number as parameter.';
       charpar = 'Takes a character as parameter.';
       onoffp  = 'Takes ON / OFF as parameter.';
       conval  = 'Valid only during CONNECT.';
       ftval   = 'Valid only during file transfer.';
       dumpval = 'Valid only in screendump mode.';

Var  i : integer;
     ch : char;


(************  Auxiliary procedures ***********************************)



PROCEDURE wait;

begin
  if not pr_out then
    begin
      ch := ' ';
      gotoxy( 0, 23 );
      write('----------- ');
      write('( Type <spacebar> to continue or '); write_ctl( esc_char );
      write(' to quit help ) ------------');
      read( keyboard, ch );
      if ch = esc_char then begin
                              writeln;
                              writeln;
                              exit( help );
                            end;
      page( output );
    end;
end;


PROCEDURE line;

begin
  for i := 1 to 24 do write(p,'-');
end;


PROCEDURE word1( sym : vocab );

begin
  writeln(p);
  line;
  writeln(p);
  writeln(p, vocablist[sym] );
  line;
  writeln(p);
  writeln(p);
end;


PROCEDURE word2( sym1, sym2 : vocab );

begin
  writeln(p);
  line;
  writeln(p);
  writeln(p, vocablist[sym1], '   ', vocablist[sym2] );
  line;
  writeln(p);
  writeln(p);
end;


PROCEDURE aciaset( sym : vocab );

begin
  write(p,'According to the file ', setup_file, ' this command should ');
  if ( ( aciaimplem=A6850 ) and ( sym=baudsym ) ) or
       ( aciaimplem=unknown ) or ( aciaimplem>A6551 )
   then writeln(p,'not work.')
   else begin
          writeln(p,'work.');
          writeln(p,'Consult your serial card manual for valid settings.');
        end;
end;


(*********** Introduction procedure  ***********************************)


PROCEDURE introkermit;
begin
  writeln(p,'KERMIT is a family of programs that do reliable file transfer');
  writeln(p,'between computers over TTY lines. ( BYTE june & july 1984 )');
  writeln(p,'KERMIT can also be used to make the micro computer behave as a');
  writeln(p,'terminal for a mainframe.');
  writeln(p);
  writeln(p,'These are the commands for the Apple ][(e) UCSD KERMIT ',version);
  writeln(p);
  writeln(p);
end;


(********* These procedures explain the commands except SET ************)


PROCEDURE helpsend;
begin
  word1( sendsym );
  writeln(p,'To send a file to the remote system.');
  writeln(p,'Takes a filename as parameter.');
end;

PROCEDURE helpdir;
begin
  word2( dirsym, pdirsym );
  writeln(p,'Lists the directory of a disk ', scrpr );
  writeln(p, numpar, ' ( 4,5,9..12 )');
end;

PROCEDURE helphelp;
begin
  word2( helpsym, phelpsym );
  writeln(p,'To get an explanation of KERMIT commands ', scrpr );
end;

PROCEDURE helpshow;
begin
  word2( showsym, pshowsym );
  writeln(p,'Shows the values of the parameters that can be modified via');
  writeln(p,'the SET command ', scrpr );
end;

PROCEDURE helpconn;
begin
  word1( consym );
  writeln(p,'To make a virtual terminal connection to a remote system.');
  writeln(p,'To break the connection and escape back to the micro KERMIT');
  write(p,'command level type '); write_ctl( esc_char );
  writeln(p,' immediately followed by <C>.');
  writeln(p,'When the Apple screen starts scrolling host characters may');
  writeln(p,'be lost at > 1200 baud. To prevent this set the host''s');
  writeln(p,'linefeed fill to a count of about 5.');
end;

PROCEDURE helpexit;
begin
  word2( exitsym, quitsym );
  writeln(p,'To return back to the Apple UCSD p-system command level.');
end;

PROCEDURE helprec;
begin
  word1( recsym );
  writeln(p,'To accept a file or group of files from the remote system.');
end;


(***********  The following procedures explain the SET subcommands  ********)


PROCEDURE baudset;
begin
  word2( setsym, baudsym );
  writeln(p,'To set the serial baud rate.');
  writeln(p, numpar );
  aciaset( baudsym );
end;

PROCEDURE parset;
begin
  word2( setsym, paritysym );
  writeln(p,'This selects the parity for outgoing characters to match the');
  writeln(p,'requirements of the host.');
  writeln(p,'Takes as parameters : ', vocablist[nonesym], vocablist[oddsym]:4,
            vocablist[evensym]:5, vocablist[marksym]:5, vocablist[spacesym]:6 );
  writeln(p,'When the IBM flag is set, parity is set to ', vocablist[marksym],
            ' ( if possible ).');
  aciaset( paritysym );
end;

PROCEDURE wordlset;
begin
  word2( setsym, wordlensym );
  writeln(p,'Sets the number of databits for outgoing & incoming characters.');
  writeln(p, numpar );
  aciaset ( wordlensym );
end;

PROCEDURE stopbset;
begin
  word2( setsym, stopbsym );
  writeln(p,'Sets the number of stopbits for outgoing & incoming characters.');
  writeln(p, numpar );
  aciaset( stopbsym );
end;

PROCEDURE debugset;
begin
  word2( setsym, debugsym );
  writeln(p,'Shows packets sent & received during filetransfer when ON.');
  writeln(p, onoffp );
  writeln(p, ftval );
end;

PROCEDURE delset;
begin
  word2( setsym, delsym );
  writeln(p,'Changes the Apple <backspace> key to a <del> key for the host');
  writeln(p,'when set to ON.');
  writeln(p, onoffp );
  writeln(p, conval );
end;

PROCEDURE emulset;
begin
  word2( setsym, emulatesym );
  writeln(p,'Not implemented.');
end;
 
PROCEDURE eolnset;
begin
  word2( setsym, eolnsym );
  writeln(p,'Sets the "end-of-line" character sent after a KERMIT package.');
  writeln(p, charpar );
  writeln(p, ftval );
end;

PROCEDURE escset;
begin
  word2( setsym, escsym );
  writeln(p,'Sets the escape character preceding the <C>.');
  write(p,'The sequence '); write_ctl( esc_char );
  writeln(p,' <C> returns you to the KERMIT command level.');
  writeln(p, charpar );
  writeln(p, conval );
end;

PROCEDURE filewset;
begin
  word2( setsym, filewarnsym );
  writeln(p,'Changes names of received files to protect already existing');
  writeln(p,'files with similar names.');
  writeln(p, onoffp );
  writeln(p, ftval );
end;

PROCEDURE ibmset;
begin
  word2( setsym, ibmsym );
  writeln(p,'When communicating with an IBM VM/CMS mainframe this flag');
  writeln(p,'should be on.');
  writeln(p,'It also sets ', vocablist[paritysym], ' to ',
             vocablist[marksym], ' and activates ', vocablist[localsym],
             '.');
  writeln(p, onoffp );
end;

PROCEDURE localset;
begin
  word2( setsym, localsym );
  writeln(p,'This sets the duplex : it should be ON for th IBM VM/CMS');
  writeln(p,'and OFF for the CYBER, VAX, DEC-20.');
  writeln(p, onoffp );
end;

PROCEDURE maxtryset;
begin
  word2( setsym, maxtrysym );
  writeln(p,'Maximum number of times KERMIT tries to receive a correct');
  writeln(p,'package before breaking off the file transfer. At the start');
  writeln(p,'of file transfer this number is five times higher to allow');
  writeln(p,'the other side extra time to start file transfer.');
  writeln(p, numpar );
end;

PROCEDURE nofeedset;
begin
  word2( setsym, nofeedsym );
  writeln(p,'Replaces an incoming formfeed character with carriage return.');
  writeln(p, onoffp );
end;

PROCEDURE prefixset;
begin
  word2( setsym, prefixsym );
  writeln(p,'Sets the prefix name of the (disk)volume for incoming files.');
  writeln(p,'Takes a volume name as parameter.');
  writeln(p, ftval );
end;

PROCEDURE rejset;
begin
  word2( setsym, rejectsym );
  writeln(p,'When set control characters coming from the host are not');
  writeln(p,'echoed to the Apple screen or printer except :');
  writeln(p,'backspace, carr. return, formfeed, linefeed, bell.');
  writeln(p, onoffp );
  writeln(p, conval );
end;

PROCEDURE textfset;
begin
  word2( setsym, textfsym );
  writeln(p,' ON : incoming and outgoing files will be treated as UCSD');
  writeln(p,'      textfiles and the 8th bit of each character is masked.');
  writeln(p,'OFF : incoming and outgoing files will be treated as UCSD');
  writeln(p,'      datafiles and the 8th bit of each char. is not masked.');
  writeln(p,'UCSD data & code files can thus be transfered only if both');
  writeln(p,'sides are set to 8-bit word length, no parity and if the 8th');
  writeln(p,'bit is not altered during transmission.');
  writeln(p, ftval );
end;

PROCEDURE timoutset;
begin
  word2( setsym, timeoutsym );
  writeln(p,'Time-out period specified to host in approx. seconds (1..31).');
  writeln(p,'( Note : some host KERMITs do not take this parameter and');
  writeln(p,'         just keep waiting.)');
  writeln(p, numpar );
  writeln(p, ftval );
end;

PROCEDURE maxpackset;
begin
  word2( setsym, maxpsym );
  writeln(p,'Sets this side''s maximum KERMIT package length ( 20..94 ).');
  writeln(p,'Reduce package length on noisy lines.');
  writeln(p, numpar );
  writeln(p, ftval );
end;

PROCEDURE xoffset;
begin
  word2( setsym, xoffsym );
  writeln(p,'A Xoff/Xon protocol is used during ',vocablist[consym],
             ' when a screendump to the printer');
  writeln(p,'is requested.');
  writeln(p,'Set Xoff & Xon  according to the requirements of the host.');
  writeln(p,'( Note : at some hosts the Xon/Xoff char''s should first be');
  writeln(p,'         defined by a terminal definition command. )');
  writeln(p, charpar );
  writeln(p, dumpval );
end;

PROCEDURE xonset;
begin
  word2( setsym, xonsym );
  writeln(p,'See ', vocablist[setsym],vocablist[xoffsym] : 11, '.');
  writeln(p,'( Note : if IBM flag is on this character is also used in the');
  write(  p,'         file-transfer protocol. It should then be set to ');
  write_ctl( chr(17) ); writeln(p,' )');
end;

PROCEDURE xoffwset;
begin
  word2( setsym, xoffwaitsym );
  writeln(p,'If characters are lost during a screendump to the printer then');
  writeln(p,'increase this parameter.');
  writeln(p, numpar, ' (1..255 )');
  writeln(p, conval );
  writeln(p, dumpval );
end;



(*************** This procedure list all SET subcommands  ****************)


PROCEDURE allset;
begin
  page( output );
  word1( setsym );
  writeln(p,'To establish system dependent parameters.');
  writeln(p,'The ', vocablist[ setsym ], ' options are as follows :');
  writeln(p);
  baudset;
  wait;
  debugset;
  delset;
  wait;
  emulset;
  eolnset;
  escset;
  wait;
  filewset;
  ibmset;
  wait;
  localset;
  maxpackset;
  wait;
  maxtryset;
  nofeedset;
  wait;
  parset;
  prefixset;
  wait;
  rejset;
  stopbset;
  wait;
  textfset;
  wait;
  timoutset;
  wordlset;
  wait;
  xoffset;
  xonset;
  wait;
  xoffwset;
end;


(*********** This procedure explains the SET command ********************)


PROCEDURE helpset;

begin
  case adj of
    nullsym       : allset;
    baudsym       : baudset;
    debugsym      : debugset;
    delsym        : delset;
    emulatesym    : emulset;
    eolnsym       : eolnset;
    escsym        : escset;
    filewarnsym   : filewset;
    ibmsym        : ibmset;
    localsym      : localset;
    maxpsym       : maxpackset;
    maxtrysym     : maxtryset;
    nofeedsym     : nofeedset;
    paritysym     : parset;
    prefixsym     : prefixset;
    rejectsym     : rejset;
    stopbsym      : stopbset;
    textfsym      : textfset;
    timeoutsym    : timoutset;
    wordlensym    : wordlset;
    xoffsym       : xoffset;
    xonsym        : xonset;
    xoffwaitsym   : xoffwset;
  end;  { case }
end;   {  helpset }



(**************** This procedure shows all valid HELP commands ************)


PROCEDURE helpall;

begin
  page( output );
  introkermit;
  helpconn;
  wait;
  helpdir;
  helpexit;
  helphelp;
  wait;
  helprec;
  helpsend;
  helpshow;
  wait;
  helpset;
end;


(********************* Finally here starts procedure HELP  ****************)


begin   {  help  }
  close(p);
  if pr_out and print_enable then reset(p, pr_file )
                             else reset(p, cs_file );
  writeln(p);
  case noun of
    nullsym              :  helpall;
    setsym               :  helpset;
    showsym, pshowsym    :  helpshow;
    dirsym , pdirsym     :  helpdir;
    helpsym, phelpsym    :  helphelp;
    exitsym, quitsym     :  helpexit;
    recsym               :  helprec;
    sendsym              :  helpsend;
    consym               :  helpconn;
  end;  {  case  }
  writeln(p);
  pr_out := false;
end;   {  help  }
 
 

begin   {  unit  helper  }
end.