home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / system / askenv / askenv.doc < prev    next >
Text File  |  1995-02-27  |  11KB  |  399 lines
  1.  
  2.     AskEnv 2.5                                             23-Mar-93
  3.     ==========
  4.  
  5.  
  6.     What is AskEnv for?
  7.     -------------------
  8.  
  9.  The only way for a shell script for input is the rather limited ASK
  10.  command. Since Commodore released the new OS2 ARexx is a part of the
  11.  operating system. This programming language is missing a powerfull
  12.  user interface too! It is a language ported from IBM mainframes
  13.  using page based alpha terminals.
  14.  
  15.  AskEnv imports the capabilities for user friendly in whatever
  16.  programming language you want to use. ARexx-programs, shell-scripts,
  17.  Superbase DML-programs and all other languages which can start an
  18.  external program and read a file can now use system-, file- and
  19.  user defined requesters.
  20.  
  21.  AskEnv requires at least OS 2.04.
  22.  
  23.  
  24.     Usage:
  25.     ------
  26.  
  27.  Running AskEnv from WorkBench is useless. The CLI syntax is (or ARexx,
  28.  Superbase...):
  29.  
  30.  AskEnv [EOL/S,F=FREQ/S,DEF/K,SBMODE/S,S=SREQ/K,BODY/K,NEG/K,POS/K,GADFILE/K]
  31.  
  32.  AskEnv is pure and can be made resident.
  33.  
  34.  
  35.     Functions
  36.     =========
  37.  
  38.  There are two classes of functions: first, simple commands in a single
  39.  command line. Second, we have only one complex function: with the help
  40.  of a configuration file, it can construct free definable requesters.
  41.  
  42.  
  43.     Simple Functions
  44.     ----------------
  45.  
  46.     Read Line
  47.     ---------
  48.  
  49.     AskEnv [>file] [EOL]
  50.  
  51.  Reads a line from keyboard until it recieves an End of Line and then
  52.  writes everything into standard output. The option EOL adds a End of
  53.  Line on the output.
  54.  
  55.  
  56.     File Requester
  57.     --------------
  58.  
  59.     AskEnv [>file] FREQ title [DEF path] [DIR] [SBMODE] [EOL]
  60.  
  61.  calls a file requester, the ASL or whatever you patched to use instead.
  62.  With DEF you can set the initial path to the directory or file you want
  63.  to show in the file req. DIR limits the requester to show only directories.
  64.  
  65.  WARNING: If started from SBPro, you must use the SBMODE option. Otherwise
  66.  the requester will hang dead, and so will SBPro. This is a bug in SBPro:
  67.  It doesn't like a view on its window to determine the screen it is
  68.  running on.
  69.  
  70.  
  71.     System Requester
  72.     ----------------
  73.  
  74.     AskEnv SREQ line1 [BODY line2] POS posiButton [NEG negaButton]
  75.  
  76.  If the user selected the negative text, a WARN returns.
  77.  
  78.  
  79.  
  80.     Complex Requester Functions
  81.     ---------------------------
  82.  
  83.  With "AskEnv gadfile <file>" the program reads a config file, an unstrucured
  84.  ASCII file with keywords. The elements can be distributed over lines at 
  85.  will.
  86.  
  87.  Strings must reside on one single line and be enclose by " ", if they
  88.  contain spaces.
  89.  
  90.  A ";" makes the rest of the line a comment. Keywords  must be written in
  91.  capitals.
  92.  
  93.  
  94.     IMMEDIATE vs SELECT-Mode
  95.     ------------------------
  96.  
  97.  Depending on the definition of the gadgets, AskEnv selects a mode to act:
  98.  
  99.     IMMEDIATE    Requester disappears after the first input;
  100.             the ID of the selected gadget is written into the
  101.             file VAR mentioned in the header. If no name is
  102.             given, the variable "AskEnv_Button" is used.
  103.             The ID of the button is the number in order of
  104.             definition, starting with 1.
  105.  
  106.     SELECT        resides until a END, CANCEL or the close gadget has
  107.             been selected. Then writes the conditions of all
  108.             gadgets.
  109.  
  110.     The close gadget always returns a WARN, nothing will be written.
  111.     Values of result variables are therefore undefined! Usually, they
  112.     have the same value as before, but these could have been changed.
  113.  
  114.  The mode will be selected automatically:
  115.  
  116.     Button only will be treated as IMMEDIATE. Adding a not-button
  117.     switches to SELECT. Not-buttons are also the filereq and the
  118.     program start buttons.
  119.     Elements with read only have no effect.
  120.  
  121.  
  122.     Configuration File
  123.     ------------------
  124.  
  125.  The file has a header and n gadget definitions. The header contains the
  126.  global attributes:
  127.  
  128. WINDOW        : this must be the first keyword
  129.  
  130. SIZE x y w h    : separated by spaces; I'm not responsible for usefull
  131.           coordinates.
  132.  
  133. As an alternative use:
  134.  
  135. CENTER w h    : centers the requester on the screen.
  136.  
  137. NAME name    : window title, optional
  138.  
  139. SCREEN name    : set name to the name of a public screen, and AskEnv will
  140.           open the new requester on this screen. If this public
  141.           screen doesn't exists, it will fall back to the default
  142.           public screen, usually the workbench screen.
  143.  
  144. VAR name    : In IMMEDIATE mode, ie. if only buttons are present,
  145.           this variable contains the number of the selected button.
  146.  
  147.           In SELECT mode, it contains the number of the selected
  148.           button, but only if the button has the keyword GLOBAL!
  149.           GLOBAL can be used without a variable name, but then it
  150.           must not be placed in front of the delimiting "#".
  151.  
  152.           Without a VAR definition, the variable "AskEnv_Button" will
  153.           be used.
  154.  
  155.  
  156.  Important: starting with version 2.4, VAR no longer defines a file to 
  157.  contain all variables. This was a relict from early days, and no one used it
  158.  later. If needed, I can implement it again.
  159.  
  160.  
  161.  After the header the gadget definitions:
  162.  
  163.  A gadget starts with a keyword and ends with a " #" (as in MountList).
  164.  Currently these gadget types are supported:
  165.  
  166.     BUTTON        various functions
  167.     CHECKBOX
  168.     INTEGER
  169.     NUMBER        read only
  170.     CYCLE
  171.     STRING
  172.     MX
  173.     TEXT        read only
  174.  
  175.     HIBOX        raised box
  176.     LOBOX        recessed box
  177.  
  178.  Button and string gadgets can be combined to serve as file request call.
  179.  A button can also call a program.
  180.  
  181.  
  182.     Functions for all Gadgets:
  183.     --------------------------
  184.  
  185. POSITION x y w h: must be used with every gadget. Minimal height depends
  186.           on screen font height.
  187.  
  188. LABEL text    : gadget text, by default IN the gadget box, can be set with
  189.  
  190. PLACETEXT loc    : ABOVE, BELOW, LEFT or RIGHT
  191.  
  192. END        : selection terminates the requester. Can be used more than
  193.           once.
  194.  
  195. CANCEL        : Nothing will be written.
  196.  
  197. GLOBAL var
  198.  LOCAL var    : the value will be written in this either local or global
  199.           (ENV:) variable. What exactly will be written depends on
  200.           the gadget type.
  201.  
  202. ENTRY        : must be the last keyword of a gadget, if used. Followed by
  203.           1 to n entries, depending on gadget type.
  204.  
  205.  
  206.     Type Specifics:
  207.     ---------------
  208.  
  209.     BUTTON
  210.     ------
  211.  
  212.  In IMMEDIATE mode, returns the number of the button into the global variable
  213.  defined in the header. Count only buttons and in order of definition!
  214.  In SELECT mode, its number is written into the variable "AskEnv_Button". Use
  215.  the keyword GLOBAL followed by a dummy variable name.
  216.  
  217.  
  218.     Specific Functions for BUTTONs:
  219.  
  220. FREQ        : The next gadget must be a string gadget definition, which
  221.           may contain a default path as ENTRY. Pressing the
  222.           button activates a file requester. The selection appears
  223.           in the string requester.
  224.  
  225. DIR        : Additional option for the file requester: limits the
  226.           requester to show only directories. May not work with every
  227.           ASL file requester replacement (i.e MFR).
  228.  
  229. SYNCRUN        : Modal execution of external programs. The string after the
  230.           keyword will be executed as program. AskEnv interrupts all
  231.           input until the program terminates. If the command contains
  232.           options or arguments separated by spaces, enclose it in
  233.           quotation marks.
  234.  
  235.           If a non 0 error code returns, you can use this value:
  236.  
  237. WARN limit    : the number limit sets the maximum return code which will
  238.           not generate a warning. AskEnv will continue to process
  239.           the current requester. If the return code is greater than
  240.           limit, a requester opens containing a option to end
  241.           AskEnv. It then returns a code of 10.
  242.  
  243. ASYNCRUN    : The same as SYNCRUN, but non modal. The new process is
  244.           independant and AskEnv ready for further input.
  245.  
  246. FILE filedef    : an optional output file for the asynchron started program.
  247.           i.e. NIL:, RAM:test or a CON: window.
  248.  
  249.  
  250.  Before a external program (either synchron or asynchron) is actually 
  251.  started, the values of all gadgets are written in their variables. The 
  252.  external program may use these values for further processing.
  253.  
  254.  These values can be used immediately by AskEnv: SYNCRUN and ASYNCRUN
  255.  commands may contains variables. The definition
  256.  
  257.     STRING ...
  258.      LOCAL myDir ...
  259.  
  260.     BUTTON ...
  261.     SYNCRUN "dir $myDir"
  262.  
  263.  tries to read the contents of the string gadget as a directory.
  264.  
  265.  
  266.     CHECKBOX
  267.     --------
  268.  
  269. CHECKED        : start in selected state
  270.  
  271.  A CHECKBOX returns 0 if selected, -1 otherwise.
  272.  
  273.  
  274.     INTEGER
  275.     -------
  276.  
  277.  After ENTRY you can set a default number to appear after startup. With
  278.  "MAXCHARS number" you set the upper limit of characters the gadget
  279.  may contain (default 20).
  280.  
  281.  
  282.     NUMBER
  283.     ------
  284.  
  285.  Like INTEGER, but read only. Nothing will be written. With NOBOX you
  286.  can suppress the border.
  287.  
  288.  
  289.     STRING
  290.     ------
  291.  
  292.  Similar to INTEGER, with the same option MAXCHARS (default 80).
  293.  
  294.  
  295.     TEXT
  296.     ----
  297.  
  298.  Like NUMBER.
  299.  
  300.  
  301.     CYCLE
  302.     -----
  303.  
  304.  List the desired entries after the keyword ENTRY. The number of the
  305.  selected entry will be written starting with 0.
  306.  
  307.  Remember: ENTRY must always be the last keyword!!
  308.  
  309.  
  310.     MX
  311.     --
  312.  
  313.  This gadget type will be handles like the CYCLE gadget above. There is
  314.  another option:
  315.  
  316. SPACING n    : additional spacing between the knobs
  317.  
  318.  
  319.     HIBOX, LOBOX
  320.     ------------
  321.  
  322.  BE AWARE: no end sign #, only 4 parameters x, y, width, height:
  323.  
  324.     HIBOX
  325.     50 20 100 20
  326.  
  327.  
  328.  
  329.     And now the Rest:
  330.     -----------------
  331.  
  332. The distribution pack must contain:
  333.  
  334.      LACE (dir)
  335.        About.req                        intro.req
  336.        Offset.req                       Select.req
  337.        Strings.req                      warning.req
  338.      HIRES (dir)
  339.        about.req                        intro.req
  340.        Offset.req                       Select.req
  341.        Strings.req                      Warning.req
  342.   AskEnv
  343.   AskEnv.doc
  344.   AskEnv.dok
  345.   Brief.rexx
  346.   BriefHilfe.req
  347.   Changes.doc
  348.   Changes.dok
  349.   dearc.req
  350.   DeArc.rexx
  351.   LiesMich
  352.   Plotter                          Plotter.info
  353.   PrefMan.rexx
  354.   ReadMe
  355.   Test
  356.  
  357.  
  358.     To Do:
  359.     ------
  360.  
  361. - AREXX support
  362.  
  363.  
  364. Thanks to all the people which helped with tips and tricks.
  365.  
  366.  
  367. Starting with V2.4, AskEnv has been tested with MungWall and Enforcer.
  368. This wasn't a real obstacle because AskEnv was written with M2Amiga
  369. Modula2.
  370.  
  371. It has been tested under OS 2.04 and OS 2.1.
  372.  
  373.  
  374. This program may be freely distributed, but the above mentioned files must be
  375. be included in the distribution.
  376.  
  377. It may not be sold on public domain disks which cost more than 5 sFr/DM. If
  378. a disk is sold for more than this price, please contact me.
  379.  
  380. If you intend to publish AskEnv on collection which will be distributed with
  381. printed manuals, you must contact me first.
  382.  
  383. All rights reserved.
  384.  
  385.  
  386.  
  387. Send bugreports to:
  388.  
  389. ===========================================================================
  390.                               Bengt Giger
  391.                             Schmiedgasse 48
  392.                           CH-8640 Rapperswil
  393.                               Switzerland
  394.                               055/27 98 79
  395.  
  396.   Link-CH1 ++41 (0)61 681 63 60      Aminet: B.GIGER%LINK-CH1 44:8010/408.0
  397.                                  Z-Netz: B.GIGER@LINK-CH1
  398. ===========================================================================
  399.