home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / util / injector-2.00.lha / Injector / ErrorMsg / Doc / ErrorMsg.doc < prev    next >
Text File  |  1994-04-21  |  9KB  |  272 lines
  1. TABLE OF CONTENTS
  2.  
  3. errormsg.library/AlertErrorMsg
  4. errormsg.library/DisplayErrorMsgA
  5. errormsg.library/DisplayMessageA
  6. errormsg.library/GetErrorMsgA
  7. errormsg.library/PutErrorMsg
  8. errormsg.library/AlertErrorMsg              errormsg.library/AlertErrorMsg
  9.  
  10.  NAME
  11.     AlertErrorMsg -- Display a recovery alert with the error message
  12.  
  13.  SYNOPSIS
  14.     Response=AlertErrorMsg(Code,System,SubSystem);
  15.     D0               D0   D1       D2
  16.  
  17.     BOOL AlertErrorMsg(LONG,ULONG,ULONG);
  18.  
  19.  FUNCTION
  20.     This function is your last chance to display an error message
  21.     to the user: it uses an Intuition recoverty alert. This must
  22.     be really your last chance, as DisplayAlert()ing in a multitasking
  23.     system is not really polite.
  24.  
  25.  INPUTS
  26.     Code - see GetErrorMsgA()
  27.     System - see GetErrorMsgA()
  28.     SubSystem - see GetErrorMsgA()
  29.  
  30.  RESULT
  31.     Response - the result of DisplayAlert(). If there is no message
  32.            for the given System/SubSystem/Code, no alert is
  33.            produced, and Response is FALSE.
  34.  
  35.  BUGS
  36.     See DisplayAlert()
  37.  
  38.  SEE ALSO
  39.     GetErrorMsgA(), DisplayAlert()
  40.  
  41. errormsg.library/DisplayErrorMsgA        errormsg.library/DisplayErrorMsgA
  42.  
  43.  NAME
  44.     DisplayErrorMsgA() -- Display an error in a requester
  45.     DisplayErrorMsg() -- varargs stub for DisplayErrorMsgA()
  46.  
  47.  SYNOPSIS
  48.     Num=DisplayErrorMsgA(Code,System,Subsystem,TagList);
  49.     D0             D0      D1     D2       A0
  50.  
  51.     LONG DisplayErrorMsgA(LONG,ULONG,ULONG,struct TagItem *);
  52.  
  53.     Num=DisplayErrorMsg(Code,System,Subsystem,Tag1,...);
  54.  
  55.     LONG DisplayErrorMsg(LONG,ULONG,ULONG,Tag,...);
  56.  
  57.  FUNCTION
  58.     This function is an integreated access to GetErrorMsgA() and
  59.     DisplayMessageA(). The error message, if it exists, will be
  60.     displayed in a nice requester. If there is no message for the
  61.     given system/subsystem/code, no requester is produced, and
  62.     Num is 0.
  63.  
  64.  INPUTS
  65.     Code - See GetErrorMsgA()
  66.     System - See GetErrorMsgA()
  67.     Subsystem - See GetErrorMsgA()
  68.     TagList - Pointer to an optionnal tag list, or NULL.
  69.  
  70.  TAGS
  71.     All tags understood by either GetErrorMsgA() or DisplayMessageA().
  72.  
  73.  RESULT
  74.     Num - See DisplayMessageA(). 0 if there is no message.
  75.     Tags - See GetErrorMsgA() or DisplayErrorMsgA()
  76.  
  77.  BUGS
  78.     See EasyRequestArgs()
  79.  
  80.  SEE ALSO
  81.     libraries/errormsg.h, GetErrorMsgA(), DisplayMessageA(),
  82.     EasyRequestArgs()
  83.  
  84. errormsg.library/DisplayMessageA          errormsg.library/DisplayMessageA
  85.  
  86.  NAME
  87.     DisplayMessageA() -- Display a requester with a message
  88.     DisplayMessage() -- varargs stub for DisplayMessageA()
  89.  
  90.  SYNOPSIS
  91.     Num=DisplayMessageA(TextFmt,Args,TagList);
  92.     D0            A0        A1     A2
  93.  
  94.     LONG DisplayMessageA(UBYTE *,APTR,struct TagItem *);
  95.  
  96.     Num=DisplayMessage(TextFmt,Args,Tag1,...);
  97.  
  98.     LONG DisplayMessage(UBYTE *,APTR,Tag,...);
  99.  
  100.  FUNCTION
  101.     This function will display an EasyRequest()-style requester
  102.     with the provided text format, arguments and optionnal taglist.
  103.  
  104.  INPUTS
  105.     TextFmt - A text formatting string, exactly as taken by
  106.           EasyRequestArgs(). Each control character (like %s
  107.           for a string, %ld for a longword decimal number)
  108.           will be replaced by the corresponding field in
  109.           the arguments array.
  110.     Args - An array of arguments for the Text format. This can
  111.            also include arguments for an optionnal gadget format
  112.            given by the EMT_GadFmt tag. in that case, gadget
  113.            arguments must follow body text arguments.
  114.     TagList - Pointer to an optionnal tag list , or NULL.
  115.  
  116.  TAGS
  117.     EMT_Window (struct Window *) - This tag says you want the requester
  118.                        to appear on the same screen as
  119.                        the window identified by ti_Data.
  120.                        It will also set the default title
  121.                        for the requester (see EasyRequest()).
  122.                        The default is to use the window
  123.                        pointed by the pr_WindowPtr of your
  124.                        process structure if it is valid, or
  125.                        the default public screen if it is
  126.                        NULL, or if the calling task is not
  127.                        a process. If pr_WindowPtr is -1,
  128.                        and there is no EMT_Window tag, no
  129.                        requester is produced.
  130.     EMT_Title (UBYTE *) - This tag provides a null-terminated string
  131.                   for the title of the requester. The default
  132.                   is the Window title, or "System Request" if
  133.                   none.
  134.     EMT_GadFmt (UBYTE *) - This tag says you want to use a custom
  135.                    gadget formatting string. This can include
  136.                    control characters like "%s". The english
  137.                    default is "Okay.". You can provide several
  138.                    gadget labels by separting them with "|".
  139.                    You must specify at least one gadget.
  140.     EMT_IDCMPPtr (ULONG *) - With this tag, you can make the requester
  141.                  close on receiving one of the IDCMP flags
  142.                  pointed by ti_Data (beware that ti_Data
  143.                  POINTS TO an IDCMP longword.
  144.  
  145.  RESULT
  146.     Num - This is the number of the gadget clicked. From left to
  147.           right: 1,2,...,N,0. -1 means that one of the custom IDCMP
  148.           flags was received. If no requester was produced (pr_WindowPtr
  149.           equals -1), then Num is 0.
  150.     EMT_IDCMPPtr - If Num was -1, the longword pointed by ti_Data
  151.                contains the IDCMP flag that was received.
  152.  
  153.  NOTE
  154.     This is exactly what EasyRequestArgs() returns.
  155.  
  156.  BUGS
  157.     See EasyRequestArgs().
  158.  
  159.  SEE ALSO
  160.     EasyRequestArgs(), libraries/errormsg.h
  161.  
  162. errormsg.library/GetErrorMsgA                errormsg.library/GetErrorMsgA
  163.  
  164.  NAME
  165.     GetErrorMsgA() -- Get a pointer to an error message
  166.     GetErrorMsg() -- varargs stub for GetErrorMsgA()
  167.  
  168.  SYNOPSIS
  169.     message=GetErrorMsgA(Code,System,Subsytem,TagList);
  170.     D0             D0      D1     D2      A0
  171.  
  172.     STRPTR GetErrorMsgA(LONG,ULONG,ULONG,struct TagItem *);
  173.  
  174.     message=GetErrorMsg(Code,System,Subsystem,Tag1,...);
  175.  
  176.     STRPTR GetErrorMsg(LONG,ULONG,ULONG,Tag,...);
  177.  
  178.  FUNCTION
  179.     Returns the error message identified by System, Subsystem,
  180.     Code and modifying tags. If locale.library was not open
  181.     on initialization, the message will be in english. It will
  182.     be also the case if the catalog does not exist or cannot
  183.     be opened.
  184.  
  185.  INPUTS
  186.     Code - the error code returned by the system/subsystem. There is
  187.            a special code, 0, that is understood by ERMSYS_DOS/
  188.            ERMSUB_IoErr (and no other system/subsystem). If you
  189.            pass this as the Code parameter, then errormsg.library
  190.            will get the real error code from the IoErr() function
  191.            (provided that the caller is a process).
  192.     System - a special code identifying the resource that has emitted
  193.          the error code. Typically, it is a code for a library or
  194.          a device. They are defined in libraries/errormsg.h
  195.     Subsystem - this is system-dependant. Typically, it is the _LVO
  196.             offset of the function that returned an error for
  197.             libraries, and the command number for devices. See
  198.             include file for supported values.
  199.     TagList - pointer to an optionnal tag list, or NULL.
  200.  
  201.  TAGS
  202.     EMT_Length (ULONG *) - pointer to an ULONG that will be filled with
  203.                    the length of the string.
  204.     EMT_Error (ULONG *) - pointer to an ULONG that will hold the error
  205.                   code from errormsg.library if no string can
  206.                   be found. Check include file for defines.
  207.     EMT_ForceCopy (APTR) - This tag forces the library to copy the
  208.                    message into the buffer pointed by ti_Data
  209.                    (must be big enough, 128 bytes will do)
  210.                    instead of referencing the internal private
  211.                    message. This lets you build a bigger message
  212.                    or modify it. If this tag is present, message
  213.                    will point at the buffer.
  214.  
  215.  RESULT
  216.     message - a pointer to a message string, or NULL if none can be
  217.           found (this happens for unsupported error codes).
  218.     EMT_Length - the ULONG pointed by ti_Data will be filled with
  219.              the length of the string (or 0 if NULL)
  220.     EMT_Error - the ULONG pointed by ti_Data will be filled with an
  221.             error code if failure, 0 if OK.
  222.  
  223.  NOTE
  224.     This function preserves all registers except D0 and D1.
  225.  
  226.  BUGS
  227.     none known.
  228.  
  229.  SEE ALSO
  230.     libraries/errormsg.h
  231.  
  232. errormsg.library/PutErrorMsg                  errormsg.library/PutErrorMsg
  233.  
  234.  NAME
  235.     PutErrorMsg() -- Print an error message
  236.  
  237.  SYNOPSIS
  238.     Success=PutErrorMsg(Code,System,SubSystem,Header);
  239.     D0            D0   D1    D2      A0
  240.  
  241.     BOOL PrintErrorMsg(LONG,ULONG,ULONG,STRPTR);
  242.  
  243.  FUNCTION
  244.     This function prints the error message identified by the Code,
  245.     System and SubSystem values to the default output channel using
  246.     buffered output. It is preceeded by the header messa