home *** CD-ROM | disk | FTP | other *** search
/ Frozen Fish 1: Amiga / FrozenFish-Apr94.iso / bbs / alib / d8xx / d827 / askreq.lha / AskReq / AskReq.doc < prev    next >
Text File  |  2001-02-25  |  9KB  |  274 lines
  1.  
  2.  
  3.                                Documentation
  4.  
  5.                                 AskReq 1.00
  6.  
  7.                      (c) and written 1992 H.P.G FreeWare
  8.  
  9.  
  10.  
  11. Index:
  12.         Index
  13.         What is AskReq
  14.         System Requirements
  15.         Legal Stuff
  16.         Starting AskReq
  17.         Cli Arguments
  18.         Examples
  19.         Technical
  20.         Address
  21.         List Of Files
  22.  
  23.  
  24. What is AskReq:
  25.  
  26.     AskReq is another batch requester tool. You will ask, why just another
  27.     requester tool. AskReq can ask the user to put in not only a okay or
  28.     cancel statement. You can also ask the user to give you text or integer
  29.     information. The results can be easily used in any kind of batch files.
  30.     It is nearly the same like the requester functions in the rexxarp.-
  31.     library. But it uses only OS 2.0 functions.
  32.  
  33. System Requirements:
  34.  
  35.     AskReq needs at minimum OS 2.04 (37L) to run.
  36.  
  37.  
  38. Legal Stuff:
  39.  
  40.         This  program  and  all files come with it, also the docfiles, are
  41.         released as FREEWARE.
  42.  
  43.         this means:
  44.  
  45.             everybody may use AskReq,
  46.  
  47.             everybody may copy AskReq, if:
  48.  
  49.                 1. You copy all included files, see list at the end of the
  50.                    doc file.
  51.                 2. No changes are made,  this  means  the  program and all
  52.                    included files must stay in the original form.
  53.                    Exception: you  may  archieve  it; but in this case you
  54.                               must also archieve the whole package.
  55.                 3. If  you  recompile  it, you have to include a notice to
  56.                    the original author. If you also want to (re)distribute
  57.                    in any new form you have to send me a copy.
  58.                 4. You may not sell AskReq.
  59.                    Execption: you`re  allowed  to  take  a  small copy fee
  60.                               which should not extend 5 US$.
  61.                 5. If you want to include AskReq or  one  of  the included
  62.                    files as a part of a commercial package, you must  have
  63.                    written  permission from the author (address see below).
  64.  
  65.  
  66.         I take no warranty or guaranty for the function of this program.
  67.         The whole risk of using AskReq stays only by the user.
  68.  
  69.  
  70. Starting AskReq:
  71.  
  72.     AskReq can only be started from CLI. No wbench support at this time.
  73.     Alternatively you can of course use tools like XIcon or IconX to run
  74.     AskReq or use the `Execute Command ...` menu of your WBench or set the
  75.     tooltype CLI.
  76.  
  77.  
  78. Cli Arguments:
  79.  
  80.     If you start AskReq from CLI, it uses the following commandline
  81.     syntax:
  82.  
  83.     Usage: AskReq [Hail=H/K]<Message=M/K>[Pos=P/K][Neg=N/K][GadgetText=G/K]
  84.                   [STRING=S/K][INT=I/S][TimeOut=T/K/N]
  85.  
  86.     with:
  87.  
  88.     Hail
  89.  
  90.         This is the title of the requester. If this arguments is omitted the
  91.         requester uses as default: `Ask Requester ...`
  92.  
  93.     Message
  94.  
  95.         This argument must be given. All others can be omitted. This
  96.         specifies the message you want give to the user. This may include
  97.         text for up to 4 lines. Each line is seperated by a `|`. If the text
  98.         contains spaces you must embedded the text in ""`s. There exists no
  99.         default Message.
  100.  
  101.     Pos
  102.  
  103.         This is the gadget text of the positive(left) gadget. If you specify
  104.         Pos this informs AskReq that you want to have a positive gadget. If
  105.         you doesn`t specify it no positive gadget will be displayed.
  106.  
  107.     Neg
  108.  
  109.         This is the gadget text of the negative(right) gadget. If you specify
  110.         Neg this informs AskReq that you want to have a negative gadget. If
  111.         you doesn`t specify it, no negative gadget will be displayed, but in
  112.         this case you must specify either String or Integer (see later). If
  113.         you do not specify String or Integer a default negative gadget will
  114.         be displayed with the text: `Proceed`
  115.  
  116.     GadgetText
  117.  
  118.         This is the text, the string or integer gadget should contain at
  119.         start time. This is the default text of the string or integer
  120.         gadget (see later). If you specify Integer, this is the default
  121.         number.
  122.  
  123.     STRING
  124.  
  125.         If you specify String a string gadget will be displayed.
  126.         default: none
  127.  
  128.     INT
  129.  
  130.         If you specify Integer an integer gadget will be displayed.
  131.         default: none
  132.  
  133.     TimeOut
  134.  
  135.         With TimeOut you can use an optionally timeout for the requester. The
  136.         requester will be closed after the given timeout in seconds. If omitted,
  137.         the requester stays open until the user answers it.
  138.         If the requester will be satisfied with the timeout, AskReq will return
  139.         0.
  140.         default: none
  141.  
  142.     You can use string or integer gadget with or without pos and/or negative
  143.     gadgets.
  144.  
  145.     If you specify no gadget the default negative gadget will be used.
  146.  
  147.     If you only specify a string or integer gadget and no pos or neg gadget,
  148.     the requester will be satisfied by hitting return in the string or integer
  149.     gadget.
  150.  
  151.     If you specify a pos and negative gadget and the positive will be clicked
  152.     AskReq returns 5 (WARN). This can be used in batchfiles as well as you
  153.     specify string or integer. This behaves exactly the same than the Ask cli
  154.     command.
  155.  
  156. Examples:
  157.  
  158.     Here are some examples how to use AskReq from within batch files.
  159.  
  160.     1.) Just a message requester
  161.  
  162.     1.> AskReq M "This is version 1.00 of the|famous AskReq requester?"
  163.  
  164.     There is no gadget specified, so the default negative gadget will be
  165.     used. The requester displays two lines of text.
  166.  
  167.     2.) A boolean requester which lets the user chose two answers.
  168.  
  169.     ;-----------  Batch file
  170.  
  171.     AskReq M "This is version 1.00 of the|famous AskReq
  172.      requester?|Do you really like it?" POS "Oh Yes !!!" NEG "NO WAY"
  173.  
  174.     ; Open a requester with two gadgets and three lines of text
  175.  
  176.     If WARN    ; the user select `Oh Yes !!!`
  177.         echo "Oh this is fine :-)"
  178.     Else
  179.         echo "Why don`t you like me :-( ???"
  180.     Endif
  181.  
  182.     ;----------- END
  183.  
  184.  
  185.     3.) A requester which lets you put in your name and age asks you if its
  186.         really correct or not. This example is included as the example.bat
  187.         file.
  188.  
  189.     ;-----------  Batch file
  190.  
  191.     Set ANSW `AskReq M "Please tell me your name,|so I know where
  192.      you are!" S`
  193.  
  194.     ; Opens a requester with only a string gadget and two lines of text
  195.     ; The result will be saved in the variable ANSW
  196.  
  197.     Set AGE `AskReq M "And now tell me your age.|Are you really old
  198.      enough to ask|me something :-| ?" I`
  199.  
  200.     ; Opens a requester with only an integer gadget and three lines of text
  201.     ; The result will be saved in the variable AGE
  202.  
  203.     AskReq M "So I have got your datas|I will now Proceed"
  204.  
  205.     ; Just a notify requester
  206.     ; Now we ask the user if the datas are really correct.
  207.  
  208.     Set ANSW `AskReq M "You told me your name|Is this really your correct
  209.      name ?" S G $ANSW POS OKAY NEG "FORGET IT"`
  210.  
  211.     ; Opens a requester with a string and two boolean gadgets. The string
  212.     ; gadget contains the input name
  213.  
  214.     If $ANSW EQ ""  ; No name specified
  215.         echo "You want to stay anonymous"
  216.     Else
  217.         echo "You name is"
  218.         echo $ANSW
  219.     Endif
  220.  
  221.     Set AGE `AskReq M "You told me your age|Is this really your age ?"
  222.      I G $AGE POS OKAY NEG "FORGET IT"`
  223.  
  224.     ; Opens a requester with an integer and two boolean gadgets. The integer
  225.     ; gadget contains the input age
  226.  
  227.     If $AGE EQ ""  ; No age specified
  228.         echo "You won`t tell me your age"
  229.         Quit 5
  230.     Else
  231.         echo "You are"
  232.         echo $AGE
  233.         echo "years old"
  234.     Endif
  235.  
  236.     echo "Thank You " $ANSW " for your datas"
  237.  
  238.     ;----------- END
  239.  
  240.  
  241.     You see you can use AskReq for almost all batch file functions. AskReq
  242.     lets you make decisions and lets you jump to other labels etc.
  243.  
  244.  
  245. Technical:
  246.  
  247.     AskReq uses the gadtools.library and the readargs DOS functions.
  248.     It is completely written with Aztec C version 5.2. Source code is
  249.     available from the author.
  250.  
  251. Address:
  252.  
  253.     Send all messages, bug reports mail, gifts etc. to the following address:
  254.  
  255.     Hans-Peter Guenther
  256.     Gruener Weg 5
  257.     3501 Fuldatal 2
  258.     W-Germany
  259.  
  260.     Have Fun ...
  261.  
  262. List Of Files:
  263.  
  264.     The complete AskReq distribution includes the following files:
  265.  
  266.     AskReq             : the binary
  267.     AskReq.info
  268.     AskReq.doc         : english manual
  269.     AskReq.doc.info
  270.     AskReq.dok         : german manual
  271.     AskReq.dok.info
  272.     example1.bat       : the 3rd example
  273.     example1.bat.info
  274.