Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/465.lha/ParM_v2.5r/ParM.docE

Text File | 1991-01-05 | 21KB | 481 lines

Documentation for ParM


ParM stands for Parametrable Menu.

ParM  allows  you to build your own menus in order to run all the programs
you  can  have  on  one ore more disks.  This is very useful for hard disk
owners  who  have  programs deeply enclosed in subdirectories.  With ParM,
you  can run them without going through directories under either WorkBench
or CLI.
With  ParM,  you  can start programs in either WorkBench or CLI mode.  The
advantage  of  WorkBench mode is that the default directory of the program
you run is the one in which the program file is.  But not all programs can
be run in this mode.


Building:

    ParM  was  made using AztecC 5.0a, CygnusEd release 2, and ARexx 1.10.
    File  headers  are done in such a way compilation can be launched from
    Ced.  I use my own DevKit, completely rewritten since the original 1.2
    version of the DevKit wasn't working at all.

    ParM  needs arp.library version 39 and req.library version 1.  I wrote
    my  owns libraries for the Manx linker.  The ones used here are called
    arps.lib  and req.lib.  The arps.lib provides a small startup code and
    glues  for arp functions that cannot be prototyped, and the req.lib is
    the reqglue.o given with CygnusEd rewriten as a library.


Installation:

    Put  ParM  with  its  icon wherever you want, and just put the default
    config  file  "ParM.cfg"  in  S:  if you use it.  If you don't, you'll
    have  to  specify  the  config file in the command line or in the tool
    types  of  the  icon, otherwise, you will have to cancel the requester
    and  won't  have  any  menus.   Make sure you have arp.library 39.1 or
    higher and req.library in your LIBS: directory.


Running:

    It  is  recommended  to run ParM from CLI if you want your programs to
    have  a default path other than the current directory and C:  which is
    the case if you start it from WorkBench.

ParM can be run in two ways.
1)  You  can  attach  ParM to the CLI you are using.  In this case, if you
    don't specify any of the window options, the menus will be attached to
    the  CLI  window  you  start  it  from.  You may then only "Run" it to
    prevent you from closing the CLI.

2)  ParM can have its own window.  This is allways the case when it is run
    from  WorkBench, but you can also tell it to open it's own window when
    run  from  CLI  using  "-w"  option or any of the window options.  You
    should then "RunBack" it to be able to close the CLI later.  Don't use
    arp ARun with NOIO because some programs don't like it, and those will
    not run from ParM.
    Warning: you shouldn't run ParM with "Run >NIL: ParM" because it would
    be detached from the CLI but still keep the console for  it's  default
    input and output file handles and some commands in RUN mode may  crash
    if you 'EndCLI' before.
    Note  that  RunBack use the C:Run command and you should place the arp
    version  of  the  Run command of your C:  directory if you want to use
    ParM as resident.

    ParM  have  some  options  which  are  available  for most either from
    WorkBench or from CLI.  Two of them are only available from CLI.  "-w"
    since  ParM  allways  open  its own window when run from WorkBench and
    '-o' because it is the default when run from WorkBench.

    Option list:

    CLI        WB

    -w      (CLI only)  Open its own window rather than taking CLI's one.
    -x      LEFTEDGE    Left edge of ParM Window (default 0)
    -y      TOPEDGE     Top edge of ParM Window (default 0)
    -d      DETAILPEN   Detail pen of ParM Window (default 3)
    -b      BLOCKPEN    Block pen of ParM Window (default 2)
    -c      MENUCOLOR   Color for ParM's main menu (default: Detail Pen)
    -r      NODRAGBAR   No drag bar (You can't move ParM), =1 to activate
    -l      LITTLE      No depth gadget, =1 to activate
    -s      STACKSIZE   Default stack size for commands (not parm's stack)
    -f      CONFIGFILE  Configuration file.
    -o                  Redirect output to NIL: for commands in RUN mode.

    -h or anything else to get help when run from CLI.

    To  use  workbench tool types, just use the keyword followed by an "="
    and the value needed.  For example

        DETAILPEN=1

    this is equivalent to

        RunBack >NIL: ParM -d1    when run from CLI.

    if you specify any of the -x,-y,-d,-b,-l,-r options when run from cli,
    a window will be open and -w option is useless.


Configuration file:

    You  will  best  understand what follows if you have in front of you a
    printout of the config file supplied.

    A  configuration  file  looks  like  a structured program.  You should
    indent your lines to make the file as readable as possible.

    The  default  configuration file should be in the S:  directory and be
    named ParM.cfg.

    The  configuration  file defines the menus you want, and what commands
    they will run.  Comments begin with a #, and continue until the end of
    the line.  Upper and lowercase do not make a difference.


    Key words:

    CMDWIN  console_name

        This  will  override  the  default console used for Command output
        which is "CON:0/11/640/100/Command Window".  This should be placed
        anywhere in the file but better be at top of it.

    SHELLWIN  console_name

        This  will  override  the  default console used for SHELL commands
        which  is  "CON:0/11/640/100/ParM Shell".    This should be placed
        anywhere in the file but better be at top of it.

    SHELLCMD  command

        This   will  override  the  default  command  used  to  create  an
        interactive  shell,  which  is  AShell.   For  example, if you own
        WShell,  you  can use NewWSH here.  This should be placed anywhere
        in the file but better be at top of it.

    WAITCMD  command

        This  will  override  the  default command used to wait for a user
        input  telling  to  close  the shell (default:  WaitReturn).  This
        should be placed anywhere in the file but better be at top of it.

    TMPDIR  path

        This  will  override  the  default  temp  directory used for SHELL
        scripts  which  is T:.  If your directory isn't in the root of the
        device,  that is to say the dir name doesn't end with a colon (for
        example  T:),  you  must  append a slash '/' to your dir name (for
        example  RAM:T/).   This should be placed anywhere in the file but
        better be at top of it.

    COLOR n

        This  will  set  the  foreground pen color for new items.  You can
        change this as often as you want.  The arguments is the pen number
        to  use.   The  default  is  window  detail pen.  If the color was
        window  block pen, the item would be invisible, in this case, ParM
        replaces the color with window detail pen.

    MENU menu_name

        Creates  a  new  menu.   Each  menu must have at least one item or
        submenu.

    SUBMENU submenu_name

        Creates  a  new submenu.  Each submenu must have at least one item
        and can't have submenus.
        Each SUBMENU must end with an ENDSUBMENU

    ENDSUBMENU

        See SUBMENU.

    ITEM [{command-char}] item_name command_def

        Defines  a  new  menu  item.   Each  item  definition must have an
        item_name  and  an associated command.  Each item is linked to the
        current  menu  or  submenu.  An ENDSUBMENU statement tells ParM to
        attach  next  items to the current menu rather than to the current
        submenu.   If  any of the menu, submenu and item names may contain
        whitespaces.   In this case, enclose the name in double quotes.  A
        command  character may be defined for the menu item by putting the
        character  after  the  ITEM  keyword  and  surround  it with {}'s.
        Command syntax is decribed below.

        command_def

            Programs  can  be run in four ways:  ARUN, RUN, SHELL, and WB.
            For  all modes, STACK and PRI are optionnal.  If STACK is less
            than  4000  bytes, or if no stack is specified, the stack will
            be  set to the ParM task Stack.  that is to say the stack size
            at  time  ParM  was  run.   There's  an exception:  If ParM is
            resident, ParM stack will allways be 4000 bytes.


            1) ARUN syntax

            ARUN [WIN console_window] [STACK n] [PRI n] command [args]

            This  mode should be used for most of your needs.  The console
            window  is  now optionnal.  This is a CreateProc() style mode.
            Some  programs  don't  like  it,  but  there is not many.  For
            example  scripts  cannot  be executed.  As a general rule, you
            shouldn't  use  this  mode  for commands of the C:  directory.
            Use  RUN  instead.   This mode has the same limitations as the
            arp ARun command.  Actually, the console is immediately closed
            after  the  program  ends.   We  hope  to  fix  this in future
            release.   For example, I use this mode to Format my floppies,
            and  I  see  in  a little window the format process.  Commands
            cannot be redirected in this mode.
            Note: The ARUN mode with a console (ARUN WIN console)  is  the
            same as the old CLI mode. So, you can do a search/replace with
            your  favorite  editor to  update  your  old  config file to a
            version >= 2.2 of ParM. ( CLI ==> ARUN WIN )


            2) RUN syntax

            RUN [STACK n] [PRI n] command [args]

            This  mode  creates  a  background shell.  This mode should be
            used for scripts.  If the bit s of your script file is set, it
            is  automaticaly sourced (No need of the execute command).  In
            this mode, commands won't be detached if ParM is attached to a
            CLI,  this  is  why  you  should use the ARUN mode as often as
            possible.  Redirection can be done in this mode.


            2) SHELL syntax

            SHELL [WIN console_window] [STACK n] [PRI n] command [args][;command [args]]...

            This  mode  creates an interactive shell.  This mode should be
            used for scripts that needs input from the user.  If the bit s
            of  your  script  file  is set, it is automaticaly sourced (No
            need  of  the execute command).  One more feature of this mode
            is   that  you  can  specify  several  commands  separated  by
            semicolons,  ie:  CD SYS:Utilities;Dir In fact, ParM creates a
            script  file in a temporary directory which is T:  by default.
            So  you  can  make  a  real script file.  Type it normaly, and
            then,  put  a  semicolon at each end of line, and join all the
            lines.   You  can  then submit this line to ParM as a command.
            If  a  command  needs  a  semicolon,  you can put it after the
            override  char  '\'.   Usualy, semicolons are taken as comment
            delimiters.   If  no  console  is  specified,  a  parametrable
            default console will be used for the shell.


            4) WB syntax

            WB [STACK n] [PRI n] command

            Execute  command  in WorkBench mode.  No arguments are allowed
            in  this  mode.  Warning:  If STACK is specified here, it will
            override the stack specified in the icon of the command.  Your
            command may crash if you ask a smaller stack than in the icon.
            Do it at your own risk.


            5) CFG action

            CFG ConfigFile

            ParM  loads  the  new  ConfigFile like ParM->Open in the Menu.
            Very  usefull  to  use different cfg file on different disk to
            choose programs on this disk.


    For  all  modes but WB, your command is searched first in arp resident
    list  and  then in CLI Path at time ParM was run.  To know the path in
    which  ParM  search  its  commands, just issue the Path command in the
    requester of ParM Command command, or open a newcli or shell from ParM
    and issue the Path command.

    A config file is given with ParM as an example.


ParM commands:

    Open:       Pops up a requester asking to select the new config file.
    UpDate:     UpDate the menu reloading the config file.  Usefull if you
                modify the config file while ParM is running.
    Std Cfg:    Load   the   standard   'S:ParM.cfg'  configuration  file.
                Usefull  to  return in your favorite cfg when you are lost
                in one disk cfg.
    Cmd Mode:   Two  modes  are available.  Simple and Shell.  The current
                mode  is  checkmarked.   This  modes  are  for the Command
                command  (see below) In 'Simple' mode, ParM will stay busy
                while your command isn't finished, where as in Shell mode,
                Command is asynchronous.  To do that, an interactive shell
                is  created,  and  your(s)  command(s)  is  (are) put in a
                startup  file.   There is an (s) because in this mode, you
                can  put  several  commands  separated by semicolons. Same
                rules as SHELL mode in config file.
                If you own WShell and use PatchDOS, you will  have  access
                to all WShell facilities. (alias, residents commands...).
    Command:    Allows you to execute a single CLI command.
    Change Dir: Changes ParM current directory.  Commands run in all modes
                but WB will inherit ParM current directory.
    Quit:       Why? You don't like it!


Separated commands:

  End:

    The  End command can now close a CLI in which a ParM is attached.  End
    needs  EndCLI  to  work.  If there is no ParM attached to the CLI, End
    will  only  do  an  EndCLI.   End  and EndCLI can be made resident for
    maximum  speed.   You  can for example put ParM in your CLI-Startup or
    Shell-Startup  to  have  menus in all of your CLI/Shells and you'll be
    able  to  leave them with the End command without worrying about ParM.
    Don't use this command in a WShell since it loads EndCLI from disk and
    WShell only accept its built in EndCLI command.


  ParMCD:

    The  ParMCD  change  the  current directory of the ParM attched to the
    current  cli window.  Without argument, ParM will take the cli current
    dir.  Otherwise, you can specify a directory as an argument to ParMCD.


  WaitReturn:

    The  WaitReturn is used by the Command command if in Shell mode.  This
    one  can  also  be made resident.  You can use it in your scripts.  It
    just wait for the user to hit return.


Limitations:

    Scripts won't run in ARUN mode, use RUN or SHELL mode instead.

    If  a  command  in  RUN or SHELL mode can't be started, you will never
    know, except you won't see it working.

    When  attached  to  a  CLI,  commands  executed  in  RUN mode won't be
    detached,  which  means that you won't be able to close the cli before
    those  commands  end.  This is the same problem as if you had run your
    command in a CLI with
            1> Run mycommand
    By  the  way,  theses  commands will have their output file handles in
    this  window, and advantages can be taken from that.  You can redirect
    these to NIL: or use -o option to avoid trashing of your cli window.

    ParM  can  be  made  resident only with the arp ARes command.  Because
    ParM is not really pure, when it is resident, ParM duplicates its data
    and bss.  Only arp make it possible to know if we are resident or not,
    and  then,  ParM  will never copy its data if it is made resident with
    the  commodore  method.   So  I allways use the arp Run command to run
    parm  since  the  arp  Run first searches commands in the arp resident
    list.


Known bugs:

    Specified PRI in SHELL mode isn't used. Pri is allways 0.
    Some commands won't run in RUN mode and some other won't in ARUN.  But
    I've never found one that won't run in either of these. ???


Future plans:

-   Decrease code size under 2 K !!!
-   I  have  a  big  project that may provide a solution to have access to
    ParM menus without having to activate ParM's little window...
-   Make  another  version  that doesn't use req.library for poor users of
    floppies only.


Release notes:

    1.0:    Internal. Major MyMenu rework.

    1.1:    First official release. (Sent to Fred Fish)
            Old CLI option changed to RB (stands for RunBack).
            New CLI option added.
            Config file syntax changed. (Old was MyMenu's one).

    1.4:    Internal. Option -l -d and WBRun enhanced.
            Now you can run projects icons which have no file. For example
            Serial, Pointer and Printer in the Prefs drawer.

    1.6:    Second official realease. 29/09/90
            Code Cleanup
            New CFG option added.
            New 'Std cfg' menu added.

    1.7:    Internal
            No more uses c16.lib, but use my owns instead.
            Code size about 1.5K smaller.

    2.0:    Third Official release. 13/10/90.
            ParM can now be made resident.
            End command created.
            Directory path string built in 'Change Dir'.

    2.1:    ParMCD command created.
    2.1r:   This version uses the great req.library (r for req!)

    2.2r:   No more RB and CLI modes. New modes are ARUN, RUN, and SHELL.
            STACK and PRI available in all modes but WB now.
            No more need of the Run command in your C: directory.
            Syntax errors in config file will now be reported with a line
            and char number.

    2.3r:   You will never see again 'Workbench processes still active'.
            ParM now creates a public MsgPort to handle workbench replies
            and leave it if there's still messages to be replied.
            Now, if your console has a close gadget, ParM will end if you
            hit it. This is usefull for lucky owners of WShell.
            Characters of ascii value over 127 now supported. (accents)
            WAITCMD added.

    2.4r:   WB mode rewriten. STACK and PRI available in all modes now.
            WB mode no more crashes if command not found. You can now run
            tools that haven't an associated icon.
            Memory for menus items is allocated by 1 K blocks to decrease
            fragmentation.

    2.5r:   -s and -o option added.
            -s (stack) is specially usefull when ParM is resident  because
            in this case ParM stack is allways 4000 bytes whereas it takes
            the default stack size of your cli when it is not resident. As
            all commands run from ParM take as default the ParM stack size
            you can specify a higher stack with this option.


Acknowledgements:

    The  first  release (internal) of ParM was a major rework of MyMenu by
    Darin Johnson.  The problem was that it wasn't possible to have MyMenu
    without workbench, and program started from MyMenu didn't have a Path.

    So, lots of thanks to Darin Johnson for menu allocations and workbench
    run.  The idea of attaching menus to the CLI and some other ideas came
    from a friend who also made a menu but wasn't easy to configure.

    Great thanks to Olaf 'Olsen' Barthel for his update of arp startup for
    manx 5.0, the code from which I made my own libs.

    Thanks  also  to  Colin  Fox  and  Bruce  Dawson  for  their fantastic
    req.library.   We  encourage  every  programmers  to  use  it.   Every
    professionnal  software  producers  should at least have a look at the
    file requester.

    Thanks to William S. Hawes for ARexx and WShell.
    Thanks to Pierre Ardichvili for his help to me and to Amiga.
    Thanks to CygnusSoft and ASDG for their GREAT CygnusEd 2.


Signature:

    S.R. & P.C.
    This is not Status Register and Program Counter but
    Sylvain Rougier & Pierre Carrette.
    We are Frenchies so we hope the documentation is readable.  We put our
    work  in  making english language comments, but it isn't allways easy,
    so be fair with us.


Donations:

    This  program is not public domain.  This program is BeerWare.  If you
    use  it  or  if  you want the last revision, send a box of beer and/or
    bugs report to:

        Sylvain Rougier
        Coiffure W
        39 rue Carnot
        86000 Poitiers
        France.