home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / MUI / MUIBuilder22.lha / MUIBuilder / MB / Tools / RexxDosSupport.lha / RexxDosSupport.doc < prev    next >
Encoding:
Text File  |  1994-06-06  |  19.5 KB  |  604 lines
  1. TABLE OF CONTENTS
  2.  
  3. RexxDosSupport.library/--Disclaimer--
  4. RexxDosSupport.library/--background--
  5. RexxDosSupport.library/--history--
  6. RexxDosSupport.library/--installation--
  7. RexxDosSupport.library/Delete
  8. RexxDosSupport.library/DeleteVar
  9. RexxDosSupport.library/Fault
  10. RexxDosSupport.library/GetVar
  11. RexxDosSupport.library/MakeDir
  12. RexxDosSupport.library/MatchPattern
  13. RexxDosSupport.library/ParsePattern
  14. RexxDosSupport.library/ReadArgs
  15. RexxDosSupport.library/Rename
  16. RexxDosSupport.library/SetComment
  17. RexxDosSupport.library/SetProtection
  18. RexxDosSupport.library/SetVar
  19. RexxDosSupport.library/--Disclaimer--   RexxDosSupport.library/--Disclaimer--
  20.  
  21. Disclaimer
  22. ----------
  23.  
  24.    Permission is granted to make and distribute verbatim copies  of  this
  25. manual provided the copyright  notice  and  this  permission  notice  are
  26. preserved on all copies.
  27.  
  28. COPYRIGHT
  29.  
  30.    Copyright (C) 1994 by hartmut Goebel
  31.  
  32.    No program, document, data file or  source  code  from  this  software
  33. package, neither in whole nor in part, may be included or used  in  other
  34. software packages unless it is authorized by a  written  permission  from
  35. the author.
  36.  
  37.  
  38. NO WARRANTY
  39.  
  40.    There is no warranty for this software package.  Although  the  author
  41. has tried to prevent errors, he can't guarantee that the software package
  42. described in this document is 100% reliable. You are therefore using this
  43. material at your own risk. The author cannot be made responsible for  any
  44. damage which is caused by using this software package.
  45.  
  46.  
  47. DISTRIBUTION
  48.  
  49.    This software package is freely distributable. It may be  put  on  any
  50. media which is used for the distribution of free  software,  like  Public
  51. Domain disk collections, CDROMs, FTP servers or bulletin board systems.
  52.  
  53.    In  order  to  ensure  the  integrity  of   this   software   package,
  54. distributors should use the original archive file  RexxDosSupport2_1.lha.
  55. The author cannot be  made  responsible  if  this software  package   has
  56. become unusable due to modifications of  the  archive  contents   or   of
  57. the archive file itself.
  58.  
  59.    There is no limit on the costs  of  the  distribution,  e.g.  for  the
  60. media, like floppy disks, streamer tapes or compact disks, or the process
  61. of duplicating. Such limits have been proven to be harmful to the idea of
  62. freely distributable software, e.g. instead of reducing the price of  the
  63. floppy disk below the limit, the software was  simply  removed  from  the
  64. master disk.
  65.  
  66.    Although the author does not impose any limit on the  distribution  of
  67. this software package, he would like to express his personal opinions  on
  68. this matter:
  69.  
  70.    * This software package should be made available to everyone  free  of
  71.      charge whenever it is possible.
  72.  
  73.    * If you have acquired this software package under  normal  conditions
  74.      from a Public Domain dealer on a floppy disk at a price higher  than
  75.      5DM or US $5, then you have definitely paid too much.  Please  don't
  76.      support this improper profit making  any  longer  and  switch  to  a
  77.      cheaper source as soon as possible.
  78.  
  79.  
  80. USAGE RESTRICTIONS
  81.  
  82.    No program, document, data file or  source  code  from  this  software
  83. package, neither in whole nor in part, may be used on any  machine  which
  84. is used
  85.  
  86.    * for the research, development, construction, testing  or  production
  87.      of weapons or other military applications. This  also  includes  any
  88.      machine which is  used  in  the  education  for  any  of  the  above
  89.      mentioned purposes.
  90.  
  91.    * by people who accept, support or use violence against other  people,
  92.      e.g. citizens from foreign countries.
  93.  
  94. RexxDosSupport.library/--background--   RexxDosSupport.library/--background--
  95.  
  96.                 RexxDosSupport.library 2.1
  97.                 ==========================
  98.  
  99.             Copyright (C) 1994 by hartmut Goebel
  100.  
  101.  
  102.    After programming ARexx script for quite a while, I missed some
  103.    function found in dos.library --  especially access to
  104.    environment variables and the comfortable argument parsing. Since
  105.    there seamed to be no ARexx function library which implements
  106.    this functions, I decited to write my own. And here it is.
  107.  
  108.    This are the functions handled by this library.
  109.    · ReadArgs()
  110.    · GetVar(), SetVar(), DeleteVar()
  111.    · ParsePattern(), MatchPattern() - even case-insensitive
  112.    · Fault()
  113.  
  114.    new functions for version 2.1
  115.    · Delete(), Rename(), MakeDir()
  116.    · SetComment(), SetProtection()
  117.  
  118.    Enjoy it!
  119.    +++hartmut
  120.  
  121. RexxDosSupport.library/--history--         RexxDosSupport.library/--history--
  122.  
  123.   2.1  03 Jun 1994
  124.        · removed curious bug in ReadArgs() (uninitialized var,
  125.          introduced in V2.0)
  126.   2.0  07 May 1994 (never released)
  127.        · stronger check for present args to avoid NIL-Traps
  128.        · new functions: Delete(), Rename(), MakeDir(),
  129.                         SetComment(), SetProtection()
  130.   1.4  01 Feb 1994
  131.        · only significant part of parsed pattern is copied
  132.          into the ARexx Argstring
  133.   1.3  23 Jan 1994
  134.        · uses module RxLibsSupport [hG]
  135.   1.2  18 Jan 1994
  136.        · finished dokumentation
  137.        · UnsetVar() - like shell commnad - renamed to
  138.          DeleteVar() - like in dos.library
  139.        · SetVar() no longer accepts option "Binary"
  140.   1.1  16 Jan 1994
  141.        initial release
  142.  
  143. RexxDosSupport.library/--installation--RexxDosSupport.library/--installation--
  144.  
  145.    To use RexxDosSupport.library, just copy is to yout LIBS:
  146.    directory. That's all.
  147.  
  148.    The LVO for the ARexx-Dispatcher is -30.
  149.        NB: it's the only LVO for this library :-)
  150.  
  151.    So, in every ARexx-Script you want to use RexxDosSupport.library,
  152.    insert
  153.  
  154.       call addlib("RexxDosSupport.library",0,-30,2)
  155.  
  156.    somewhere before the first call to one of the routines
  157.    implemented in this library.
  158.    Since ARexx does not check whether the lib can be opened but only
  159.    inserts the name into a list, the result value from addlib() can
  160.    be ignored in most cases. The value would be interesting to check
  161.    if the added note will require the same library version, but I
  162.    don't know how to find this out.
  163.  
  164. RexxDosSupport.library/Delete                   RexxDosSupport.library/Delete
  165.  
  166.    NAME
  167.        Delete -- Delete a file or directory (V2)
  168.  
  169.    SYNOPSIS
  170.        success = Delete( name )
  171.  
  172.    FUNCTION
  173.        This attempts to delete the file or directory specified by
  174.        'name'. If the deletion fails an error is returned and the
  175.        rexx variable RC is set. Note that all the files within a
  176.        directory must be deleted before the directory itself can be
  177.        deleted.
  178.  
  179.    INPUTS
  180.        name     - name of file or directory to delete.
  181.  
  182.    RESULT
  183.        success - If TRUE, the file was sucessfully deleted,
  184.                  FALSE indicates failure.
  185.  
  186.        RC (rexx variable) - contains the dos error code if the
  187.                function was not successfull. This can can directly
  188.                be used as input for Fault().
  189.  
  190.    SEE ALSO
  191.        Fault(), dos.library/DeleteFile()
  192.  
  193. RexxDosSupport.library/DeleteVar             RexxDosSupport.library/DeleteVar
  194.  
  195.    NAME
  196.        DeleteVar -- Deletes a local or environment variable
  197.  
  198.    SYNOPSIS
  199.        success = DeleteVar( name, [ "Local" | "Global" ] )
  200.  
  201.    FUNCTION
  202.        Deletes a local or environment variable.
  203.  
  204.    INPUTS
  205.        name     - variable name.  Note variable names follow
  206.                   filesystem syntax and semantics.
  207.        "Global" - tries to get a global env variable.
  208.        "Local"  - tries to get a local variable.
  209.  
  210.                 The default is to delete a local variable if found, otherwise
  211.                 a global environment variable if found.
  212.  
  213.    RESULT
  214.        success - If TRUE, the variable was sucessfully deleted,
  215.                  FALSE indicates failure.
  216.  
  217.    SEE ALSO
  218.        GetVar(), SetVar(), dos.library/DeleteVar()
  219.  
  220. RexxDosSupport.library/Fault                     RexxDosSupport.library/Fault
  221.  
  222.    NAME
  223.        Fault -- Returns the text associated with a DOS error code
  224.  
  225.    SYNOPSIS
  226.        string = Fault( code, header )
  227.  
  228.    FUNCTION
  229.        This routine obtains the error message text for the given
  230.        error code. The header is prepended to the text of the error
  231.        message, followed by a colon. By convention, error messages
  232.        should be no longer than 80 characters, and preferably no
  233.        more than 60.
  234.  
  235.        The value returned by IoErr() (not available in this library)
  236.        is set to the code passed in. If there is no message for the
  237.        error code, the message will be "Error code <number>\n".
  238.  
  239.        The string will be empty if the code passed in was 0.
  240.  
  241.    INPUTS
  242.        code   - Error code
  243.        header - header to output before error text
  244.  
  245.    RESULT
  246.        string - error massage as described above.
  247.  
  248.        RC (rexx variable) - 5 when error message is empty
  249.                             0 otherwise
  250.  
  251.    SEE ALSO
  252.        dos.library/Fault(), dos.library/IoErr()
  253.  
  254. RexxDosSupport.library/GetVar                   RexxDosSupport.library/GetVar
  255.  
  256.    NAME
  257.        GetVar -- Returns the value of a local or global variable
  258.  
  259.    SYNOPSIS
  260.        string = GetVar( name, ["Local" | "Global"], ["Binary"] )
  261.  
  262.    FUNCTION
  263.        Gets the value of a local or environment variable.  It is advised to
  264.        only use ASCII strings inside variables, but not required.  This stops
  265.        putting characters into the destination when a \n is hit, unless
  266.        "Binary" is specified.  (The \n is not stored in the buffer.)
  267.  
  268.    INPUTS
  269.        name     - variable name.
  270.        "Global" - tries to get a global env variable.
  271.        "Local"  - tries to get a local variable.
  272.        "Binary" - don't stop at \n
  273.                   in this mode the string returned is not null terminated
  274.  
  275.                 The default is to try to get a local variable first,
  276.                 then to try to get a global environment variable.
  277.  
  278.    RESULT
  279.        string - contents of the variable
  280.  
  281.        RC (rexx variable) - 5 when variable does not exist,
  282.                             0 otherwise
  283.  
  284.    EXAMPLE
  285.        /* */
  286.        username = GetVar("username")
  287.        if RC = 5 then
  288.          say "Variable 'username' is not set"
  289.        else
  290.          say "Variable 'username' is" username
  291.  
  292.    NOTES
  293.       contents may be max. 512 char.
  294.  
  295.    BUGS
  296.        Due to a bug in dos.library, binary global vars will be null
  297.        terminated in V37, V38.
  298.  
  299.    SEE ALSO
  300.      SetVar(), DeleteVar(), dos.library/GetVar()
  301.  
  302. RexxDosSupport.library/MakeDir                 RexxDosSupport.library/MakeDir
  303.  
  304.    NAME
  305.        MakeDir -- Create a new directory (V2)
  306.  
  307.    SYNOPSIS
  308.        success = MakeDir( name )
  309.  
  310.    FUNCTION
  311.        MakeDir creates a new directory with the specified name. If
  312.        it fails an error is returned and the rexx variable RC is
  313.        set.  Directories can only be created on devices which
  314.        support them, e.g. disks.
  315.  
  316.    INPUTS
  317.        name     - name of directory to create
  318.  
  319.    RESULT
  320.        success - If TRUE, the variable was sucessfully deleted,
  321.                  FALSE indicates failure.
  322.  
  323.        RC (rexx variable) - contains the dos error code if the
  324.                function was not successfull. This can can directly
  325.                be used as input for Fault().
  326.  
  327.    SEE ALSO
  328.        Fault(), dos.library/CreateDir()
  329.  
  330. RexxDosSupport.library/MatchPattern       RexxDosSupport.library/MatchPattern
  331.  
  332.    NAME
  333.        MatchPattern --  Checks for a pattern match with a string
  334.  
  335.    SYNOPSIS
  336.        match = MatchPattern(pattern, string, ["Nocase"], ["Parsed"] )
  337.  
  338.    FUNCTION
  339.        Checks for a pattern match with a string.
  340.        This routine is case-sensitive by default. Use option
  341.        "NoCase" for case-insensitve matching.
  342.  
  343.        Use option "Parsed" to indicate that pattern has already been
  344.        tokenized using ParsePattern(). Make sure to use or use not
  345.        "NoCase" for both function.
  346.  
  347.    INPUTS
  348.        pattern  - pattern string to match
  349.        string   - string to match against given pattern
  350.        "Nocase" - match should be case-insensitve
  351.        "Parsed" - pattern has already been parsed using ParsePattern()
  352.  
  353.    RESULT
  354.        match - success or failure of pattern match.
  355.  
  356.    SEE ALSO
  357.        ParsePattern(), dos.library/MatchPattern(),
  358.        dos.library/MatchPatternNoCase()
  359.  
  360. RexxDosSupport.library/ParsePattern       RexxDosSupport.library/ParsePattern
  361.  
  362.    NAME
  363.        ParsePattern -- Create a tokenized string for MatchPattern()
  364.  
  365.    SYNOPSIS
  366.        token = ParsePattern( pattern, ["NoCase"] )
  367.  
  368.    FUNCTION
  369.        Tokenizes a pattern, for use by MatchPattern().  Also indicates
  370.        if there are any wildcards in the pattern (i.e. whether it might match
  371.        more than one item).
  372.  
  373.        For a description of the wildcards, see dos.library/ParsePattern().
  374.  
  375.    INPUTS
  376.        pattern  - unparsed wildcard string to search for.
  377.  
  378.    RESULT
  379.        token    - output string, tokenized version of input.
  380.  
  381.        RC (rexx variable) - 5 when does not contain wildcards
  382.                             0 otherwise
  383.  
  384.    BUGS
  385.        Since is't not clear wether the resulting token may contain
  386.        null charakters, the returned string is always
  387.        2 * Length(pattern) + 2 bytes long.
  388.  
  389.    SEE ALSO
  390.        ParsePattern(), dos.library/ParsePattern(),
  391.        dos.library/ParsePatternNoCase()
  392.  
  393. RexxDosSupport.library/ReadArgs               RexxDosSupport.library/ReadArgs
  394.  
  395.    NAME
  396.        ReadArgs -- Parse argument string using Dos/ReadArgs()
  397.  
  398.    SYNOPSIS
  399.        okay = ReadArgs( arguments, template, [stem] )
  400.  
  401.    FUNCTION
  402.        Parses an argument string according to a template. See
  403.        dos.library/ReadArgs() for details and describtion of the
  404.        template.
  405.  
  406.        This function supports the following template options:
  407.  
  408.        /S - Switch.  Resulting variable will be either true (1) or
  409.             false (0).
  410.        /N - Number.
  411.        /M - Multiple strings.  See below for further information.
  412.  
  413.        /K - Keyword.      }
  414.        /A - Required.     }  handled by dos
  415.        /F - Rest of line. }
  416.  
  417.        /T (toggle) is not supported, since handling this would be a
  418.        large turnover with small profit.
  419.  
  420.    INPUTS
  421.        arguments - the string to be parsed
  422.        template  - dos.library/ReadArgs()-style like template
  423.        stem      - stem prefix for resulting variables (optional)
  424.  
  425.    RESULT
  426.        okay  - boolean value indicating success.
  427.  
  428.        RC (rexx variable) - contains the dos error code if the
  429.                function was not successfull. This can can directly
  430.                be used as input for Fault().
  431.  
  432.        For each item in the template which has a corresponding
  433.        argument, a Rexx variable will be created. The variable's
  434.        name is the item's name prefixed by the stem name (if given).
  435.  
  436.        Items with option /M will result in a stem variable with a
  437.        .COUNT node containing the number of elements. If no fitting
  438.        arguments is passed, .COUNT will be zero.
  439.        The entries will be in stem nodes .0 to .n (where n is
  440.        .COUNT-1).
  441.  
  442.    EXAMPLE
  443.        /* ReadArgsExample.rexx */
  444.        /* AddLib() here */
  445.  
  446.        parse arg args /* get the arguments w/o ARexx-Parsing */
  447.  
  448.        template = "Files/M,Method/K,MinSize/K/N,Test/S"
  449.  
  450.        /* set defaults */
  451.        Method = "NUKE"; MinSize = 512;
  452.  
  453.        /* no stem given: results are assigned to simple variables */
  454.  
  455.        if ReadArgs(args,template) then
  456.          say 'Method =' method '  MinSize =' MinSize '  Test =' test
  457.          do i = 0 by 1 for file.count
  458.            say name.1
  459.          end
  460.  
  461.        /* stem given: results are assigned to stem variable */
  462.        /* since the default values are set as non-stem variables,
  463.         * they are not overwritten by the following call even if
  464.         * given
  465.         */
  466.  
  467.        if ReadArgs(input,template,"args.") then
  468.          say 'Method =' args.method '  MinSize =' args.MinSize ' Test =' args.test
  469.          do i = 0 by 1 for args.file.count
  470.            say args.name.1
  471.          end
  472.  
  473.    SEE ALSO
  474.       Fault(), dos.library/ReadArgs()
  475.  
  476. RexxDosSupport.library/Rename                   RexxDosSupport.library/Rename
  477.  
  478.    NAME
  479.        Rename -- Rename a directory or file (V2)
  480.  
  481.    SYNOPSIS
  482.        success = Rename( oldName, newName )
  483.  
  484.    FUNCTION
  485.        Rename() attempts to rename the file or directory specified
  486.        as 'oldName' with the name 'newName'. If the file or
  487.        directory 'newName' exists, Rename() fails and returns an
  488.        error. Both 'oldName' and the 'newName' can contain a
  489.        directory specification. In this case, the file will be moved
  490.        from one directory to another.
  491.  
  492.        Note: it is impossible to Rename() a file from one volume to
  493.        another.
  494.  
  495.    INPUTS
  496.        oldName - pointer to a null-terminated string
  497.        newName - pointer to a null-terminated string
  498.  
  499.    RESULT
  500.        success - If TRUE, the variable was sucessfully deleted,
  501.                  FALSE indicates failure.
  502.  
  503.        RC (rexx variable) - contains the dos error code if the
  504.                function was not successfull. This can can directly
  505.                be used as input for Fault().
  506.  
  507.    SEE ALSO
  508.        Fault(), dos.library/Rename()
  509.  
  510. RexxDosSupport.library/SetComment           RexxDosSupport.library/SetComment
  511.  
  512.    NAME
  513.        SetComment -- Change a files' comment string (V2)
  514.  
  515.    SYNOPSIS
  516.        success = SetComment( name, comment )
  517.  
  518.    FUNCTION
  519.        SetComment() sets a comment on a file or directory. The
  520.        comment may be up to 80 characters in the current ROM
  521.        filesystem (and RAM:).  Note that not all filesystems will
  522.        support comments (for example, NFS usually will not), or the
  523.        size of comment supported may vary.
  524.  
  525.    INPUTS
  526.        name     - name of file or directory to set comment
  527.        comment  - comment to be set
  528.  
  529.    RESULT
  530.        success - If TRUE, the variable was sucessfully deleted,
  531.                  FALSE indicates failure.
  532.  
  533.        RC (rexx variable) - contains the dos error code if the
  534.                function was not successfull. This can can directly
  535.                be used as input for Fault().
  536.  
  537.    SEE ALSO
  538.        SetProtection(), Fault(), dos.library/SetComment()
  539.  
  540. RexxDosSupport.library/SetProtection     RexxDosSupport.library/SetProtection
  541.  
  542.    NAME
  543.        SetProtection -- Set protection for a file or directory (V2)
  544.  
  545.    SYNOPSIS
  546.        success = SetProtection( name, mask )
  547.  
  548.    FUNCTION
  549.        SetProtection() sets the protection attributes on a file or
  550.        directory.  See <dos/dos.h> for a listing of protection bits.
  551.  
  552.        The archive bit should be cleared by the filesystem whenever
  553.        the file is changed.  Backup utilities will generally set the
  554.        bit after backing up each file.
  555.  
  556.        The V36 Shell looks at the execute bit, and will refuse to
  557.        execute a file if it is set.
  558.  
  559.        Other bits will be defined in the <dos/dos.h>include files.
  560.        Rather than referring to bits by number you should use the
  561.        definitions in <dos/dos.h>.
  562.  
  563.    INPUTS
  564.        name     - name of file or directory to set protection
  565.        mask     - the protection mask required
  566.  
  567.    RESULT
  568.        success - If TRUE, the variable was sucessfully deleted,
  569.                  FALSE indicates failure.
  570.  
  571.        RC (rexx variable) - contains the dos error code if the
  572.                function was not successfull. This can can directly
  573.                be used as input for Fault().
  574.  
  575.    SEE ALSO
  576.        SetComment(), Fault(), dos.library/SetProtection()
  577.  
  578. RexxDosSupport.library/SetVar                   RexxDosSupport.library/SetVar
  579.  
  580.    NAME
  581.        SetVar -- Sets a local or environment variable
  582.  
  583.    SYNOPSIS@{ub}
  584.        success = SetVar( name, ["Local" | "Global"] )
  585.  
  586.    FUNCTION
  587.        Sets a local or environment variable.  It is advised to only use
  588.        ASCII strings inside variables, but not required.
  589.  
  590.    INPUTS
  591.        name     - variable name.
  592.        "Global" - tries to get a global env variable.
  593.        "Local"  - tries to get a local variable.
  594.  
  595.                The default is to set a local environment variable.
  596.  
  597.    RESULT
  598.        success - If non-zero, the variable was sucessfully set, FALSE
  599.                  indicates failure.
  600.  
  601.    SEE ALSO
  602.      GetVar(), DeleteVar(), dos.library/SetVar()
  603.  
  604.