home *** CD-ROM | disk | FTP | other *** search
/ Amiga MA Magazine 1998 #6 / amigamamagazinepolishissue1998.iso / coders / biblioteki / c_library / extrdargs / extrdargs.doc < prev    next >
Text File  |  1977-12-31  |  6KB  |  152 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. ExtReadArgs/--background--
  6. ExtReadArgs/ExtFreeArgs
  7. ExtReadArgs/ExtReadArgs
  8.  
  9.  
  10. ExtReadArgs/--background--                          ExtReadArgs/--background--
  11.  
  12.     PURPOSE
  13.         This is a CLI/Workbench transparent argument interface. I don't liked
  14.         the way of parsing ToolTypes and used only the ReadArgs() function.
  15.         Thus all my tools can only be invoked from the CLI/Shell . Thats the
  16.         reason for building this project !
  17.  
  18.     FUNCTION
  19.         ExtReadArgs() copies all Workbench arguments in a single string and
  20.         passes this string to the ReadArgs() function. All WBArg structure
  21.         are expanded to their full filenames , enclosed in '"' and passed to
  22.         the item specified via the erda_FileParameter field. Then all Tool-
  23.         types are strcat()'ed into one line, thus ReadArgs() can handle it.
  24.         To handle each Tooltype correctly the argument is enclosed in '"' !
  25.  
  26.     NOTE
  27.         There are some special feature according to the ReadArgs() function.
  28.         If you have a template like "FROM/M/A,TO/A", you can select these
  29.         files from workbench : Select the program, then the FROM files and
  30.         finally select and double click th TO file. This is available,because
  31.         ReadArgs() grab's the last string from a MultiArg FROM and uses it
  32.         as the TO parameter, if no is explicitly given !
  33.  
  34.     INSPIRATION
  35.         I get the main idea, how I implement the Workbench ReadArgs()
  36.         interface from the author of ARoach Stefan Winterstein. Thanks for
  37.         this idea of parsing ToolTypes !
  38.  
  39. ExtReadArgs/ExtFreeArgs                                ExtReadArgs/ExtFreeArgs
  40.  
  41.     NAME
  42.         ExtFreeArgs - free's all allocated resources from ExtReadArgs()
  43.  
  44.     SYNOPSIS
  45.         ExtFreeArgs(extrdargs);
  46.  
  47.         void ExtFreeArgs(struct ExtRDArgs *);
  48.  
  49.     FUNCTION
  50.         free's all allocated resources from a previously call to
  51.         ExtReadArgs().
  52.  
  53.     INPUTS
  54.         extrdargs (struct ExtRDArgs *) - same pointer, which was passed
  55.             to ExtReadArgs()
  56.  
  57.     RESULTS
  58.         none
  59.  
  60.     SEE ALSO
  61.         ExtReadArgs()
  62.  
  63. ExtReadArgs/ExtReadArgs                                ExtReadArgs/ExtReadArgs
  64.  
  65.     NAME
  66.         ExtReadArgs - CLI/Workbench transparent ReadArgs() function
  67.  
  68.     SYNOPSIS
  69.         error = ExtReadArgs(ac,av,extrdargs);
  70.  
  71.         LONG ExtReadArgs(LONG ,STRPTR *,struct ExtRDArgs *);
  72.  
  73.     FUNCTION
  74.         this function is a CLI/Workbench transparent interface to ReadArgs().
  75.         It uses the argcount and argvector like SASC from the main entry 
  76.         point, to get the initial startup parameter. If ac is zero, so the
  77.         program is invoked from workbench and the av variable contains the
  78.         WBStartup structure ! Before you can call this function, you must set
  79.         up the library bases for dos.library and icon.library. Normally the
  80.         SASC autoinitialization code does this for you !
  81.         If all went right you get a return value of zero. This means the
  82.         passed arguments fits the template and are ready to use. Otherwise
  83.         you get a IoErr() like return code. You can pass this return value
  84.         directly to PrintFault() or something like that !
  85.  
  86.         NOTE : You must call the ExtFreeArgs() function to clean up, even
  87.                this function fails (see EXAMPLE) !!!
  88.  
  89.     INPUTS
  90.         ac (LONG) - parameter normally get from main()
  91.         av (STRPTR *) - parameter normally get from main()
  92.         extrdargs (struct ExtRDArgs *) - structure , which hold any
  93.             information used by ExtReadArgs()
  94.  
  95.         structure fields to setup before calling ExtReadArgs() :
  96.  
  97.             erda_Template - the really ReadArgs() template
  98.             erda_Parameter - ReadArgs() LONG WORD array to hold the arguments
  99.             erda_FileParameter - number of Argument in the template to use
  100.                 for the files passed via WBStartup->sm_ArgList or -1, that
  101.                 means you don't want any files
  102.             erda_Window - window description string to open, if the program
  103.                 is started from the workbench or NULL for no window ! If
  104.                 in the ToolType Array exists a WINDOW description this is
  105.                 used
  106.                 instead of the parameter of the ExtRDArgs structure !
  107.             erda_RDArgs - RDArgs structure to use for ReadArgs() call, thus
  108.                 you can use extended help !
  109.             erda_Buffer - pointer to a buffer to use for the Workbench
  110.             startup
  111.                 or NULL, that means ExtReadArgs() allocates a buffer for you
  112.             erda_BufferSize - if you provided a buffer, here is the length of
  113.                 it. If not this is the length you would have ! This length is
  114.                 checked against a minimum of ERDA_MIN_BUFFER_SIZE !
  115.  
  116.     RESULTS
  117.         zero for success, otherwise an IoErr() like error code.
  118.  
  119.         If the function successes you can check the erda_Flags field for the
  120.         FRDAF_WORKBENCH flag, if you want to known from where the program was
  121.         started
  122.  
  123.     EXAMPLE
  124.         /* In this example the dos.library and icon.library must be open
  125.          * from autoinitialization code
  126.          */
  127.         LONG main(LONG ac,STRPTR *av)
  128.         {
  129.            struct ExtRDArgs eargs = {NULL};
  130.            LONG para[2];
  131.            LONG error;
  132.  
  133.            eargs.erda_Template      = "FILES/M/A,VERBOSE";
  134.            eargs.erda_Parameter     = para;
  135.            eargs.erda_FileParameter = 0;
  136.            eargs.erda_Window        = "CON:////My WB-Window/CLOSE/WAIT";
  137.  
  138.            if((error = ExtReadArgs(ac,av,&eargs)) == 0)
  139.            {
  140.               /* do something */
  141.            } else
  142.               PrintFault(error,"MyProgram");
  143.            ExtFreeArgs(&eargs);
  144.  
  145.            return((error == 0) ? RETURN_OK : RETURN_FAIL);
  146.         }
  147.  
  148.     SEE ALSO
  149.         ExtFreeArgs(), dos.library/ReadArgs(),
  150.         icon.library/GetDiskObjectNew()
  151.  
  152.