NAME

VMS::ICC - VMS ICC systems service interface

SYNOPSIS

use VMS::ICC;
$service_handle = new_service($service_name, $logical_name, $logical_table);
$connection_handle = accept_connection($service_handle);
$connection_handle = open_connection($service, $node);
$data = read_data($connection_handle);
$status = write_data($connection_handle, $data, $async);
$status = close_connection($connection_handle);
$status = delete_service($service_handle);
$old_debug = VMS::ICC::debug($new_level);

DESCRIPTION

The VMS::ICC module provides an interface into the IntraCluster Communication services.

new_service

Registers a service in the cluster. The service_name, logical_name and logical_table parameters are all optional--if you leave one or more out, or pass them as undef, VMS::ICC will use the default values.

Since connection accepts are done in AST routines, and there's no good way to register a perl AST routine, VMS::ICC automatically accepts any connection request and puts it on an internal queue. The queue is currently limited to 25 entries, and any connection requests made while the queue is full will be refused. (Calling accept_connection from perl takes a connect request off the internal queue, opening up a slot for another inbound connection)

This returns a scalar that represents this particular service, though at the moment the scalar is unused and a program can only have one open service at a time.

accept_connection

Accepts a connection and returns a handle to it, or undef if there aren't any pending connections. The service_handle parameter is the same as what's returned by new_service, though it's currently ignored.

open_connection

Opens a connection to a server out there someplace. Makes the connection to the service you specified, optionally on the node you specified. (If no node parameter is passed, the ICC services choose from amongst all the services registered with that name in the cluster)

read_data

Reads a message from the specified connection. This will block waiting for a message to arrive on the specified connection.

Currently messages are limited to a maximum of 1000 bytes.

write_data

Writes data to the specified connection. The data scalar is converted to a string (if it isn't already one) and sent to the other end. If the async flag is set this will return immediately, otherwise it blocks until the message is read on the other end.

close_connection

Closes the specified connection.

delete_service

Deregisters the service and closes any pending accepted but unprocessed connections.

debug

Turns on all sorts of debugging logic. This takes an integer. Bit 0 turns on tracing, bit 1 turns on system service status messages, and bit 2 turns on generall chatty stuff.

LIMITATIONS

Right now a program can only provide one service at a time. This is a limitation that may be lifted in the future.

It's not possible to wait on multiple connections for data, though this limitation may also be lifted in the future. (Or you can use threads if you'd rather)

AUTHOR

Dan Sugalski <DSugalski@cantor.com>

SEE ALSO

perl(1).