Transparent communication provides the basic functions necessary for a task to communicate with another task over the network. These functions include the initiation and completion of a logical link connection, the orderly exchange of messages between both tasks, and the controlled termination of the communication process. To perform these functions, you can write your cooperating tasks in any of the higher-level languages supported over the network, in VAX MACRO (using RMS service calls or system service calls), or by using DCL commands.

One way to view transparent communication is to look at the programming required to develop such an application. Transparent access provides the functions necessary to communicate over the network using standard I/O operations. When accessing the network transparently, you may use standard I/O statements of the higher-level language or straightforward RMS or system service calls to access a sequential record-oriented device. System service calls are described in Section 4.5, “Performing Transparent Task-to-Task Operations”.

Nontransparent communication provides the same functions as transparent communication plus additional system service and I/O features supported by DECnet-Plus for OpenVMS. In particular, a nontransparent task can create and use an OpenVMS mailbox to receive information that is not available to a transparent task with transparent communication. You can make use of network-specific features such as optional user data on connects and disconnects, and interrupt messages. Also, nontransparent tasks can receive and process multiple inbound connection requests. (See the description in Section 4.6.1.5, “Completing the Establishment of a Logical Link”.)

Note that on a OpenVMS Cluster node, nontransparent tasks that can receive multiple inbound connection requests should not use the cluster alias node address for outgoing connections. They should also not be enabled to receive incoming connections directed to the cluster alias node. Incoming links directed to a cluster alias node address can be assigned to any of the nodes in the cluster that accept that alias node address, without knowledge of the nodes on which a declared task may be running.

Nontransparent functions that indirectly cause mailbox messages to be placed in the receiver's mailbox include calls for initiating, completing and terminating logical links. Figure 4.1, “Mailbox Messages”illustrates how nontransparent tasks use mailboxes.

Table 4.3, “System Mailbox Messages” (later in this chapter)provides a list of mailbox messages and their meanings.

Whether you access the network transparently or nontransparently, you must establish a communication link to the remote node on which the target task runs before any message exchange can take place. You establish the link by issuing a source task call that requests a logical link connection. The source task is the task that initiates a logical link connection request; the target task is the task with which you want to communicate.

You should be aware that after you issue a call that uses either a task specification string or an NCB, you access the network and, by definition, the DECnet-Plus for OpenVMS software.

As part of the handshaking sequence, the target task completes the logical link connection in two steps. First, the DECnet software at the remote node processes the inbound logical link connection request. Second, the target task either accepts or rejects the link. These steps are performed differently, depending on whether the target task uses transparent or nontransparent I/O.

When a logical link request is received, a procedure called NET$SERVER.COM is executed, which in turn invokes the image NET$SERVER. This program works in conjunction with the network ACP (NET$ACP) and uses DCL to invoke the image or command procedure defined for the requested object. For example, the specified task is invoked for object 0 and FAL is invoked for object 17.

When the logical link is terminated, the “object” program (for example, FAL) also terminates. However, the process is not deleted. Instead, control is returned to NET$SERVER, which communicates with NET$ACP to inquire for another incoming logical link request. This inquiry process continues until NET$SERVER encounters a timeout condition (the default is 5 minutes).

The system manager can specify the time that NET$SERVER waits for another logical link request. The logical name NETSERVER$TIMEOUT, when defined, determines the amount of time NET$SERVER waits before reaching the timeout condition. Note that the equivalence name must be in the standard OpenVMS delta time format, for example, 0:10:0, representing 10 minutes.

You may define a number of NET$SERVER processes that never time out. This is useful on systems that are the target of significant amounts of network activity, such as mail or public file access. Two benefits may be gained: improved response time for the user initiating the network access, because there is no waiting for a new process to be created, and reduced overhead on the target system by virtue of fewer process creations.

$ DEFINE NETSERVER$SERVERS_CML$SERVER 2

You should put this command in the login command procedure of the default account; in this case, the SYS$LOGIN directory for CML$SERVER. You could also define it as a system logical name in the site-dependent system startup command procedure. The account must have WRITE access to its SYS$LOGIN directory. Note that you gain very little by defining only one permanent server, because a number of functions such as wildcard file copy require multiple logical links, each of which requires its own server.

If you use this mechanism, you should understand the interaction between proxy access and NET$SERVER processes. The proxy database is read by NET$ACP before a process has been created. For this reason, any incoming connection that may have a proxy account on the local system will not be given to an existing NET$SERVER process that was created for a different user.

In the following discussion, the remote node is assumed to be an OpenVMS operating system. If the remote node on which your target task runs is not an OpenVMS operating system, you should refer to the DECnet documentation for that system.

Completing the Connection Transparently

If the target task is transparent, the DECnet software at the remote node checks the access control information supplied in the connection request call.

Before you access the remote node, the system manager must have created the appropriate account in the user authorization file (UAF) (refer to the information on access control). In addition, the command procedure file ( taskname.COM ) starting the remote task must exist in the default directory associated with the account identified by the access control information. For a description of the command procedure taskname.COM, see Section 4.7.1, “DCL Command Procedure for Task-to-Task Communication”, which contains examples of command procedures designed for task-to-task communication.

Command procedures for objects existing in the Session Application database (which is created using NCL commands) are located in the SYS$SYSTEM directory. The VSI-supplied FAL.COM procedure is an example of such a command procedure. (Note that the command procedure is bypassed if the application definition specifies an EXE file.)

Completing the Connection Nontransparently

If the target task is nontransparent, then one of several things may occur. If the task has not declared itself a network task (and is therefore eligible to accept only one connection request at a time), then the DECnet software at the remote node performs the access checking procedure. After it starts, the target task retrieves the connection information by translating the logical name SYS$NET using the $TRNLNM system service call (see Section 4.6, “Performing Nontransparent Task-to-Task Operations”).

If the target task declares itself as an active network task, then DECnet-Plus for OpenVMS software places all connection requests addressed to the task in the mailbox associated with the channel being used. The first message in the mailbox is the NCB from the original connection request that started the task. This message appears in the mailbox after channel assignment and name declaration occur. After the task declares a network name or number, subsequent inbound connection requests are not checked by the remote node to verify access control. (Note that if the task is started without being part of a DECnet operation, access control is never checked.) Section 4.6, “Performing Nontransparent Task-to-Task Operations” describes in more detail the nontransparent process of completing the logical link connection.

After examining the incoming connection request, the target task either accepts or rejects the request, and optionally can send 1 to 16 bytes of data back to the source task at the same time that it responds to the logical link connection request. Furthermore, a library routine, LIB$ASN_WTH_MBX, which assigns a channel and associates a unique mailbox, can be used when accepting the connection.

When you access the network transparently or nontransparently, DECnet-Plus for OpenVMS sends data messages over a logical link in response to a set of send and receive calls issued by the source and target tasks. For higher-level language tasks, use standard read and write statements to send and receive data messages. (In Example 4.2, “FORTRAN Task-to-Task Communication”, the two FORTRAN tasks use read and write statements to exchange information. The equivalent RMS service calls are $GET and $PUT.)

After DECnet-Plus for OpenVMS creates a logical link, the two tasks are ready to exchange messages. This exchange can take place only if the two tasks cooperate in the transmission process. In other words, for each message sent by a task, the receiving task must issue a corresponding call to receive the message. Also, you must decide which task will disconnect the link. In addition, if the tasks are nontransparent, they must agree on whether or not the optional data will be passed. In the context of an established logical link, the task sending a message is the transmitter and the task receiving it is the receiver. Because logical links are inherently full duplex, each task may be a transmitter and a receiver simultaneously.

DECnet-Plus for OpenVMS distinguishes between two types of message: data messages and mailbox messages. Data messages are the normal mode of information exchange for both transparent and nontransparent communication. Mailbox messages such as interrupt messages, messages resulting from some DECnet operation (including optional user data), and network status notifications can be used only in nontransparent communication.

The termination of a logical link signals the end of the communication between tasks.

In transparent communication using higher-level language statements, RMS service calls, or system service calls, either task can break the link. To terminate the link properly, the receiver, and not the transmitter, of the final message should issue the $CLOSE service to break the link. The link termination process is complete when the other task issues a link termination request. In transparent communication using system service calls, the $DASSGN system service call causes the link to be terminated.

Issuing the $CANCEL service call followed by the $DASSGN service call causes all pending operations to abort, then closes the link and deassigns the channel.

Note that after either a synchronous disconnect or a disconnect abort of a nontransparent link, you can issue a new connection request because you did not deassign the I/O channel but merely deaccessed the link. For further information about these system service calls, see Section 4.6, “Performing Nontransparent Task-to-Task Operations”.

When a connection to a nontransparent task terminates the connection, a notification message indicating that the link is disconnected is placed in the mailbox of the affected task. A nontransparent task can send up to 16 bytes of optional user data, with the disconnect request. This optional user data is placed in the mailbox of the nontransparent task on the receiving end of the disconnect message.

Disconnect operations cannot guarantee to both partners that communication is complete. Therefore, VSI recommends that the communicating tasks agree on a protocol for terminating communication. In general, the receiver, not the transmitter, of the final message should disconnect the logical link.

Transparent communication allows you to create a logical link between tasks, send and receive data messages, and terminate the logical link at the end of the message dialog. The discussion covers general concepts implicit in DECnet-Plus for OpenVMS task-to-task communication and assumes familiarity with the QIO-related material in the VSI OpenVMS System Services Reference Manual. The use of higher-level language statements and RMS service calls in transparent task-to-task communication is described in Section 4.5, “Performing Transparent Task-to-Task Operations”.

To request a logical link and assign an I/O channel, use the $ASSIGN system service. When you issue this call, you must include a task specifier for the remote node on which the cooperating task runs. The task specifier identifies the remote node and the target task to which you want to establish a logical link.

TARGET:     .ASCID  /TRNTO::"TASK=TEST2"/
NETCHAN:    .BLKW   1       ; Channel number returned here
                  .
                  .
                  .
            $ASSIGN_S      DEVNAM=TARGET,CHAN=NETCHAN

For debugging or for symmetry, you can develop and run the target task on the local node. Use the local node name (or node number 0) plus two colons to connect to the local node. This practice applies to DCL, higher-level languages and RMS, as well as system services.

After you establish a logical link, you refer to the assigned channel in any succeeding call in the MACRO program, either to send or receive messages, or to deassign the channel and terminate the logical link.

Until the connection operation completes, the process is in local event flag (LEF) wait state in kernel mode. Therefore, pressing Ctrl/Y does not return the process to DCL status. The maximum amount of time that the process will wait in this state is specified by the OUTGOING TIMER parameter of the NCL command SET SESSION CONTROL. If this timer cannot be set to an acceptable value, tasks that accept commands from the terminal should use $QIO (IO$_ACCESS) instead of the transparent $ASSIGN call to initiate logical links.

LOGNAM:     .ASCID  /SYS$NET/
NETCHAN:    .BLKW   1       ; Channel number returned here
               .
               .
               .
            $ASSIGN_S      DEVNAM=LOGNAM,CHAN=NETCHAN

Issue this call in the target task to complete the logical link connection. The target task also specifies a channel to be used in subsequent system service calls.

The remote node is assumed to be an OpenVMS operating system. If the remote node on which the target task runs is other than OpenVMS, you should refer to the related DECnet documentation.

After DECnet-Plus for OpenVMS software establishes a logical link with the target task, either task can then send or receive messages. However, they must cooperate with each other: For each message sent with the $QIO (IO$_WRITEVBLK), the other task must issue a corresponding $QIO (IO$_READVBLK) to receive the message.

On logical links, DECnet-Plus for OpenVMS supports sending and receiving data messages that are larger than the maximum size allowed by the $QIO system service. You do this by allowing write and read requests to be fragmented across multiple $QIO requests. To fragment writes and reads, you must include the modifier IO$M_MULTIPLE on the write or read $QIO call.

When you supply the modifier on a write message request $QIO (IO$_WRITEVBLK!IO$M_MULTIPLE), it indicates that more data will be supplied for this message. To indicate the last fragment of the message being sent, you should issue the write request without a modifier$QIO (use the QIO called IO$_WRITEVBLK).

When you supply the modifier on a read message $QIO (IO$_READVBLK!IO$M_MULTIPLE), if the received data message contains more than enough data to fill the buffer supplied with the read request, then SS$_BUFFEROVF is returned. This is not an error status. The next read posted receives the next fragment of the data message. If the received message fits into the buffer posted, then SS$_NORMAL is returned. Tasks that require fragmentation should always supply the IO$M_MULTIPLE on read requests.

If you do not use the read multiple request to receive a data message, then you must ensure that the tasks allocate enough buffer space for receiving the messages. If the tasks do not, SS$_DATAOVERUN error occurs. You must also ensure that the end of the dialog can be determined.

One of the two tasks must disconnect the logical link. To terminate a logical link properly, the receiver, and not the transmitter, of the final message should break the link.

DECnet-Plus for OpenVMS does not provide an automatic timeout of read or write requests. If the task needs to stop a read or write request on a logical link, it must do so by disconnecting or aborting the logical link.

Use the $DASSGN system service call to deassign the channel and break off the logical link with the cooperating task. This call terminates all pending calls for sending and receiving messages, aborts the link immediately, and frees the channel associated with that logical link.

When a system service completes execution, a status value is returned (does not apply to the $EXIT service). The $ASSIGN, $DASSGN, and $QIO system services place the return status information in register 0 (R0). For the$QIO system service, a successful return status indicates only that the request was queued successfully. All I/O completion status information is placed in the I/O status block (IOSB). For example, a $QIO system service read request to a task might be successful (status return is SS$_NORMAL) yet fail because the link was disconnected. (I/O status return is SS$_LINKABORT.) The return status codes shown in the following sections may be returned both in R0 and in the IOSB.

When DECnet-Plus for OpenVMS returns the status SS$_NORMAL in the I/O status block on a write request, it means that the write was queued for transmission on the logical link. It does not mean that the write request has been received or acknowledged by the remote task. The logical link services of DECnet-Plus for OpenVMS provide the guaranteed delivery of transmitted messages to the remote node. If a message cannot be delivered, the user is notified by the disconnection of the logical link. The DECnet-Plus for OpenVMS services cannot guarantee the delivery of data received on the remote node to the remote task. It is the responsibility of cooperating tasks to agree on a protocol to ensure that data transmitted by the local task is received by the remote task.

The VSI OpenVMS System Services Reference Manual and the Guide to OpenVMS Programming Resources both provide more information about $QIO system services.

The $ASSIGN system service assigns a channel to refer to the logical link. You can then use the channel returned in the chan argument in any succeeding call to send or receive a message, or to deassign the channel and thereby terminate the logical link.

Format

$ASSIGN devnam, chan, [acmode]

Arguments

Return Status

The $QIO system service with a function code of IO$_WRITEVBLK or IO$_WRITEVBLK!IO$M_MULTIPLE sends a message to a target task. The $QIO call initiates an output operation by queuing a request to the channel associated with the logical link. Alternatively, you could use the $QIOW system service to perform the same operation but also wait for I/O completion.

Format

$QIO [efn], chan, func, [iosb], [astadr], [astprm], p1, p2$QIOW

Arguments

Return Status

The $QIO system service with a function code of IO$_READVBLK receives a message from a target task. The $QIO call initiates an input operation by queuing a request to the channel associated with the logical link. Alternatively, you could use the $QIOW system service to perform the same operation but also wait for I/O completion.

Format

$QIO [efn], chan, func, [iosb], [astadr], [astprm], p1, p2$QIOW

Arguments

Return Status

The $DASSGN system service terminates all pending operations to send and receive data, disconnects the logical link immediately, and frees the channel associated with that link. Either task can terminate the logical link by calling $DASSGN.

Format

$DASSGN chan

Argument

Return Status

To prepare for nontransparent task-to-task communication, you need to assign a channel just as you would for transparent communication. In addition, you can create a mailbox to take advantage of optional network protocol features.

You must assign a channel to the pseudodevice _NET:; use the $ASSIGN system service call for this purpose. This call normally contains a reference to a mailbox, thereby associating it with the channel assigned to _NET:. If you use a mailbox, you must create the mailbox before assigning a channel to _NET:. It is important to note that this use of the $ASSIGN system service differs from its use for transparent communication. Assigning a channel to _NET: does not transmit a logical link connection request to the remote node. Instead, the channel to _NET: provides a communication path to DECnet software. You must use a separate $QIO call (IO$_ACCESS function using the same channel) to request a logical link to the remote task. Refer to Section 4.6.2.1, “$ASSIGN (I/O Channel Assignment)” for details about the$ASSIGN system service.

To take advantage of optional network protocol features, you can create a mailbox to receive messages on behalf of logical link operations. For example, the mailbox receives a message indicating whether the cooperating task accepted or rejected a connection request issued by the source task. Use the $CREMBX system service to create a mailbox for these purposes. In the event that your application does not need the information supplied in the mailbox, you need not create a mailbox.

For convenience, you can use the Run-Time Library routine LIB$ASN_WTH_MBX to create a temporary mailbox, assign a channel to it, and assign a channel to _NET:. This routine creates a unique mailbox on each call to the routine. Multiple copies of a task using this routine, in effect, use different mailboxes. If you were to create a mailbox with a logical name within the task, then all copies of that task would use the same mailbox and thereby interfere with each other's mailbox messages.

The mailbox receives information specific to nontransparent communication with a remote task. Figure 4.2, “Mailbox Message Format” illustrates the general format of the mailbox message.

Notes on Figure 4.2, “Mailbox Message Format”

All system mailbox messages contain, in the first word of the message, a constant that identifies the sender of the message. These constants have symbolic names (defined in the $MSGDEF macro) in the following format:MSG$_sender

After you assign the I/O channel, you can request a logical link connection to the target task. Use the $QIO system service with a function code of IO$_ACCESS. You must identify the target task in the $QIO call. Use a network connect block (NCB) to specify the target task identification string. In addition, you can optionally send one to 16 bytes of data in the NCB. The format of the NCB is discussed in Section 4.6.1.4, “Using the Network Connect Block”.

After the source task issues the connection request, it can issue a $QIO call with a function code of IO$_READVBLK to read its mailbox. Checking the contents of the mailbox is one way to determine whether the target task accepted or rejected the connection request. The mailbox can contain a variety of information, including either the MSG$_CONFIRM or MSG$_REJECT messages, and possibly optional data in the mailbox buffer.

If specified, the IOSB argument of the $QIO (IO$_ACCESS) call will also contain the result of the connection request operation. Section 4.6.2.2, “$QIO (Requesting a Logical Link Connection)” provides a complete list of I/O status messages for this call.

Note that you must read the mailbox to inspect any optional data sent from the target task upon accepting or rejecting the connection request.

The network connect block (NCB) is a user-generated data structure that contains the information necessary to request a logical link connection or to accept or reject a logical link connection request. The NCB must be in read/write storage.

"TASK=TEST2"TASK=157"0=TEST2"

For an inbound call with an NCB, the task name portion of the task specification string is a process ID if the remote node is an OpenVMS operating system; if not, then the task name portion is a system-specific string that identifies an executable unit (for example, job or task). The task specification string must be enclosed in quotation marks. Note that the final quotation mark of the task specification string follows the last item within the NCB. Section 4.4.2, “Task Specification Strings in Task-to-Task Applications” provides additional information about task specification strings.

1.  With optional data (outbound connect):
                                       
NCB:    .ASCII  ?TRNTO::"TASK=TEST2/?
             .WORD   0
OPTDATA:
             .ASCIC /USERINFO/
             .BLKB 17-<.-OPTDATA>
             .ASCII /"/
                 
2.  Without optional data (outbound connect):
                                   
NCB:     .ASCII   ?TRNTO::"TASK=TEST2"?

A nontransparent target task completes the logical link connection in one of several ways, depending upon whether the task can process multiple inbound connection requests or just a single request. Furthermore, a nontransparent target task has the option of accepting or explicitly rejecting a logical link request.

Receiving Connection Requests

This section describes what happens when you receive single and multiple connection requests. The remote node is assumed to be OpenVMS. If the remote node on which your target task runs is other than OpenVMS, you should refer to the related DECnet documentation.

When a remote node receives a call requesting a logical link, the DECnet-Plus for OpenVMS software constructs an NCB from the information contained in the call. At this point, one of two things occurs. If a task already running on the remote node has declared a network name or object number which is the same as the one identified in the constructed NCB, the software puts the NCB into that task's mailbox. If not, DECnet-Plus for OpenVMS must create a process to execute the task. The DECnet-Plus for OpenVMS software either uses a compatible netserver process (if one exists) or creates a netserver process (if one does not already exist) to execute NET$SERVER.COM, which in turn runs NET$SERVER.EXE.

When executing, the target task can determine whether to accept or explicitly reject the connection request. You can program the target task to base this assessment on the information contained in the NCB.

A nontransparent target task can accept only one connection request at a time, unless it declares itself as a network task. The target task may retrieve the connection information by translating the logical name SYS$NET using the$TRNLNM system service. After the task retrieves the logical name, it may decide whether to accept or explicitly reject the connection request.

A target task can accept multiple inbound connection requests only if it declares itself a known network task. To make this declaration, you must first use the $ASSIGN call to assign an I/O channel to _NET:. Then, use the $QIO system service with the function code IO$_ACPCONTROL to assign a network name or object number to the task, making it eligible to process multiple inbound connection requests. This system service requires SYSNAM privilege. You must associate a mailbox with the channel if a name or number is to be declared.

You should program tasks that have declared names or object numbers to terminate when their mailboxes receive a MSG$_NETSHUT message. You must restart such tasks when the network comes back up.

After you declare the target task as an active network task, DECnet places all connection requests addressed to the task in the mailbox associated with the channel over which the ACP control function was issued. The target task retrieves connection requests from the mailbox by issuing the $QIO system service call with the function code IO$_READVBLK. Note that the first message in the mailbox is the NCB from the original connection request that put the task into a state of execution. After the task declares a network name or object number, subsequent inbound connection requests are not checked for their access control information.

Note that you can start tasks that declare names or object numbers apart from the first inbound connection (that is, by a RUN command). However, if the network task is started separately from a DECnet operation, access control is never checked.

Accepting or Rejecting a Connection Request

The target task can either accept or reject a connection request. To accept a connection request, thus completing the logical link connection, use the $QIO system service with the function code IO$_ACCESS. To reject the connection request, use the $QIO system service with the function code IO$_ACCESS!IO$M_ABORT. When it either accepts or rejects the connection request, the target task can also send 1 to 16 bytes of optional data within a modified NCB back to the source task.

Exchanging Data Messages and Interrupt Messages

The exchange of data messages between the two cooperating tasks is performed in the same way for both nontransparent and transparent communication. (Refer to Section 4.5.4.3, “Exchanging Messages” for information about exchanging messages on DECnet-Plus for OpenVMS logical links.)

The exchange of interrupt messages applies only to nontransparent communication. Either task can send a 1- to 16-byte interrupt message. You can use this method to send a message to a target task outside the normal flow of data messages. DECnet-Plus for OpenVMS places the received interrupt message in the target task's mailbox. Use the $QIO system service with the function code IO$_WRITEVBLK!IO$M_INTERRUPT to send the interrupt message. If the target task needs to be notified that an interrupt message has been placed in its mailbox, then it should issue a $QIO system service read request to the mailbox. The task may also specify an AST on the $QIO request to cause the execution of a special routine to handle the received interrupt message. (AST routines are described in the VSI OpenVMS System Services Reference Manual.)

A nontransparent task can terminate communication with a remote task either by disconnecting the link (synchronous disconnect or disconnect abort) or by deassigning the channel. In the first instance, you can issue a new connection request on the same channel because you do not deassign it. If you specifically use the IO$_DEACCESS, as opposed to the $DASSGN method of terminating a link, you can send an optional message of 1 to 16 bytes of data with the $QIO call.

To disconnect a logical link synchronously, issue the $QIO system service with the function code IO$_DEACCESS!IO$M_SYNCH. The channel is then free for subsequent communication with either the same or a different remote task.

A synchronous disconnect may be useful for master/slave communication, in which one task always sends data and its partner task always receives data. If the receiving task is notified of a synchronous disconnection, then all the data that was sent has been received. (The sending task, on the other hand, is not guaranteed that its partner received the data.) Because this notification is the only guarantee provided by this operation, VSI discourages using this operation in favor of a user-defined protocol to ensure completion of communication. In general, the receiver of the final message should break the logical link.

To abort the logical link, issue the $QIO system service with the function code IO$_DEACCESS!IO$M_ABORT. This type of disconnect indicates that all messages transmitted by the local transmitter may not have been received or acknowledged by the remote ECL before the logical link was disconnected. You should use this type of disconnect when the local task needs to reset the logical link to a known state. If the local task needs to ensure that the transmitted messages have been received and acknowledged by the remote ECL, the task can issue the system service $CANCEL on the channel before issuing the disconnect abort. Note that this does not guarantee the delivery of the received data to the remote task. It is the responsibility of cooperating tasks to agree on a protocol to ensure that the received data is delivered to the remote task.

Note that after either a synchronous disconnect or a disconnect abort, you can issue a new connection request if you did not deassign the I/O channel.

If you issue the $CANCEL system service to a channel over which a network name or object has been declared, the declaration is removed from the network database.

You can issue the $DASSGN system service call to deassign the channel and terminate the logical link immediately. You issue the call only after all communication between the tasks is complete. The call releases the I/O channel, disassociates the mailbox from the channel, and terminates the logical link immediately. This operation is equivalent to using $CANCEL followed by $QIO IO$_DEACCESS!IO$M_ABORT.

The same status and error-reporting considerations apply to both nontransparent and transparent task-to-task communication. Refer to Section 4.5.4.5, “Status and Error Reporting” for information about status and error reporting.

The $ASSIGN system service assigns a channel to refer to a logical link. You use this channel in all $QIO calls that communicate with a remote task. In addition, you can use the $ASSIGN system service call to associate a mailbox with the channel.

Format

$ASSIGN devnam, chan, [acmode], [mbxnam]

Arguments

Return Status

The $QIO system service with the function code IO$_ACCESS requests a logical link connection to a target task. You can send 1 to 16 bytes of optional data to the target task at the same time that you issue the $QIO system service.

Format

$QIO [efn], chan, func, [iosb], [astadr], [astprm], [p1], p2

Arguments

Return Status

The $QIO system service with the function code IO$_ACCESS accepts a logical link connection request from a source task. You can send 1 to 16 bytes of optional data to the source task at the same time that you issue the $QIO system service.

Format

$QIO [efn], chan, func, [iosb], [astadr], [astprm], [p1], p2

Arguments

Return Status

The $QIO system service with the function code IO$_ACCESS!IO$M_ABORT rejects a logical link connection request. You can send 1 to 16 bytes of optional data to the target task at the same time that you issue the $QIO system service.

Format

$QIO [efn], chan, func, [iosb], [astadr], [astprm], [p1], p2

Arguments

Return Status

The $QIO system service with the function code IO$_WRITEVBLK or IO$_WRITEVBLK!IO$M_INTERRUPT or IO$_WRITEVBLK!IO$M_MULTIPLE sends a message to a target task. Refer to Section 4.5.5.2, “$QIO (Sending a Message to a Target Task)” for the format of this call, its arguments, and possible return status codes.

The $QIO system service with the function code IO$_READVBLK or IO$_READVBLK!IO$M_MULTIPLE receives a message from a target task. Refer to Section 4.5.5.3, “$QIO (Receiving a Message from a Target Task)” for the format of this call, its arguments, and possible return status codes.

The $QIO system service with the IO$_WRITEVBLK!IO$M_INTERRUPT function code sends a 1- to 16-byte interrupt message to a target task. If the remote node is an OpenVMS operating system, the message is placed in the mailbox associated with the target task.

Format

$QIO [efn], chan, func, [iosb], [astadr], [astprm], p1, p2

Arguments

Return Status

The $QIO system service with the function code IO$_DEACCESS!IO$M_SYNCH synchronously disconnects the logical link. All pending messages are transmitted to the remote node before the link is disconnected.

You can send 1 to 16 bytes of optional data to the task from which you are disconnecting at the same time you issue this $QIO system service.

Format

$QIO [efn], chan, func, [iosb], [astadr], [astprm], [p1], [p2]

Arguments

Return Status

The $QIO system service with the function code IO$_DEACCESS!IO$_ABORT terminates the logical link. Note, however, that the DEACCESS function completes only after all pending I/O operations complete, even if you specify IO$_ABORT. First, issue the $CANCEL system service call to cancel I/O operations on the logical link and then issue this call to terminate the logical link.

You can send 1 to 16 bytes of optional data to the task from which you are disconnecting at the same time that you issue this $QIO system service call.

Format

$QIO [efn], chan, func, [iosb], [astadr], [astprm], [p1], [p2]

Arguments

Return Status

The $QIO system service with the function code IO$_ACPCONTROL assigns a network name or object number to the task, thereby making it eligible to process multiple inbound connection requests. You must associate a mailbox with the I/O channel. All inbound connection requests are placed in the mailbox associated with the channel over which this I/O function is issued. You need the SYSNAM privilege to declare a name or object number.

MACRO programmers should be aware that, whenever a logical link is established, you should obtain its device unit number (for example, 18 from _NET18:) by using the $GETDVI system service, because unit numbers and not channel numbers appear in mailbox messages. Use this system service call where a single mailbox is being used for many logical links. The unit number could be used as a key into a database that keeps track of multiple links.

Format

$QIO [efn] ,chan ,func ,[iosb] ,[astadr] ,[astprm] ,p1 ,p2

Arguments

Return Status

The $DASSGN system service terminates all pending operations to send and receive data, aborts the logical link immediately, and frees the channel associated with that link. Refer to Section 4.5.5.4, “$DASSGN (Disconnecting a Logical Link)” for the format of this call, its arguments, and possible return status codes.