Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference
Return to Main Page
NetAccept associates a connection specific event handler and instance data with a connection that was previously handled by the NetListen event handler.
FUNCTION NetAccept (VAL hndlHost: NETCONNECTION, EventHandler {InstanceData} :EVENT, ): INTEGER:
Argument Name | Description |
hndlHost | The handle to the connection. This handle can be used in calls to SendMessage and PostMessage to communicate with a host. It must be serviced by a NetListen event handler to be used in a call to NetAccept. |
EventHandler | Processes messages from the server. |
All connections served by NetListen event handlers share the same copy of the instance data defined for the NetListen event handler. You can associate a specific set of instance data with an open NetListen connection by calling the NetAccept statement for the connection.
Note: NetAccept can be called only for a NetListen connection and only by its handle.
The instance data you associate with the connection is not used with other open connections or that might be open later for the NetListen event handler. After you call NetAccept, the connection is changed. All requests for the same host or service are directed to the new event handler.
When NetAccept is called to assume a NetListen-serviced connection, the event handler passed to NetAccept receives a $MsgCreate to create its instance data. (A NetListen event handler opened the connection before the NetAccept call.)
A NetAccept event handler does the following:
Return codes usually originate from the local machine, unless specified.
Return Code | Description |
1 | Success |
-1 | BAD_HANDLE The NetConnection handle does not refer to a valid handle. This return code could be sent if the server process has been stopped and restarted since the connection was established. This return code could originate from either the local or the remote machine. |
-2 | UNKNOWN_VALUE A parameter with an unknown value has been used with a call that requires the parameter to have a known value. |
-3 | NO_MEMORY Sufficient memory was not available to complete the operation. |
-4 | NO_CREATE A connection could not be created. This return could originate from a local or remote machine at the operating system or the network level. It also applies to other system objects required by the server. NetRegister returns this message if a second Tivoli Script server tries to start on the same port. |
-5 | INVALID_TYPE There are three messages designed to transfer data across a network. $MsgNetInteger, $MsgNetReal, and $MsgNetString only accept a certain data type. This return code appears if an improper argument is passed to a SendMessage or PostMessage statement. |
-10 | OS_CALL_FAILED A call failed at the operating system level. This may be caused by improper configuration or inadequate resources. |
-12 | ERROR_BAD_MSG The SendMessage or PostMessage statement was called with a message that is not supported by the NETx statements (or a user-defined $MsgUser + n message specifically for use with NETx statements). |
-13 | HOST_UNREACHABLE The requested server could not be reached. Either the server is down, or no route exists to the server, or there is no NetListen or NetRegister event handler running on the server. |
-15 | RESOURCE_LOCK Another connection is using shared resources that are required to service the call. This return code may occur if the system is overloaded. |
-16 | SERVICE_NOT_SUPPORTED The server does not support the requested service. |
-17 | NO_CONNECTION There is no valid connection associated with the handle. |
-18 | BAD PORT The port portion of a service string cannot be resolved into a valid port or service. |
NetClose closes a connection.
FUNCTION NetClose (VAL hndlHost: NETCONNECTION ): INTEGER:
Argument | Description |
hndlHost | The handle to the connection |
Before instance data is destroyed, the event handler for the connection receives a $MsgDestroy message.
Note: If the connection is severed by a NetListen event handler, instance data is not destroyed.
When the client initiates a closure, NetClose closes the connection on
the client side. The server detects the closed connection and sends the connection event
handler a $MsgNetClose message.
The server destroys any instance data associated with the connection before it closes the
connection.
NetConnect establishes a connection between two networked machines.
NetConnect has two syntax formats: client and peer-to-peer. The primary format (listed as the client/server variation), is used to open connections in either the client or peer-to-peer architectures.
The following is the client syntax.
FUNCTION NetConnect (REF hndlHost: NETCONNECTION, VAL hostName: STRING, VAL service: STRING ): INTEGER;
The following is the peer-to-peer syntax.
FUNCTION NetConnect( VAL hndlHost: NETCONNECTION ): INTEGER;
Note: Peer-to-peer is a shortcut for creating a return connection.
Argument Name | Description |
hndlHost | The handle to the server. Use this handle in calls to SendMessage and PostMessage to communicate with the server. If a handle already exists for the host/service pair, calling NetConnect returns that handle. If you use the peer-to-peer format, the handle is initialized for the return connection. |
hostName | The name or IP of the intended server. |
service | The name of a specific service the client requests from the
server. If you specify the service name as a zero-length string or $Unknown, the
server searches for a wildcard service. (The service name can be up to 256 characters.) If the service is not found on the server, the server attempts to match the service request with a wildcard service or a generic service (one registered with a NetListen event handler). A port number for the remote machine can be appended to the service string with the following form: service : nnnn where nnnn is an TCP/IP port number. Otherwise, the form is: service : name where name is an TCP/IP service name. |
If you call NetConnect on a handle associated with an existing connection, NetConnect does not re-open the connection, but verifies that the following is true:
SourceName : Port
The default service is ASENET/TCP. The default port is 5005.
Returns the remote address associated with an active connection
FUNCTION NetGetAddress( VAL handle : NETCONNECTION ) : STRING;
Argument Name | Description |
handle | Handle of the active connection |
Returns unknown on error or if the connection is not active.
NetGetHostName returns the name (or machine ID) of the server associated with a connection when it is called on a client. NetGetHostName returns the name of the client when it is called on the server.
FUNCTION NetGetHostName( VAL hndlHost: NETCONNECTION ): STRING:
Argument Name | Description |
hndlHost | The handle to the server |
You can obtain a handle from either of the following sources:
Return Code | Description |
NetGetHostName | Returns the name (or machine ID) of the server associated with the handle |
Note: $Unknown is returned if an error occurs or no server is associated
with a handle.
Returns the IP address of the local machine as reported by the standard IP name resolution method (usually DNS or the host's file).
FUNCTION NetGetLocalAddress : STRING;
If the network configuration has discrepancies, this function may not report the address configured for the machine. If the host has multiple addresses, it will report the one known to DNS or the host's file.
Returns unknown on error.
NetGetService returns the name string of the network service associated with a connection.
FUNCTION NetGetService ( VAL hndlHost: NETCONNECTION ): STRING:
Argument Name | Description |
hndlHost | The handle to the server |
You can obtain the handle from either a NetConnect or the $Handle parameter to an event handler serviced by NetListen, NetAccept, or NetRegister. (NetGetService does not return the port portion of a service specification.)
Return Code | Description |
NetGetService | Returns the name of the service associated with the handle |
Note: $Unknown is returned if an error occurs or no server is associated
with a handle.
NetListen registers a generic event handler to process requests from clients.
FUNCTION NetListen( EventHandler EVENT): INTEGER:
Argument Name | Description |
EventHandler | An event handler of type NetConnection that processes requests from a client |
Requests for Service
A NetListen event handler receives requests for services if there is no matching NetRegister or wildcard service. A second call to NetListen replaces the event handler and instance data with new instance data.
Each time a new connection is opened for the NetListen event handler, a $MsgNetConnect is sent to the NetListen event handler.
A NetListen event handler has one set of shared instance data for all connections opened for it. The event handler receives a $MsgCreate message when it is registered and a $MsgDestroy message when it is unregistered.
Calls to the NetListen event handler provide a handle to the client in $Handle and the message in $Event.
When a connection that is being handled by a NetListen event handler is closed, the NetListen event handler receives a $MsgNetClose for that connection.
NetLoopBack sends a message to a local event handler servicing a connection to a remote machine.
FUNCTION NetLoopBack (VAL hndlHost NETCONNECTION VAL message: INTEGER, ANY ... ): INTEGER:
Argument Name | Description |
hndlHost | A handle to a server. The handle must be designated for an open connection with a remote machine. |
SendMessage
NetRegister registers an event handler source port that accepts connections from network clients. Unlike NetListen, NetRegister can run many event handlers on a server simultaneously.
FUNCTION NetRegister(EventHandler EVENT, VAL service STRING ): INTEGER:
Argument Name | Description |
EventHandler | Processes messages from the client. |
service | The name of the service that is being provided by the server. Service
names are limited to 255 characters. A port number for the remote machine can be appended to the service string with the following form: service : nnnn where nnnn is a TCP/IP port number. Otherwise, the form is: service : name where name is a TCP/IP service name. |
When you register an event handler, you specify the name of the service that it provides. If you register the service as either a zero-length string or $Unknown, the event handler can process any requested service.
When you register an event handler, you can also associate instance data with it. This instance data is initialized for the connection when the connection is opened. (Specifying the port as part of the service allows the server process to run on a single machine.)
Enables network tracing. Usually only helpful in debugging application problems.
Note: An optional filter can be used with NetTrace that enables you to specify what kind of messages to trace instead of receiving all messages. (For example, you may only want to trace error messages). The optional syntax is shown after the standard syntax.
FUNCTION NetTrace( VAL traceFile : STRING ) : INTEGER;
Function NetTrace( VAL fileName : STRING VAL flags : STRING ) : INTEGER;
Argument Name | Description |
traceFile | Name of the file to write trace data to. |
fileName | Name of file to write the filtered trace data to. |
flags | Controls what trace data is written. Flags can be any of the following:
|
A very large quantity of data may be produced.
NetTrace supports the use of unicode which recognizes the double-byte character encoding in asian languages. The environment variable is the following:
SAI_NET_USE_UNICODE
This variable is off by default.
Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference