@database
@node main "DLGRexx-Area.guide"
TABLE OF CONTENTS

@{"DLGRexx-Area/-- Overview --" LINK "-- Overview --"}
@{"DLGRexx-Area/BorrowArea()" LINK "BorrowArea()"}
@{"DLGRexx-Area/EnterArea()" LINK "EnterArea()"}
@{"DLGRexx-Area/FreeArea()" LINK "FreeArea()"}
@{"DLGRexx-Area/GetAreaInfo()" LINK "GetAreaInfo()"}
@{"DLGRexx-Area/LeaveArea()" LINK "LeaveArea()"}
@{"DLGRexx-Area/LockArea()" LINK "LockArea()"}
@endnode

@node "-- Overview --" "DLGRexx-Area/-- Overview --"

Area commands were all implemented in V2 of dlgrexx.library.

Area commands are a subset of Resource Manager commands. They are used to lock,
enter, borrow, and otherwise control DLG's message and file areas.

Unless indicated otherwise, the commands will return a 0 for no error.
Otherwise, the error code will come from this list:

   -4    Area not locked
            You'll see this if you used the wrong password or if you're
            going for an "borrow" lock which fails.

   -5    ResMan not active
            You'll get this if DLG's resource manager, ResMan, is not running.
            This probably means you don't have DLG running, either.

   -6    Out of Memory

   -7    Area has users in it
            You'll get this if you are attemting to lock an area and there are
            users within it. You'll have to get rid of them first.

   -8    Area not active
            You'll get this if you are attempting to release a lock on an area
            that you do not have a lock on.

   -9    Area has no users in it
            You'll get this if you are attempting to get user info in an empty
            area.

Unlike the port functions, you have slightly less control over the functions you
are using. For example, when attempting to lock an area, we assume you want an
exclusive lock and that it will pend until the area is empty. However, there
are a number of functions that make up for this lack of control. For example,
you can use BorrowArea() instead of LockArea() if you don't want an exclusive
lock. Likewise, you can use EnterArea() to simulate a user in the area and keep
other locks from removing the area from active use.

All area functions require that you specify the type of area -- 0 for message, 1
for file.

Parameters bracketed in brackets [ like this ] are optional.

If you wish to use one of the optional parameters, you must use all previous
parameters in the parameter list as well. For example, if a function has this
template:

   Function ( manditory, [opt 1], [opt 2])

then you could use the following:

   Function(manditory)
   Function(manditory, opt 1)
   Function(manditory, opt 1, opt 2)

but not

   Function(manditory, opt 2)

and CERTAINLY NOT

   Function(opt 1)

This document is provided in pseudo-autodoc format, and was prepared using the
BGUI developer utility CAD (Create AutoDoc), with thanks.

@endnode

@node "BorrowArea()" "DLGRexx-Area/BorrowArea()"

NAME
   BorrowArea (V2)

   Lock the specified area, pending the lock until other locks are freed, and
   allowing users to enter and leave as desired.

USAGE
   BorrowArea ( Area, [ Type ], [ Password ], [ Reason ], [ Priority ] )

      Area:       The area to lock.

      Type:       The type of area - 0 for message area, 1 for file area. If not
                  specified, 0 is assumed.

      Password:   The password used to lock the area.  If you leave it blank,
                  DLG will supply an internal password. (optional) (string)

      Reason:     While this doesn't affect functionality, giving a reason for
                  the lock is helpful to users online at the time. (string)
                  (optional). You must also specify a password.

      Priority    A value between -127 and 128 inclusive, indicating the
                  priority of your lock. If two or more processes are trying to
                  lock the same area, the one with the highest priority will get
                  the lock. Defaults to 0. (numeric) (optional). You must also
                  specify a password and reason.

NOTES
   To use this function, you must first use EnterArea() to increase the user
   count (which keeps exclusive locks from happening). Once you are done with
   the area, you must use LeaveArea() to decrease the user count appropriately.
   If you fail to do so, your system will eventually hang up somewhere when
   something tries to exclusively lock the area.

   You must free your lock before leaving the area. If you do not free your
   lock, a later attempt to borrow the area will hang the system and the port.

   Above all, after borrowing an area, do your stuff and free it quickly! All
   other DLG library functions that access file and message areas do their own
   BorrowArea/FreeArea, so you must release the lock before using them. This
   applies double for most DLG programs like MESS and FILE.

SEE ALSO
   FreeArea(), LockArea(), EnterArea(), LeaveArea()


@endnode

@node "EnterArea()" "DLGRexx-Area/EnterArea()"

NAME
   EnterArea (V2)

   Increase the user count in an area by 1 -- essentially, simulates a user in
   an area. This will prevent the area being locked from use.

USAGE
   EnterArea ( Area, [ Type ] )

      Area:       The area to enter.

      Type:       The type of area - 0 for message area, 1 for file area. If not
                  specified, 0 is assumed.

NOTES
   This is functionally equivelent to DLG:EnterArea.


SEE ALSO
   LeaveArea()


@endnode

@node "FreeArea()" "DLGRexx-Area/FreeArea()"

NAME
   FreeArea (V2)

   Release the lock on an area. You must have already locked it for this to
   work.

USAGE
   FreeArea ( Area, Type, [ Password ] )

      Area:       The area number (number)

      Type:       0 for message area, 1 for file area. (optional -- if not
                  specified, 0 is assumed).

      Password:   A password used to lock the area.  If the area was not locked
                  with a password, you must leave this out. If the port has been
                  previously locked with a password, you must supply the same
                  password to get the port. (optional) (string)

NOTES

SEE ALSO
   LockArea(), BorrowArea()



@endnode

@node "GetAreaInfo()" "DLGRexx-Area/GetAreaInfo()"

NAME
   GetAreaInfo (V2)

   Gets information about a specified area. The returned information is in the
   form:

   PASS "<password>" REASON "<reason>" PRI <priority> USERS <users>

   or else it returns numeric error code as specified in the overview. If you do
   not get a numeric error code, you can assume all went well and that the
   information provided is legitimate. Otherwise, if it is a numeric code AND
   less than 0, something went wrong.

   The one exception to this is code -8 -- if no users are present in an area,
   you will get this error message, but it might be normal for your situation.

USAGE
   GetAreaInfo( area, [ type ] )

      Area: The area that you want to examine. (1 - 9999)

      Type: 0 for message area, 1 for file area. If not supplied, 0 is assumed.

NOTES
   Functionally equivelent to DLG:AreaInfo

   This function automatically frees the DLGAreaInfo after it uses it, so an
   Arexx FreeAreaInfo is not required.

   Note that while all 4 fields of the DLGAreaInfo struct (as defined in
   resman.h) are returned, they may not be filled in. For example, if no reason
   was given for the lock, you will see REASON "". The only parameters that are
   guaranteed to have something are the priority and user count.

SEE ALSO


@endnode

@node "LeaveArea()" "DLGRexx-Area/LeaveArea()"

NAME
   LeaveArea (V2)

   Decrease the user count in an area by 1 -- essentially, simulates a user
   leaving an area. This will allow the area to be locked, if no other users are
   in the area.

USAGE
   LeaveArea ( Area, [ Type ] )

      Area:       The area to leave.

      Type:       The type of area - 0 for message area, 1 for file area. If not
                  specified, 0 is assumed.

NOTES
   This is functionally equivelent to DLG:LeaveArea.


SEE ALSO
   LeaveArea()


@endnode

@node "LockArea()" "DLGRexx-Area/LockArea()"

NAME
   LockArea (V2)

   Lock the specified area, pending the lock until the area is empty of users.

USAGE
   LockArea ( Area, [ Type ], [ Password ], [ Reason ], [ Priority ] )

      Area:       The area to lock.

      Type:       The type of area - 0 for message area, 1 for file area. If not
                  specified, 0 is assumed.

      Password:   The password used to lock the area.  If you leave it blank,
                  DLG will supply an internal password. (optional) (string)

      Reason:     While this doesn't affect functionality, giving a reason for
                  the lock is helpful to users online at the time. (string)
                  (optional). You must also specify a password.

      Priority    A value between -127 and 128 inclusive, indicating the
                  priority of your lock. If two or more processes are trying to
                  lock the same area, the one with the highest priority will get
                  the lock. Defaults to 0. (numeric) (optional). You must also
                  specify a password and reason.

NOTES
   This function will pend until the area is available for lock -- i.e. until
   it is empty of users.. Use this function only in places where you know that
   the area will be freed within a reasonable amount of time. If you are
   uncertain of this, and if you suspect that your entire BBS will be locked up
   because of a pending lock, then use BorrowArea() instead -- that's what it's
   for.

SEE ALSO
   FreeArea(), BorrowArea()

@endnode
@endnode
