Tivoli Service Desk 6.0 Developer's Toolkit Script Language Reference

Network Handling

Return to Main Page


NetAccept

Description

NetAccept associates a connection specific event handler and instance data with a connection that was previously handled by the NetListen event handler.

Syntax

FUNCTION NetAccept (VAL hndlHost: NETCONNECTION,
                    EventHandler {InstanceData} :EVENT,
                    ): INTEGER:

Argument Notes

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.

Notes

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 for All Network Statements

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.

See Also


NetClose

Description

NetClose closes a connection.

Syntax

FUNCTION NetClose (VAL hndlHost: NETCONNECTION
                   ): INTEGER:

Argument Notes

Argument Description
hndlHost The handle to the connection

Notes

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.

See Also


NetConnect

Description

NetConnect establishes a connection between two networked machines.

Syntax

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 Notes

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.

Notes

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.

See Also


NetGetAddress

Description

Returns the remote address associated with an active connection

Syntax

FUNCTION NetGetAddress( VAL handle : NETCONNECTION ) : STRING;

Argument Notes

Argument Name Description
handle Handle of the active connection

Return Codes

Returns unknown on error or if the connection is not active.


NetGetHostName

Description

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.

Syntax

FUNCTION NetGetHostName( VAL hndlHost: NETCONNECTION
                         ): STRING:

Argument Notes

Argument Name Description
hndlHost The handle to the server

Notes

You can obtain a handle from either of the following sources:

Return Codes

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.

See Also


NetGetLocalAddress

Description

Returns the IP address of the local machine as reported by the standard IP name resolution method (usually DNS or the host's file).

Syntax

FUNCTION NetGetLocalAddress : STRING;

Notes

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.

Return Codes

Returns unknown on error.


NetGetService

Description

NetGetService returns the name string of the network service associated with a connection.

Syntax

FUNCTION NetGetService ( VAL hndlHost: NETCONNECTION
                         ): STRING:

Argument Notes

Argument Name Description
hndlHost The handle to the server

Notes

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 Codes

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.

See Also


NetListen

Description

NetListen registers a generic event handler to process requests from clients.

Syntax

FUNCTION NetListen( EventHandler EVENT): INTEGER:

Argument Notes

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.

Opening a Connection

Each time a new connection is opened for the NetListen event handler, a $MsgNetConnect is sent to the NetListen event handler.

Instance Data for a Connection

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

Calls to the NetListen event handler provide a handle to the client in $Handle and the message in $Event.

Closing a Connection

When a connection that is being handled by a NetListen event handler is closed, the NetListen event handler receives a $MsgNetClose for that connection.

See Also


NetLoopBack

Description

NetLoopBack sends a message to a local event handler servicing a connection to a remote machine.

Syntax

FUNCTION NetLoopBack (VAL hndlHost NETCONNECTION
                      VAL message: INTEGER, ANY ...
                      ): INTEGER:

Argument Notes

Argument Name Description
hndlHost A handle to a server. The handle must be designated for an open connection with a remote machine.

See Also

SendMessage


NetRegister

Description

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.

Syntax

FUNCTION NetRegister(EventHandler EVENT,
                     VAL service STRING
                     ): INTEGER:

Argument Notes

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.

Notes

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.)

See Also


NetTrace

Description

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.

Syntax

FUNCTION NetTrace( VAL traceFile : STRING ) : INTEGER;

Optional Filter Syntax

Function NetTrace( VAL fileName : STRING
                   VAL flags : STRING
                   ) : INTEGER;

Argument Notes

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:
  • NETTraceAll
  • NETTraceApp
  • NETTraceClient
  • NETTraceConnections
  • NETTraceDebug
  • NETTraceErrors
  • NETTraceInfo

Notes

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

Return to Main Page

Copyright