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

@{"DLGRexx-Port/-- Overview --" LINK "-- Overview --"}
@{"DLGRexx-Port/ActivatePort()" LINK "ActivatePort()"}
@{"DLGRexx-Port/DeactivatePort()" LINK "DeactivatePort()"}
@{"DLGRexx-Port/FreePort()" LINK "FreePort()"}
@{"DLGRexx-Port/GetPortInfo()" LINK "GetPortInfo()"}
@{"DLGRexx-Port/ImmedLockPort()" LINK "ImmedLockPort()"}
@{"DLGRexx-Port/ListPorts()" LINK "ListPorts()"}
@{"DLGRexx-Port/LockPort()" LINK "LockPort()"}
@{"DLGRexx-Port/TransferPortLock()" LINK "TransferPortLock()"}
@endnode

@node "-- Overview --" "DLGRexx-Port/-- Overview --"

Port commands are a subset of Resource Manager commands. They are used to open,
activate, close, and gain ownership of DLG's communication ports.

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

   -2    Port already active
            Don't activate the same port twice.

   -3    Port not active
            Deactivation and locking requires an active port.

   -4    Port not locked
            You'll see this if you used the wrong password or if you're
            going for an "immediate" 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

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 "ActivatePort()" "DLGRexx-Port/ActivatePort()"

NAME
   ActivatePort

   Activate a port for use.

USAGE
   ActivatePort ( Port, [ BGCommand ] )

      Port:       The name of the port that you want to activate. (string)

      BGCommand:  A background command that you want to launch upon port
                  activation. This command should accomplish something useful,
                  such as monitoring the port for incoming calls. DLG:Setup is
                  usually used for regular ports; GETTY and TrapDoor are other
                  popular choices. (optional) (string)

NOTES
   Functionally equivelent to DLG:ActivatePort

SEE ALSO
   DeactivatePort()

@endnode

@node "DeactivatePort()" "DLGRexx-Port/DeactivatePort()"

NAME
   DeactivatePort

   Remove a port from the list of active ports. The port must be active already.

USAGE
   DeactivatePort ( Port, [ Password ] )

      Port:       The name of the port that you want to deactivate. (string)

      Password:   A password to use to lock the port.  If the port is not
                  already locked with a password, you may leave this out and DLG
                  will supply a password to use while deactivating. If the port
                  has been previously locked with a password, you must supply
                  the same password to get the port. (optional) (string)

NOTES
   Functionally equivelent to DLG:DeactivatePort

SEE ALSO
   ActivatePort()

@endnode

@node "FreePort()" "DLGRexx-Port/FreePort()"

NAME
   FreePort

   Release the lock on a port. You must have already locked it for this to work.

USAGE
   FreePort ( Port, [ Password ] )

      Port:       The name of the port that you want to release. (string)

      Password:   A password used to lock the port.  If the port 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
   Functionally equivelent to DLG:FreePort

SEE ALSO
   LockPort(), ImmedLockPort(), TransferPortLock()



@endnode

@node "GetPortInfo()" "DLGRexx-Port/GetPortInfo()"

NAME
   GetPortInfo (V2)

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

   PASS "<password>" REASON "<reason>" PRI <priority> BREAKCMD <"break command">

   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.

USAGE
   GetPortInfo( port )

      Port:       The name of the port that you want to examine. (string)

NOTES
   Functionally equivelent to DLG:PortInfo

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

   Note that while all 4 fields of the PortInfo 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 parameter that is guaranteed
   to have something is the priority.

SEE ALSO
   FreePort(), LockPort(), ImmedLockPort()


@endnode

@node "ImmedLockPort()" "DLGRexx-Port/ImmedLockPort()"

NAME
   ImmedLockPort

   Lock the specified port immediately.  If an immediate lock cannot be
   achieved, it returns immediately with error code -4.

USAGE
   ImmedLockPort ( Port, [ Password ], [ Reason ], [ Priority ], [ Break ] )

      Port:       The name of the port that you want to lock. (string)

      Password:   The password used to lock the port.  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 port, the one with the highest priority will get
                  the lock. Defaults to 0. (numeric) (optional). You must also
                  specify a password and reason.

      Break       An external command that is used to break (interrupt) your
                  process if another process locks the port with a higher
                  priority. If the port is one that has a high level of
                  contention, you should supply this command --otherwise, the
                  system may lock up waiting for your program to release a port.
                  You must also specify a password, reason, and priority.

NOTES
   Functionally equivelent to DLG:GetPort with -i option.

SEE ALSO
   FreePort(), LockPort(), TransferPortLock()


@endnode

@node "ListPorts()" "DLGRexx-Port/ListPorts()"

NAME
   ListPorts (V2)

   List active ports. You may specify a password to search for, in which case
   only the ports locked with that password will be displayed.

   Resulting text returned is in the form

      TxyTxyTxy

   in that T specifies the first character in the port name, x is either R for
   remote, N for network, or L for local, and y is the device number (0 through
   9). Thus, you might see

      TL0TL1TR0TR1TR2TN1

   returned.

   If an error occurs, it will return a numeric error code as specified in the
   overview.

   If no ports match your password criteria, or if no ports are active, you will
   get a -3 returned.

   If you do not get a numeric error code, you can assume all went well
   and that the information provided is legitimate.

USAGE
   ListPorts( [ password ] )

      Password:   The locking password you are searching for (optional). Don't
                  specify a password if you want to see all ports.

NOTES
   Functionally equivelent to DLG:ListPorts.

SEE ALSO



@endnode

@node "LockPort()" "DLGRexx-Port/LockPort()"

NAME
   LockPort

   Lock the specified port, pending the lock until the port is free.

USAGE
   LockPort ( Port, [ Password ], [ Reason ], [ Priority ], [ Break ] )

      Port:       The name of the port that you want to lock. (string)

      Password:   The password used to lock the port.  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 port, the one with the highest priority will get
                  the lock. Defaults to 0. (numeric) (optional). You must also
                  specify a password and reason.

      Break       An external command that is used to break (interrupt) your
                  process if another process locks the port with a higher
                  priority. If the port is one that has a high level of
                  contention, you should supply this command --otherwise, the
                  system may lock up waiting for your program to release a port.
                  You must also specify a password, reason, and priority.

NOTES
   This function will pend until the port is available for lock. Use this
   function only in places where you know that the port 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
   ImmedLockPort instead -- that's what it's for.

   Functionally equivelent to DLG:GetPort

SEE ALSO
   FreePort(), ImmedLockPort(), TransferPortLock()

@endnode

@node "TransferPortLock()" "DLGRexx-Port/TransferPortLock()"

NAME
   TransferPortLock

   Changes the status of a locked port.

USAGE
   TransferPortLock ( Port, [ OldPassword ], [ NewPassword ], [ Reason ],
                            [ Priority ], [ Break ] )

      Port:       The name of the port that you want to lock. (string)

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

     NewPassword: The new password to lock the port with.  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)

      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 port, the one with the highest priority will get
                  the lock. Defaults to 0. (numeric) (optional)

      Break       An external command that is used to break (interrupt) your
                  process if another process locks the port with a higher
                  priority. If the port is one that has a high level of
                  contention, you should supply this command --otherwise, the
                  system may lock up waiting for your program to release a port.

NOTES
   Functionally equivelent to DLG:TransferPort

SEE ALSO
   FreePort(), LockPort(), ImmedLockPort()


@endnode
@endnode
