HP OpenVMS System Services Reference Manual


Previous Contents Index


$ICC_CONNECT

Establishes a connection to a remote application over an open association.

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


Format

SYS$ICC_CONNECT 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_connect (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);


Arguments

ios_icc


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

I/O status block:

Completion status values:

SS$_NORMAL, SS$_BUFFEROVF, SS$_EXQUOTA, SS$_INSFMEM, SS$_IVBUFLEN, SS$_LINKABORT, SS$_LINKDISCON, SS$_NOLOGNAM, SS$_NOSUCHOBJ, SS$_NOSUCHNODE, SS$_PATHLOST, SS$_REJECT, SS$_SSFAIL, SS$_UNREACHABLE, SS$_WRONGSTATE

The second longword is undefined unless the completion code is SS$_REJECT. In this case, the application-defined rejection reason code is supplied by the server when $ICC_REJECT is called.

astadr


OpenVMS usage: ast_procedure
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha and Integrity servers)

The AST routine to be executed when the operation completes.

astprm


OpenVMS usage: user_arg
type: quadword (unsigned) (Alpha and Integrity servers)
access: read only
mechanism: by 64-bit value (Alpha and Integrity servers)

The parameter to be passed to the AST routine.

assoc_handle


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

The handle of the association on which the connection is to be opened. The constant ICC$C_DFLT_ASSOC_HANDLE, if used, indicates that the default association is to be used (and opened if necessary).

conn_handle


OpenVMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by 32-bit or 64-bit reference (Alpha and Integrity servers)

The 32-bit or 64-bit address (on Alpha and Integrity server systems) of a longword into which $ICC_CONNECT writes the connection handle of the created connection on a successful call.

remote_assoc


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

An ASCII character string (31 characters maximum) specifying the name of the target application to connect to. Association names are case sensitive.

remote_node


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

The name of the node where the target association resides. A null or blank string can be used to indicate the local node. If omitted (by passing zero by value), the simple clusterwide association registry is to be used. Each node name is a one-to-six character SCS node name. A comma-delimited list of nodes may be specified, indicating that one is to be chosen at random.

user_context


OpenVMS usage: user_arg
type: quadword (Alpha and Integrity servers)
access: read only
mechanism: by value

A user-specified value to be subsequently returned on any disconnect or data events on this connection.

conn_buf


OpenVMS usage: byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha and Integrity servers)

A buffer of up to 1000 bytes of connection data to be sent to the target of the connection during the connection process.

conn_buf_len


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

The number of bytes in conn_buf to be sent.

return_buf


OpenVMS usage: byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha and Integrity servers)

A buffer of up to 1000 bytes in length to receive any incoming connection accept or reject data returned.

return_buf_len


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

The length of the supplied return_buf.

retlen_addr


OpenVMS usage: longword_unsigned
type: longword (unsigned)
access: write only
mechanism: by 32-bit or 64-bit reference (Alpha and Integrity servers)

The 32-bit or 64-bit address (on Alpha and Integrity server systems) of a longword into which $ICC_CONNECT writes the actual length (in bytes) of any user accept or reject data returned in the buffer return_buf.

flags


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

ICC$M_SYNCH_MODE can be specified to indicate that the data transmission and reception routines $ICC_TRANSMIT, $ICC_RECEIVE, and $ICC_REPLY are allowed to return the status SS$_SYNCH in the case of synchronous completion, indicating that the AST will not be called.

Description

This service establishes a connection to a remote application over an open association. Connections must be opened in the same mode as their association. If the user provides the default association constant ICC$C_DFLT_ASSOC_HANDLE as its association handle, the default association will be used; it will be opened if it is not already open. Multiple connections are possible over a single association. When completion is signaled by the AST routine, the application must check the completion status field of the IOS_ICC to determine if the server has accepted or rejected the connection request. The number of connections is subject to process BYTLM quota.

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. For more information, see the HP OpenVMS System Manager's Manual.

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.

$ICC_CONNECTW

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 Integrity server 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);


$ICC_DISCONNECT

Terminates the specified connection.

On Alpha and Integrity server 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 Integrity servers)

I/O status block:

Completion status values:

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

astadr


OpenVMS usage: ast_procedure
type: procedure_entry_mask
access: call without stack unwinding
mechanism: by 32-bit or 64-bit linkage reference (Alpha and Integrity servers)

The AST routine to be executed when the operation completes.

astprm


OpenVMS usage: user_arg
type: quadword (unsigned) (Alpha and Integrity servers)
access: read only
mechanism: by 64-bit value (Alpha and Integrity servers)

The parameter to be passed to the AST routine.

disc_buf


OpenVMS usage: byte_stream
type: character-coded text string
access: read only
mechanism: by 32-bit or 64-bit reference (Alpha and Integrity servers)

A buffer of up to 1000 bytes of disconnect data to be sent to the partner in the connection when notifying it that disconnection is being initiated. Delivery of this data is not guaranteed.

disc_buf_len


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

The number of bytes in disc_buf to be sent.

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.

$ICC_DISCONNECTW

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 Integrity server 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);


$ICC_OPEN_ASSOC

Declares an application association with ICC.

On Alpha and Integrity server 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 Integrity servers)

The 32-bit or 64-bit address (on Alpha and Integrity server systems) 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 Integrity servers)

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 Integrity servers)

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 Integrity servers)

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 Integrity servers)

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 Integrity servers)

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 Integrity servers)

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.


Previous Next Contents Index