home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / inc&ad2.0 / text_autodocs / rexxsyslib.doc < prev    next >
Text File  |  1992-09-01  |  9KB  |  315 lines
  1. TABLE OF CONTENTS
  2.  
  3. rexxsyslib.library/ClearRexxMsg
  4. rexxsyslib.library/CreateArgstring
  5. rexxsyslib.library/CreateRexxMsg
  6. rexxsyslib.library/DeleteArgstring
  7. rexxsyslib.library/DeleteRexxMsg
  8. rexxsyslib.library/FillRexxMsg
  9. rexxsyslib.library/IsRexxMsg
  10. rexxsyslib.library/LengthArgstring
  11. rexxsyslib.library/LockRexxBase
  12. rexxsyslib.library/UnlockRexxBase
  13. rexxsyslib.library/ClearRexxMsg               rexxsyslib.library/ClearRexxMsg
  14.  
  15.     NAME
  16.     ClearRexxMsg - Releases and clears the argument array in a RexxMsg
  17.  
  18.     SYNOPSIS
  19.     ClearRexxMsg(msgptr, count)
  20.                  A0      D0
  21.  
  22.     VOID ClearRexxMsg(struct RexxMsg *,ULONG);
  23.  
  24.     FUNCTION
  25.     This function will DeleteArgstring() one or more argstrings from
  26.     the RexxMsg and clear the slot.  The count is used to select the
  27.     number of slots to clear.
  28.  
  29.     INPUTS
  30.     msgptr - A pointer to a RexxMsg
  31.     count - The number of slots to be cleared.  The number can be from
  32.             1 to 16.  (There are 16 slots)
  33.  
  34.     RESULTS
  35.     All of the slots in the given count will be cleared and the argstring
  36.     will have been released.
  37.  
  38.     SEE ALSO
  39.     FillRexxMsg(), DeleteRexxMsg(), DeleteArgstring(), CreateArgstring()
  40.  
  41.     BUGS
  42. rexxsyslib.library/CreateArgstring         rexxsyslib.library/CreateArgstring
  43.  
  44.     NAME
  45.     CreateArgstring - Create an argument string structure
  46.  
  47.     SYNOPSIS
  48.     argstr = CreateArgstring(string, length)
  49.     D0,A0                    A0      D0
  50.  
  51.     UBYTE *CreateArgstring(UBYTE *, ULONG);
  52.  
  53.     FUNCTION
  54.     Allocates a RexxArg structure and copies the supplied string into it.
  55.     The returned pointer points at the string part of the structure
  56.     and can be treated like an ordinary string pointer.  (However, care
  57.     must be taken that you do not change the string)
  58.  
  59.     INPUTS
  60.     string - A pointer at your input string
  61.     length - The number of bytes of your input string you wish copied.
  62.              (NOTE:  You are limited to 65,535 byte strings)
  63.  
  64.     RESULTS
  65.     argstr - A pointer to the argument string.  The results are returned
  66.              in both A0 and D0.  You should always check the result
  67.              as an allocation failure would cause an error.
  68.  
  69.     SEE ALSO
  70.     DeleteArgstring(), LengthArgstring(), ClearRexxMsg(), FillRexxMsg()
  71.  
  72.     BUGS
  73. rexxsyslib.library/CreateRexxMsg             rexxsyslib.library/CreateRexxMsg
  74.  
  75.     NAME
  76.     CreateRexxMsg - Create an ARexx message structure
  77.  
  78.     SYNOPSIS
  79.     rexxmsg = CreateRexxMsg(port, extension, host)
  80.     D0,A0                   A0    A1         D0
  81.  
  82.     struct RexxMsg *CreateRexxMsg(struct MsgPort *, UBYTE *, UBYTE *);
  83.  
  84.     FUNCTION
  85.     This functions allocates an ARexx message packet.  The RexxMsg
  86.     consists of a standard EXEC message structure extended to include
  87.     the ARexx specific information.
  88.  
  89.     INPUTS
  90.     port - A pointer to a public or private message port.  This *MUST*
  91.            be a valid port as this is where the message will be replied.
  92.  
  93.     extension - A pointer to a NULL terminated string that is to be used
  94.                 as the default extension for the REXX scripts.  If this
  95.                 is NULL, the default is "REXX"
  96.  
  97.     host - A pointer to a NULL terminated string that is to be used
  98.            as the default host port.  The name must be the same as the
  99.            name of the public message port that is to be the default host.
  100.            If this field is NULL, the default is REXX.
  101.  
  102.     RESULTS
  103.     rexxmsg - A RexxMsg structure
  104.  
  105.     NOTES
  106.     The extension and host strings must remain valid for as long as the
  107.     RexxMsg exists as only the pointer to those strings are stored.
  108.  
  109.     SEE ALSO
  110.     DeleteRexxMsg(), ClearRexxMsg(), FillRexxMsg()
  111.  
  112.     BUGS
  113. rexxsyslib.library/DeleteArgstring         rexxsyslib.library/DeleteArgstring
  114.  
  115.     NAME
  116.     DeleteArgstring - Releases an Argstring created by CreateArgstring()
  117.  
  118.     SYNOPSIS
  119.     DeleteArgstring(argstring)
  120.                     A0
  121.  
  122.     VOID DeleteArgstring(UBYTE *);
  123.  
  124.     FUNCTION
  125.     Releases an argstring.  The argstring must have been created by ARexx
  126.  
  127.     INPUTS
  128.     argstring - A pointer to the string buffer of an argstring.
  129.  
  130.     RESULTS
  131.  
  132.     SEE ALSO
  133.     CreateArgstring(), ClearRexxMsg(), FillRexxMsg()
  134.  
  135.     BUGS
  136. rexxsyslib.library/DeleteRexxMsg             rexxsyslib.library/DeleteRexxMsg
  137.  
  138.     NAME
  139.     DeleteRexxMsg - Releases a RexxMsg structure created by CreateRexxMsg()
  140.  
  141.     SYNOPSIS
  142.     DeleteRexxMsg(packet)
  143.                   A0
  144.  
  145.     VOID DeleteRexxMsg(struct RexxMsg *);
  146.  
  147.     FUNCTION
  148.     The function releases an ARexx message packet that was allocated
  149.     with CreateRexxMsg().  Any argument fields in the RexxMsg structure
  150.     should be cleared before calling this function as it does
  151.     not release them for you.
  152.  
  153.     INPUTS
  154.     packet - A pointer to a RexxMsg structure allocated by CreateRexxMsg()
  155.  
  156.     EXAMPLE
  157.     if (rmsg=CreateRexxMsg(myport,"myapp","MYAPP_PORT"))
  158.     {
  159.         /* Do my think with rmsg */
  160.         ClearRexxMsg(rmsg,16);    /* We may not want to clear all 16 */
  161.         DeleteRexxMsg(rmsg);
  162.     }
  163.  
  164.     SEE ALSO
  165.     CreateRexxMsg(), ClearRexxMsg()
  166.  
  167.     BUGS
  168. rexxsyslib.library/FillRexxMsg                 rexxsyslib.library/FillRexxMsg
  169.  
  170.     NAME
  171.     FillRexxMsg - Fill the argument strings as needed
  172.  
  173.     SYNOPSIS
  174.     result = FillRexxMsg(msgptr, count, mask)
  175.     D0                   A0      D0     D1 [0:15]
  176.  
  177.     BOOL FillRexxMsg(struct RexxMsg *,ULONG,ULONG);
  178.  
  179.     FUNCTION
  180.     This function will convert and install up to 16 argument strings into
  181.     a RexxMsg structure.  The message packet's argument fields must be
  182.     set to either a pointer to a NULL terminated string or an integer value
  183.     The mask, bits 0 to 15, correspond to the type of value is stored
  184.     in the argument slot.  If the bit is cleared, the argument is a
  185.     string pointer; if the bit is set, the argument is an integer.
  186.  
  187.     INPUTS
  188.     msgptr - Pointer to a RexxMsg (allocated via CreateRexxMsg)
  189.     count - The number of argument slots to fill in.  This number should
  190.             be from 1 to 16.
  191.  
  192.     mask - A bit mask corresponding to the 16 fields that is used to
  193.            determine the type of the field.
  194.  
  195.     RESULTS
  196.     result - A boolean.  If it is TRUE, the call worked.  If it is false,
  197.              some allocation did not work.  All argstrings that were
  198.              created will be released.
  199.  
  200.     SEE ALSO
  201.     ClearRexxMsg(), CreateArgstring(), DeleteArgstring(), CreateRexxMsg()
  202.  
  203.     BUGS
  204. rexxsyslib.library/IsRexxMsg                     rexxsyslib.library/IsRexxMsg
  205.  
  206.     NAME
  207.     IsRexxMsg - Function to determine if a message came from ARexx
  208.  
  209.     SYNOPSIS
  210.     result = IsRexxMsg(msgptr)
  211.     D0                 A0
  212.  
  213.     BOOL IsRexxMsg(struct RexxMsg *);
  214.  
  215.     FUNCTION
  216.     This function can be used to determine if a message came from an
  217.     ARexx program.
  218.  
  219.     INPUTS
  220.     msgptr - A pointer to the suspected RexxMsg.
  221.  
  222.     RESULTS
  223.     result - A boolean:  TRUE if it is an ARexx message, FALSE if not.
  224.  
  225.     SEE ALSO
  226.     CreateRexxMsg()
  227.  
  228.     BUGS
  229. rexxsyslib.library/LengthArgstring         rexxsyslib.library/LengthArgstring
  230.  
  231.     NAME
  232.     LengthArgstring - Returns the length value stored in the argstring
  233.  
  234.     SYNOPSIS
  235.     length = LengthArgstring(argstring)
  236.     D0                       A0
  237.  
  238.     ULONG LengthArgstring(UBYTE *);
  239.  
  240.     FUNCTION
  241.     This function returns the length value stored in the argstring.
  242.     This is *NOT* the same as doing a strlen() type call on the
  243.     argstring.  (Note that argstrings may contain NULLs)
  244.  
  245.     INPUTS
  246.     argstring - A pointer to an argstring that was created by ARexx
  247.  
  248.     RESULTS
  249.     length - The length of the argstring.
  250.  
  251.     EXAMPLE
  252.  
  253.     SEE ALSO
  254.     CreateArgstring()
  255.  
  256.     BUGS
  257. rexxsyslib.library/LockRexxBase               rexxsyslib.library/LockRexxBase
  258.  
  259.     NAME
  260.     LockRexxBase - Obtain a semaphore lock on the RexxBase structure
  261.  
  262.     SYNOPSIS
  263.     LockRexxBase(resource)
  264.                  D0
  265.  
  266.     VOID LockRexxBase(ULONG);
  267.  
  268.     FUNCTION
  269.     Secures the specified resource in the ARexx library base.
  270.  
  271.     INPUTS
  272.     resource - A manifest constant defining which resource to lock.
  273.                ZERO locks all resources.
  274.  
  275.     NOTES
  276.     Currently, only ZERO resource type is available.  You *MUST* make
  277.     sure that you do not call this function with an undefined value
  278.     as it may become defined at some future date and cause unwanted
  279.     behavior.
  280.  
  281.     SEE ALSO
  282.     UnlockRexxBase()
  283.  
  284.     BUGS
  285. rexxsyslib.library/UnlockRexxBase           rexxsyslib.library/UnlockRexxBase
  286.  
  287.     NAME
  288.     UnlockRexxBase - Release a semaphore lock on the RexxBase structure
  289.  
  290.     SYNOPSIS
  291.     UnlockRexxBase(resource)
  292.                    D0
  293.  
  294.     VOID UnlockRexxBase(ULONG);
  295.  
  296.     FUNCTION
  297.     Releases the specified resource in the ARexx library base.
  298.  
  299.     INPUTS
  300.     resource - A manifest constant defining which resource to unlock.
  301.                This value *MUST* match the value used in the matching
  302.                LockRexxBase() call.
  303.  
  304.     NOTES
  305.     Currently, only ZERO resource type is available.  You *MUST* make
  306.     sure that you do not call this function with an undefined value
  307.     as it may become defined at some future date and cause unwanted
  308.     behavior.  You *MUST* make sure that you only call this function
  309.     after a matching call to LockRexxBase() was made.
  310.  
  311.     SEE ALSO
  312.     LockRexxBase()
  313.  
  314.     BUGS
  315.