home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / util / libs / errormsg / doc / errormsg.doc < prev    next >
Encoding:
Text File  |  1994-10-28  |  12.5 KB  |  356 lines
  1. TABLE OF CONTENTS
  2.  
  3. errormsg.library/--rexxhost--
  4. errormsg.library/AlertErrorMsg
  5. errormsg.library/DisplayErrorMsgA
  6. errormsg.library/DisplayMessageA
  7. errormsg.library/GetErrorMsgA
  8. errormsg.library/PutErrorMsg
  9. errormsg.library/--rexxhost--                errormsg.library/--rexxhost--
  10.  
  11.  HOST INTERFACE
  12.     As of V2.0, errormsg.library provides an ARexx function interface that
  13.     enables ARexx programs to take advantage of the features of
  14.     ErrorMsg.  The functions provided by the interface are directly
  15.     related to the functions described herein, with the differences
  16.     mostly being in the way they are called.
  17.     The function host library vector is located at offset -60 from
  18.     the library. This is the value you provide to ARexx in the
  19.     AddLib() function call.
  20.  
  21.  FUNCTIONS
  22.     CALL AlertErrorMsg(CODE/N/A,SYSTEM/N/A,SUBSYSTEM/N/A)
  23.  
  24.     Num= DisplayErrorMsg(CODE/N/A,SYSTEM/N/A,SUBSYSTEM/N/A,GAD,TITLE,
  25.                             WINDOW/N,IDCMP/N)
  26.  
  27.     Num= DisplayMessage(BODY/A,GAD,TITLE,WINDOW/N,IDCMP/N)
  28.  
  29.     Message= GetErrorMsg(CODE/N/A,SYSTEM/N/A,SUBSYSTEM/N/A)
  30.  
  31.     Success= PutErrorMsg(CODE/N/A,SYSTEM/N/A,SUBSYSTEM/N/A,HEADER)
  32.  
  33.  NOTES
  34.     As these functions are called from ARexx's context, and not from,
  35.     for example, the CLI that launched the script, the pr_WindowPtr
  36.     field of the calling process structure may not be representative
  37.     of the window the output is actually produced. In fact, it is likely
  38.     to be 0, in which case the output is produced on the Workbench screen.
  39.     Since this field provides for the default values of the arguments
  40.     TITLE and WINDOW, you are likely to get "Information" or "Request"
  41.     as the title and the window displayed on the default public screen.
  42.     I might write if you really need it a function that sets the pr_WindowPtr
  43.     field as needed (by asking the console process), but I'm not sure it
  44.     is really safe to modify ARexx's context by hand (in fact, I'm sure
  45.     of the opposite :-).
  46.  
  47.  BUGS
  48.     Not really a bug, but it is currently impossible to detect error
  49.     returns from GetErrorMsgA(). May or may not be fixed in the future.
  50.  
  51.     DisplayErrorMsg() will force code to 0 when using ERMSYS_EXEC/
  52.     ERMSUB_NoLibrary because it is _currently_ impossible to pass
  53.     the library name and version. Might or might not be fixed in the
  54.     future...
  55.     AlertErrorMsg() and PutErrorMsg() will do so as well, but because
  56.     of the functions themselves (this is not an ARexx limitation).
  57. errormsg.library/AlertErrorMsg              errormsg.library/AlertErrorMsg
  58.  
  59.  NAME
  60.     AlertErrorMsg -- Display a recovery alert with the error message
  61.  
  62.  SYNOPSIS
  63.     Response=AlertErrorMsg(Code,System,SubSystem);
  64.     D0               D0   D1       D2
  65.  
  66.     BOOL AlertErrorMsg(LONG,ULONG,ULONG);
  67.  
  68.  FUNCTION
  69.     This function is your last chance to display an error message
  70.     to the user: it uses an Intuition recoverty alert. This must
  71.     be really your last chance, as DisplayAlert()ing in a multitasking
  72.     system is not really polite.
  73.  
  74.  INPUTS
  75.     Code - see GetErrorMsgA()
  76.     System - see GetErrorMsgA()
  77.     SubSystem - see GetErrorMsgA()
  78.  
  79.  RESULT
  80.     Response - the result of DisplayAlert(). If there is no message
  81.            for the given System/SubSystem/Code, no alert is
  82.            produced, and Response is FALSE.
  83.  
  84.  BUGS
  85.     See DisplayAlert()
  86.     When using ERMSYS_EXEC/ERMSUB_NoLibrary, the Code argument will
  87.     be forced to 0 since there's no way of passing in the library
  88.     name and version as additionnal args. Use GetErrorMsgA() and
  89.     DisplayAlert() if you really need this feature.
  90.  
  91.  SEE ALSO
  92.     GetErrorMsgA(), DisplayAlert()
  93.  
  94. errormsg.library/DisplayErrorMsgA        errormsg.library/DisplayErrorMsgA
  95.  
  96.  NAME
  97.     DisplayErrorMsgA() -- Display an error in a requester
  98.     DisplayErrorMsg() -- varargs stub for DisplayErrorMsgA()
  99.  
  100.  SYNOPSIS
  101.     Num=DisplayErrorMsgA(Code,System,Subsystem,TagList);
  102.     D0             D0      D1     D2       A0
  103.  
  104.     LONG DisplayErrorMsgA(LONG,ULONG,ULONG,struct TagItem *);
  105.  
  106.     Num=DisplayErrorMsg(Code,System,Subsystem,Tag1,...);
  107.  
  108.     LONG DisplayErrorMsg(LONG,ULONG,ULONG,Tag,...);
  109.  
  110.  FUNCTION
  111.     This function is an integreated access to GetErrorMsgA() and
  112.     DisplayMessageA(). The error message, if it exists, will be
  113.     displayed in a nice requester. If there is no message for the
  114.     given system/subsystem/code, no requester is produced, and
  115.     Num is 0.
  116.  
  117.     As of V3.02, this function handles the special case of library
  118.     name and version for ERMSYS_EXEC/ERMSUB_NoLibrary.
  119.  
  120.  INPUTS
  121.     Code - See GetErrorMsgA()
  122.     System - See GetErrorMsgA()
  123.     Subsystem - See GetErrorMsgA()
  124.     TagList - Pointer to an optionnal tag list, or NULL.
  125.  
  126.  TAGS
  127.     All tags understood by either GetErrorMsgA() or DisplayMessageA().
  128.     EMT_LibName (UBYTE *) - The library name for messages from
  129.                 ERMSYS_EXEC/ERMSUB_NoLibrary only.
  130.                 Ignored for other systems/subsystems.
  131.                 You must set the flag in the code field
  132.                 (see include file for the full description
  133.                 of this procedure).
  134.     EMT_LibVersion (ULONG) - The library version for the same case.
  135.                  Set the flag too.
  136.  
  137.  RESULT
  138.     Num - See DisplayMessageA(). 0 if there is no message.
  139.     Tags - See GetErrorMsgA() or DisplayErrorMsgA()
  140.  
  141.  BUGS
  142.     See EasyRequestArgs()
  143.  
  144.  SEE ALSO
  145.     libraries/errormsg.h, GetErrorMsgA(), DisplayMessageA(),
  146.     EasyRequestArgs()
  147.  
  148. errormsg.library/DisplayMessageA          errormsg.library/DisplayMessageA
  149.  
  150.  NAME
  151.     DisplayMessageA() -- Display a requester with a message
  152.     DisplayMessage() -- varargs stub for DisplayMessageA()
  153.  
  154.  SYNOPSIS
  155.     Num=DisplayMessageA(TextFmt,Args,TagList);
  156.     D0            A0        A1     A2
  157.  
  158.     LONG DisplayMessageA(UBYTE *,APTR,struct TagItem *);
  159.  
  160.     Num=DisplayMessage(TextFmt,Args,Tag1,...);
  161.  
  162.     LONG DisplayMessage(UBYTE *,APTR,Tag,...);
  163.  
  164.  FUNCTION
  165.     This function will display an EasyRequest()-style requester
  166.     with the provided text format, arguments and optionnal taglist.
  167.  
  168.  INPUTS
  169.     TextFmt - A text formatting string, exactly as taken by
  170.           EasyRequestArgs(). Each control character (like %s
  171.           for a string, %ld for a longword decimal number)
  172.           will be replaced by the corresponding field in
  173.           the arguments array.
  174.     Args - An array of arguments for the Text format. This can
  175.            also include arguments for an optionnal gadget format
  176.            given by the EMT_GadFmt tag. in that case, gadget
  177.            arguments must follow body text arguments.
  178.     TagList - Pointer to an optionnal tag list , or NULL.
  179.  
  180.  TAGS
  181.     EMT_Window (struct Window *) - This tag says you want the requester
  182.                        to appear on the same screen as
  183.                        the window identified by ti_Data.
  184.                        It will also set the default title
  185.                        for the requester (see EasyRequest()).
  186.                        The default is to use the window
  187.                        pointed by the pr_WindowPtr of your
  188.                        process structure if it is valid, or
  189.                        the default public screen if it is
  190.                        NULL, or if the calling task is not
  191.                        a process. If pr_WindowPtr is -1,
  192.                        and there is no EMT_Window tag, no
  193.                        requester is produced.
  194.     EMT_Title (UBYTE *) - This tag provides a null-terminated string
  195.                   for the title of the requester. The default
  196.                   is the Window title, or "System Request" if
  197.                   none.
  198.     EMT_GadFmt (UBYTE *) - This tag says you want to use a custom
  199.                    gadget formatting string. This can include
  200.                    control characters like "%s". The english
  201.                    default is "Okay.". You can provide several
  202.                    gadget labels by separting them with "|".
  203.                    You must specify at least one gadget.
  204.     EMT_IDCMPPtr (ULONG *) - With this tag, you can make the requester
  205.                  close on receiving one of the IDCMP flags
  206.                  pointed by ti_Data (beware that ti_Data
  207.                  POINTS TO an IDCMP longword.
  208.  
  209.     EMT_MUIBase (APTR) - This tag tells errormsg.library that it should
  210.                  use MUI's requester instead of intuition's.
  211.                  ti_Data must be the base of the muimaster.library
  212.                  (no check is performed).
  213.                  When using MUI, EMT_IDCMPPtr and EMT_Window are
  214.                  ignored. Moreover, MUI does not support formatting
  215.                  codes in gadget labels (yet ?). New for V3.01.
  216.     EMT_MUIAppObject (APTR) - With this tag, you provide a pointer to
  217.                   your application object, as returned by MUI
  218.                   New for V3.01.
  219.     EMT_MUIWinObject (APTR) - With this tag, you provide a pointer to
  220.                   the window the requester should appear on.
  221.                   Warning: this is MUI's window object, not
  222.                   Intuition's Window structure !. New for V3.01.
  223.  
  224.  RESULT
  225.     Num - This is the number of the gadget clicked. From left to
  226.           right: 1,2,...,N,0. -1 means that one of the custom IDCMP
  227.           flags was received. If no requester was produced (pr_WindowPtr
  228.           equals -1), then Num is 0.
  229.     EMT_IDCMPPtr - If Num was -1, the longword pointed by ti_Data
  230.                contains the IDCMP flag that was received.
  231.  
  232.  NOTE
  233.     This is exactly what EasyRequestArgs() returns.
  234.  
  235.  BUGS
  236.     See EasyRequestArgs().
  237.  
  238.  SEE ALSO
  239.     EasyRequestArgs(), libraries/errormsg.h
  240.  
  241. errormsg.library/GetErrorMsgA                errormsg.library/GetErrorMsgA
  242.  
  243.  NAME
  244.     GetErrorMsgA() -- Get a pointer to an error message
  245.     GetErrorMsg() -- varargs stub for GetErrorMsgA()
  246.  
  247.  SYNOPSIS
  248.     message=GetErrorMsgA(Code,System,Subsytem,TagList);
  249.     D0             D0      D1     D2      A0
  250.  
  251.     STRPTR GetErrorMsgA(LONG,ULONG,ULONG,struct TagItem *);
  252.  
  253.     message=GetErrorMsg(Code,System,Subsystem,Tag1,...);
  254.  
  255.     STRPTR GetErrorMsg(LONG,ULONG,ULONG,Tag,...);
  256.  
  257.  FUNCTION
  258.     Returns the error message identified by System, Subsystem,
  259.     Code and modifying tags. If locale.library was not open
  260.     on initialization, the message will be in english. It will
  261.     be also the case if the catalog does not exist or cannot
  262.     be opened.
  263.  
  264.  INPUTS
  265.     Code - the error code returned by the system/subsystem. See
  266.            include files for special cases.
  267.     System - a special code identifying the resource that has emitted
  268.          the error code. Typically, it is a code for a library or
  269.          a device. They are defined in libraries/errormsg.h
  270.     Subsystem - this is system-dependant. Typically, it is the _LVO
  271.             offset of the function that returned an error for
  272.             libraries, and the command number for devices. See
  273.             include file for supported values.
  274.     TagList - pointer to an optionnal tag list, or NULL.
  275.  
  276.  TAGS
  277.     EMT_Length (ULONG *) - pointer to an ULONG that will be filled with
  278.                    the length of the string.
  279.     EMT_Error (ULONG *) - pointer to an ULONG that will hold the error
  280.                   code from errormsg.library if no string can
  281.                   be found. Check include file for defines.
  282.     EMT_ForceCopy (APTR) - This tag forces the library to copy the
  283.                    message into the buffer pointed by ti_Data
  284.                    (must be big enough, 128 bytes will do)
  285.                    instead of referencing the internal private
  286.                    message. This lets you build a bigger message
  287.                    or modify it. If this tag is present, message
  288.                    will point at the buffer.
  289.  
  290.  RESULT
  291.     message - a pointer to a message string, or NULL if none can be
  292.           found (this happens for unsupported error codes).
  293.     EMT_Length - the ULONG pointed by ti_Data will be filled with
  294.              the length of the string (or 0 if NULL)
  295.     EMT_Error - the ULONG pointed by ti_Data will be filled with an
  296.             error code if failure, 0 if OK.
  297.  
  298.  NOTE
  299.     This function preserves all registers except D0 and D1.
  300.     For SetFunction()ners only: D1 points to the name of the system
  301.     that reported an error. Please do not depend on this value (it is
  302.     only required for DisplayErrorMsgA()).
  303.  
  304.  BUGS
  305.     When you pass ERMSYS_MUI/ERMSUB_MUIAutoError, you must provide
  306.     the MUIMasterBase as the code parameter. If the base is
  307.     invalid, you will get the error ERMERR_UnknownCode and a few
  308.     (harmless) enforcer hits.
  309.  
  310.  SEE ALSO
  311.     libraries/errormsg.h
  312.  
  313. errormsg.library/PutErrorMsg                  errormsg.library/PutErrorMsg
  314.  
  315.  NAME
  316.     PutErrorMsg() -- Print an error message
  317.  
  318.  SYNOPSIS
  319.     Success=PutErrorMsg(Code,System,SubSystem,Header);
  320.     D0            D0   D1    D2      A0
  321.  
  322.     BOOL PrintErrorMsg(LONG,ULONG,ULONG,STRPTR);
  323.  
  324.  FUNCTION
  325.     This function prints the error message identified by the Code,
  326.     System and SubSystem values to the default output channel using
  327.     buffered output. It is preceeded by the header message and a
  328.     colon. A linefeed is then added. If there is no corresponding
  329.     error message, no output is produced, and Success is FALSE.
  330.     It is also the case if VPrintf() fails.
  331.  
  332.  INPUTS
  333.     Code - see GetErrorMsgA()
  334.     System - see GetErrorMsgA()
  335.     SubSystem - see GetErrorMsgA()
  336.     Header - Pointer to an optionnal to header string or NULL for
  337.          none. Else, the header will be printed before the
  338.          message itself, and followed by a colon. The string
  339.          is terminated by a 0.
  340.  
  341.  RESULT
  342.     Success - Success/failure code.
  343.  
  344.  NOTE
  345.     This function is safe when called from a task, but useless.
  346.  
  347.  BUGS
  348.     When using ERMSYS_EXEC/ERMSUB_NoLibrary, the Code argument will
  349.     be forced to 0 since there's no way of passing in the library
  350.     name and version as additionnal args. Use GetErrorMsgA() and
  351.     VPrintf() if you really need this feature.
  352.  
  353.  SEE ALSO
  354.     GetErrorMsgA(), libraries/errormsg.h
  355.  
  356.