HP OpenVMS Systems Documentation

HP OpenVMS System Services Reference Manual

At image exit, as a result of closing any open user mode associations, all user mode connections are disconnected. Inner mode connections are the responsibility of the inner mode code, but are disconnected at process termination when inner mode associations are closed. Connections are only visible to the mode in which they were opened.

A client opens connections with the $ICC_CONNECT service; a server opens connections with the $ICC_ACCEPT service.

Required Access or Privileges

SYSNAM, or access via ICC Security Object. Refer to the HP OpenVMS System Manager's Manual for more information.

Required Quota

$ICC_CONNECT changes the process BYTLM quota for the length of the conn_buf parameter, as well as a fixed value for each potential Receive buffer on the connection. The number of potential Receive buffers is specified by the MAXFLOWBUFCNT parameter in the $ICC_OPEN_ASSOC service.

If $ICC_OPEN_ASSOC is not called before $ICC_CONNECT, the default value of MAXFLOWBUFCNT is used (currently 5).

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECTW, $ICC_DISCONNECT, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_BUFFEROVF	Overflow on inbound accept or reject data.
SS$_EXQUOTA	Not enough AST quota (asynchronous request) or insufficient BYTLM/BYTCNT.
SS$_INSFARG	Too few arguments were supplied, or required arguments not supplied.
SS$_INSFMEM	Not enough system resources or process virtual memory available.
SS$_INSFP1POOL	Not enough process P1 space available.
SS$_IVBUFLEN	The length of the context data or the accept or reject data buffer is more than 1000 bytes.
SS$_IVCHAN	Invalid association handle.
SS$_IVMODE	Attempted to open a connection from a more privileged access mode than the requested association.
SS$_LINKABORT	The communications link to the target node was lost.
SS$_LINKDISCON	The communications link to the target node was lost.
SS$_NOLINKS	Too many connections open.
SS$_NOLOGNAM	The underlying layers failed to start properly during system initialization.
SS$_NOPRIV	No privilege to connect to the specified association. Connection access is granted either through an ICC security object or through the SYSNAM privilege. If no security object exists and the caller lacks the SYSNAM privilege, SS$_NOPRIV is returned rather than SS$_NOSUCHOBJ.
SS$_NOSUCHOBJ	The remote association name and/or node was not found.
SS$_NOSUCHNODE	The target node is not known.
SS$_PATHLOST	The communications link to the target node was lost.
SS$_REMRSRC	Insufficient resources at remote node.
SS$_REJECT	The remote association or node rejected the connection request.
SS$_TOO_MANY_ARGS	Too many arguments specified.
SS$_UNREACHABLE	Target node currently unreachable.
SS$_WRONGSTATE	Connection is in the wrong state for the request.

Establishes a link between two ICC associations.

The $ICC_CONNECTW service completes synchronously; that is, it returns to the caller after the server has either accepted or rejected the connection request.

For asynchronous completion, use the $ICC_CONNECT service; $ICC_CONNECT returns to the caller as soon as the connection request has been sent to the server, without waiting for a response from the server.

On Alpha and I64 systems, this service accepts 64-bit addresses.

Format

SYS$ICC_CONNECTW ios_icc, [astadr], [astprm], assoc_handle, conn_handle, remote_assoc, [remote_node], [user_context], [conn_buf], [conn_buf_len], [return_buf], [return_buf_len], [retlen_addr], [flags]

C Prototype

int sys$icc_connectw (struct _ios_icc *ios_icc, void (*astadr)(__unknown_params), __int64 astprm, unsigned int assoc_handle, unsigned int *conn_handle, void *remote_assoc, void *remote_node, unsigned int user_context, char *conn_buf, unsigned int conn_buf_len, char *return_buf, unsigned int return_buf_len, unsigned int *retlen_addr, unsigned int flags);

Terminates the specified connection.

On Alpha and I64 systems, this service accepts 64-bit addresses.

Format

SYS$ICC_DISCONNECT conn_handle ,iosb ,[astadr] ,[astprm] ,[disc_buf] ,[disc_buf_len]

C Prototype

int sys$icc_disconnect (unsigned int conn_handle, struct _iosb, *iosb, void (*astadr)(__unknown_params), __int64 astprm, char * disc_buf, unsigned int disc_buf_len);

Arguments

conn_handle

OpenVMS usage:	connection_id
type:	longword (unsigned)
access:	read only
mechanism:	by value

The ID of the connection to be disconnected.

iosb

OpenVMS usage:	io_status_block
type:	quadword (unsigned)
access:	write only
mechanism:	by 32-bit or 64-bit reference (Alpha and I64); by 32-bit reference (VAX)

I/O status block:

Completion status values:

SS$_NORMAL, SS$_EXQUOTA, SS$_LINKDISCON, $ICC_REJECT

astadr

astprm

disc_buf

disc_buf_len

Description

This service must be called in the mode in which the association was opened.

This service terminates the specified connection. After this service is called, no further communication is possible over this connection. All outstanding data transmission and reception functions are terminated with an error before completion is signaled by calling the AST (if supplied).

A connection may be disconnected by either party. Proper programming procedure for network communications strongly recommends that the party that last received a message initiate the disconnection. If the party that last sent a message initiates the disconnection, there is no guarantee that the message was delivered.

Similarly, although this interface provides the ability to send disconnect data, only noncritical information should be transmitted with the disconnect data mechanism, because there is no guarantee that the data will have been received or acted upon by the other party to the connection.

Required Access or Privileges

None.

Required Quota

BYTLM (disc_buf)

Related Services

$ICC_ACCEPT, $ICC_CLOSE_ASSOC, $ICC_CONNECT, $ICC_CONNECTW, $ICC_DISCONNECTW, $ICC_OPEN_ASSOC, $ICC_RECEIVE, $ICC_RECEIVEW, $ICC_REJECT, $ICC_REPLY, $ICC_REPLYW, $ICC_TRANSCEIVE, $ICC_TRANSCEIVEW, $ICC_TRANSMIT, $ICC_TRANSMITW

Condition Values Returned

SS$_NORMAL	Normal successful completion.
SS$_ACCVIO	Access violation on parameter.
SS$_BADPARAM	Bad parameter value specified.
SS$_INSFMEM	Not enough nonpaged pool.
SS$_IVBUFLEN	The length of the disconnect data buffer is more than 1000 bytes.
SS$_IVCHAN	Unknown connection specified or invalid connection handle.
SS$_IVMODE	Attempted to disconnect a connection from a more privileged access mode than the requested connection.
SS$_LINKDISCON	The remote association closed the connection before it was accepted or rejected.
SS$_TOO_MANY_ARGS	Too many arguments specified.

Terminates a link between two ICC associations.

The $ICC_DISCONNECTW service completes synchronously; that is, it returns to the caller after the connection has completely finished the disconnection request.

For asynchronous completion, use the $ICC_DISCONNECT service; $ICC_DISCONNECT returns to the caller as soon as the disconnection request has been sent to the transport layer, without waiting for notification that the disconnection has completed.

On Alpha and I64 systems, this service accepts 64-bit addresses.

Format

SYS$ICC_DISCONNECTW conn_handle ,iosb ,[astadr] ,[astprm] ,[disc_buf] ,[disc_buf_len]

C Prototype

int sys$icc_disconnectw (unsigned int conn_handle, struct _iosb, *iosb, void (*astadr)(__unknown_params), __int64 astprm, char * disc_buf, unsigned int disc_buf_len);

Declares an application association with ICC.

On Alpha and I64 systems, this service accepts 64-bit addresses.

Format

SYS$ICC_OPEN_ASSOC assoc_handle ,[assoc_name] ,[logical_name] ,[logical_table] ,[conn_event_rtn] ,[disc_event_rtn] ,[recv_rtn] ,[maxflowbufcnt] ,[prot]

C Prototype

int sys$icc_open_assoc (unsigned int *assoc_handle, void *assoc_name, void *logical_name, void *logical_table, void (*conn_event_rtn)(__unknown_params), void (*disc_event_rtn)(__unknown_params), void (*recv_rtn)(__unknown_params), unsigned int maxflowbufcnt, unsigned int prot);

Arguments

assoc_handle

OpenVMS usage:	association_id
type:	longword (unsigned)
access:	write only
mechanism:	by 32-bit or 64-bit reference (Alpha and I64); by 32-bit reference (VAX)

The 32-bit or 64-bit address (on Alpha and I64 systems) or the 32-bit address (on VAX systems) of a longword into which $ICC_OPEN_ASSOC writes the handle assigned to the opened association.

assoc_name

OpenVMS usage:	char_string
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit descriptor (Alpha and I64); by 32-bit descriptor (VAX)

An ASCII character string of up to 31 characters in length specifying the name of the application opening the association. Null (0 length), and empty or blank association names are not allowed. If this argument is omitted (that is, a zero is passed in by value), it signifies that the user wants to open the default association. This argument is case sensitive.

logical_name

OpenVMS usage:	logical name
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit descriptor (Alpha and I64); by 32-bit descriptor (VAX)

A logical name in a clusterwide logical name table used to maintain the simple association registry. The logical name represents the name of the service provided by the application. Logical names are case sensitive.

logical_table

OpenVMS usage:	logical name table
type:	character-coded text string
access:	read only
mechanism:	by 32-bit or 64-bit descriptor (Alpha and I64); by 32-bit descriptor (VAX)

The table containing the logical name logical_name. Logical name tables are converted to uppercase. Unless your application requires an application-specific logical name table, this argument should be either the default ICC Registry search list (ICC$REGISTRY), or the default registry table (ICC$REGISTRY_TABLE).

conn_event_rtn

OpenVMS usage:	user_routine
type:	procedure_entry_mask
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit linkage reference (Alpha and I64); by 32-bit reference (VAX)

The address of the AST routine to be called for incoming connect events. This routine will be called in the mode of the caller. (No mechanism is provided for the routine to be called at a different mode).

You must have a conn_event_rtn to operate as a server.

disc_event_rtn

OpenVMS usage:	user_routine
type:	procedure_entry_mask
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit linkage reference (Alpha and I64); by 32-bit reference (VAX)

The address of the AST routine to be called for incoming disconnect events. This routine will be called in the mode of the caller. (No mechanism is provided for the routine to be called at a different mode). The arguments, conn_event_rtn, and disc_event_rtn, may reference the same routine.

recv_rtn

OpenVMS usage:	user_routine
type:	procedure_entry_mask
access:	call without stack unwinding
mechanism:	by 32-bit or 64-bit linkage reference (Alpha and I64); by 32-bit reference (VAX)

The address of the AST routine to be called for incoming new data events.

If the user provides this routine, it indicates that the user will supply a buffer of the size required (specified in an argument to the recv_rtn at each call) each time one is requested. If the user supplies this routine, receive calls should only be issued after receive events arrive and sufficient buffer space has been allocated to handle the incoming data.

This routine will be called in the mode of the caller. (No mechanism is provided for the routine to be called at a different mode).

maxflowbufcnt

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by value

The maximum number of pending inbound messages (per connection) that ICC will allow the user before initiating flow control. A message is pending if it is being held within ICC but no receive call(s) are outstanding from the user.

Default = 5 (Pass 0 to get the default)

prot

OpenVMS usage:	longword_unsigned
type:	longword (unsigned)
access:	read only
mechanism:	by value

This argument is ignored for non-server applications.

The default protection scheme for this association is as follows:

0 - access for everyone (default)
1 - stops WORLD access
2 - stops both WORLD and GROUP access

Advanced access control is provided by ICC Security objects. Refer to the HP OpenVMS System Manager's Manual for information on ICC system management and security.

Description

This service declares an application association with ICC. Servers must make this call to declare or register their name and to indicate their readiness to receive incoming connections. Although a client is permitted to call this routine, it is unnecessary for simple applications. A client application that wishes to be notified of disconnection events or Receive Data events must call the $ICC_OPEN_ASSOC service.

A client can open a connection without specifying an open association; this automatically creates a default association name of ICC$PID_nnnnnnnn (where nnnnnnnn is a character representation of the Process ID).

NETMBX privilege is required to open any association.

The association name space is a controlled resource. Refer to the HP OpenVMS System Manager's Manual for information on managing this resource.

An attempt to open an association with a name not authorized as described in the HP OpenVMS System Manager's Manual will fail with the error SS$_NOPRIV returned to the caller. In addition to making entries in the system's local association name space, a call to $ICC_OPEN_ASSOC may also make an entry in a simple clusterwide registry of active associations.

An association may only be accessed from the mode in which it was opened. Inner modes are prevented from using the default association.

An application can open any number of associations subject to available process BYTLM quota. Currently, there is a systemwide limit of 512 open associations. There is no limit imposed clusterwide.

Description of User-Supplied Routines (ASTs)

When opening an association, the user may optionally supply a connect/disconnect AST and/or a Data Event AST. These routines will be used for all connections established over the specified association. In addition, for any of the asynchronous services (those provided with both an immediate return and a "W" form), a completion AST may be supplied by the user. This section describes these ASTs.

1. Connect and Disconnect AST

The user chooses the name of this routine and supplies the procedure name as an argument to the Open Association service. Seven arguments will be passed to the user.

The first argument notifies the user whether this is an incoming new connection or a disconnection of an existing connection. The second identifies the connection. The third and fourth provide access to incoming connect or disconnect data (if any) sent by the cooperating application. The fifth argument provides the number of bytes available for any optional Accept or Reject data (in the case of a connect request) or the disconnect reason supplied by the cooperating application (if any).

For connect events, the sixth and seventh arguments are the EPID and user name of the process requesting the connect, respectively.

The user has the choice of using and declaring a common routine or separate routines as specified when calling $OPEN_ASSOCIATION.

Format

ConnDiscRtn event_type ,conn_handle ,data_len ,data_bfr ,P5 ,P6 ,P7

C Prototype

void ConDiscRtn (unsigned int event_type, unsigned int conn_handle, unsigned int data_len, char *data_bfr, unsigned int P5, unsigned int P6, char *P7);

Arguments

event_type Type: longword (unsigned) Access: read only Mechanism: by value

This field will contain a code describing the type of event. The possible event codes are defined in ICCDEF:

ICC$C_EV_CONNECT - Connection event ICC$C_EV_DISCONNECT - Disconnection event

conn_handle Type: longword (unsigned) Access: read only Mechanism: by value

The handle of the connection associated with the event.

data_len Type: longword (unsigned) Access: read only Mechanism: by value

The length (in bytes) of the incoming data. This value specifies the length of the buffer data_bfr, and will be between 0 and 1000, with zero indicating no data.

data_bfr Type: character-coded text string Access: read only Mechanism: by 32-bit or 64-bit value (Alpha and I64); by 32-bit value (VAX)

The 32-bit address of the P1-space buffer containing the data, or zero if no data is available. The length of this buffer is specified by the argument data_len.

Upon return from the AST, the address of the data is no longer valid. An application wishing to reference the Connection or Disconnection data after Return must copy the data from the supplied buffer to storage owned by the application.

P5 Type: longword (unsigned) Access: read only Mechanism: by value

The usage of this argument is dependent on the specified event type code (event_type).

For connect events (event_type=ICC$C_EV_CONNECT), this argument contains the length (in bytes) of the buffer available for a reply.

For disconnect events (event_type=ICC$C_EV_DISCONNECT), this argument contains the user-defined disconnect reason/status from the remote partner.

P6 Type: longword (unsigned) (VAX); quadword (Alpha and I64) Access: read only Mechanism: by value

The usage of this argument is dependent on the specified event type code (event_type).

For connect events (event_type=ICC$C_EV_CONNECT), this argument contains the EPID of the process requesting the connection, passed by value.

For disconnect events (event_type=ICC$C_EV_DISCONNECT), this argument contains the user-defined user_context supplied when the connection was opened. For a client, the user_context is that supplied to the $ICC_CONNECT call. For a server, it is the value supplied to $ICC_ACCEPT.

P7 Type: character-coded text string Access: read only Mechanism: by reference

For connect events: Username, passed by reference (to P1 space buffer) as a 12-character, space-filled string.

The application must copy this information to local storage before exiting from the connect routine.

For disconnect events, this argument is zero (0).

2. Data Event Routine

This routine, if supplied by the user when opening the association, allows the user to be notified of any pending data events over any connections subsequently opened over that association.

---

Previous

Next

Contents

Index