Chapter 1: System Procedures

sp_listener

Description

Dynamically starts and stops listeners on Adaptive Server on any given port on a per-engine basis.

Syntax

sp_listener “command”, “server_name”, engine | remaining

Or:

sp_listener “command”, “[protocol:]machine:port”, engine

Parameters

command

can be any of the following:

start – starts a listener on the specified ports on each of the specified engines
stop – terminates the specified listeners.
suspend – prevent the listener from accepting any more connections.
resume – instructs suspended listeners to resume listening again.
status – report on the state of the listeners specified by the parameters. The state is one of: active, stopped, or suspended.

server_name: is the name of the Adaptive Server, as specified in the interfaces file.

engine: specifies the number of the engine affected by this command. engine can be a single-engine number in quotes (“2”), a list (“3,5,6”), a range (“2 – 5”), or mix of all (“2,3 – 5,7”).

The engine parameter is ignored by Windows NT.

remaining: specifies that the command is to take effect on all engines on which it can be meaningfully applied (that is, where the listener is in a state in which the command is can take effect).

protocol: the type of protocol. This can be one of: tcp, tli, ssltcp, ssltli, winsock, sslnlwnsck, sslwinsock.

machine:port: the machine name and port number (as specified in the interfaces file) to which the listener connects.

Examples

Example 1

Create tcp listeners on engines 0-6 for port number 4226:

sp_listener "start", "goldie:4226", "0-6"

Example 2

Create listeners for all master entries in the interfaces file for server orion:

sp_listener "start", "orion", "remaining"

Example 3

Start listeners on engines 1, 3 and 5 for each master entry in the interfaces file corresponding to server orion:

sp_listener "start", "orion", "1,3,5"

Example 4

Start TCP listeners on port 4226 on machine goldie for all engines not already listening to this port:

sp_listener "start", "goldie:4226", "remaining"

Example 5

Stop the listener on port number 4226 on engine number 2:

sp_listener "stop", "tcp:goldie:4226", "2"

Example 6

Stop all listeners on port number 4226 for all engines. Because this command includes the remaining parameter, it will not fail if some engines are not listening to the port:

sp_listener "stop", "tcp:goldie:4226", "remaining"

Example 7

Suspend NT Winsock listener on port 4226:

sp_listener "suspend", "winsock:clouds:4226"

Example 8

Resume NT Winsock listener on port 4227:

sp_listener "suspend", "winsock:clouds:4226"

Example 9

Resume all active listeners on port number 4226:

sp_listener "resume", "tcp:goldie:4226", "remaining"

Usage

sp_listener uses either of two syntaxes, described in the syntax section, above. The first syntax affects all Adaptive Server master ports listed in the interfaces file. The second allows you to manage listeners not listed in the interfaces file.
The semantics for sp_listener is atomic: if a command cannot be completed successfully, it is aborted.
You can issue the status parameter by itself. The status parameter displays the state of all the listeners in the interfaces file.
A listener can be in one of the following states: stopped, suspended, or active. sp_listener allows you to move listeners between these states. A request to move to a non-permissible state results in failure (For example, requesting to stop a non existent listener). Use sp_listener “status” to determine the state of a listener.
You can specify engines in the engine list as: an engine number (a single interger in quotes), a range of engine numbers (“3-6”), a comma separated list of engines (“2,5,9”), or combinations of the previous two (“2,5,3-6,9”).
The remaining parameter specifies that, for the command you are running (start, stop, resume, and so on), the command runs successfully for all listeners that are in a state that allow the change (for example, moving states from start to stop). For example, if you attempt to start listeners on engines one through six, but engines one, four, and five are unavailable, sp_listener... “remaining” starts listeners on engines two, three, and six, disregarding the offline engines. You cannot specify an engine number if you include the remaining parameter.
The maximum number of listeners is 32. If you create an Adaptive Server with two master ports in the interfaces file, you can start at most 30 more listeners on other ports. Apart from the first listener, each supplementary listener consumes resources similar to a user connection, so in a setup where 25 user connections are configured, starting three listeners at startup (corresponding to three master entries) leaves room for 30 user connections.

Permissions

Auditing

Values in event and extrainfo columns from the sysaudits table are:

Event	Audit option	Command or access audited	Information in extrainfo
38	exec_procedure	Execution of a procedure	Roles – Current active roles Keywords or options – NULL Previous value – NULL Current value – NULL Other information – All input parameters Proxy information – Original login name, if set proxy in effect

View this book as PDF