TOPS-20 Monitor Calls User's Guide
Chapter 7 Inter-process communication facility
7.1 Overview
The Inter-Process Communication Facility (IPCF) allows communication among jobs and system processes. This communication occurs when processes send and receive information in the form of packets. Each sender and receiver has a Process ID (PID) assigned to it for identification purposes.
When the sender sends a packet of information to another process, the packet is placed into the receiver's input queue. The packet remains in the queue until the receiver checks the queue and retrieves the packet. Instead of periodically checking its input queue, the receiver can enable the software interrupt system (refer to Chapter 4) to generate an interrupt when a packet is placed in its input queue.
The <SYSTEM>INFO process is the information center for the Inter-Process Communication Facility. This process performs system functions related to PIDs and names, and any process can request these functions by sending <SYSTEM>INFO a packet.
7.2 Quotas
Before using IPCF, the user must acquire the ability to use IPCF privileges from the system administrator: a send packet quota and a receive packet quota. These quotas designate, on a per process basis, the number of sends and receives that can be outstanding at any one time. For example, if the process has a send quota of two and it has sent two packets, it cannot send any more until at least one packet has been retrieved by its receiver. A send packet quota of two and a receive packet quota of five are assumed as the standard quotas. If these quotas are zero, the process cannot use IPCF.
7.3 Packets
Information is transferred in the form of packets. Each packet is divided into two portions: a packet descriptor block of four to six words and a packet data block the length of the message. The format of the packet is shown in Figure 7-1.
Packet Descriptor Block
!=======================================================!
.IPCFL ! flags !
!-------------------------------------------------------!
.IPCFS ! PID of sender !
!-------------------------------------------------------!
.IPCFR ! PID of receiver !
!-------------------------------------------------------!
.IPCFP ! length of message ! address of message !
! n ! ADR !
!-------------------------------------------------------!
.IPCFD ! sender's connected ! sender's logged in !
! directory ! directory !
!-------------------------------------------------------!
.IPCFC ! enabled capabilities of sender !
!-------------------------------------------------------!
.IPCSD ! connected directory of sender !
!-------------------------------------------------------!
.IPCAS ! account string of sender !
!-------------------------------------------------------!
.IPCLL ! logical location of sender !
!=======================================================!
Packet Data Block
!=======================================================!
ADR ! message word 1 !
!=======================================================!
.
.
.
!=======================================================!
! message word n !
!=======================================================!
7.3.1 Flags
There are two types of flags that can be set in word .IPCFL of the packet descriptor block. The flags in the left half of the word are instructions to IPCF for packet communication, and the flags in the right half are descriptions of the data message. The flags in the right half are returned as part of the associated variable (refer to Section 7.4.2). The packet descriptor block flags are described in Table 7-1.
| Bit | Symbol | Meaning | ||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | IP%CFB | Do not block the process if there are no messages in the queue. If this bit is on, the process receives an error if there are no messages. | ||||||||||||||||||||||||||||||
| 1 | IP%CFS | Use the PID obtained from the address in word .IPCFS of the packet descriptor block as the sender's PID. | ||||||||||||||||||||||||||||||
| 2 | IP%CFR | Use the PID obtained from the address in word .IPCFR of the packet descriptor block as the receiver's PID. | ||||||||||||||||||||||||||||||
| 3 | IP%CFO | Allow the process one send above the send quota. (The standard send quota is two.) | ||||||||||||||||||||||||||||||
| 4 | IP%TTL | Truncate the message if it is longer than the area reserved for it in the packet data block. If this bit is not on, the process receives an error if the message is too long. | ||||||||||||||||||||||||||||||
| 5 | IP%CPD | Create a PID to use as the sender's PID. The PID created is returned in word .IPCFS of the packet descriptor block. | ||||||||||||||||||||||||||||||
| 6 | IP%JWP | Make the PID created be permanent until the job logs out (if both bits IP%CPD and IP%JWP are on). Make the PID created be temporary until the process executes a RESET% monitor call (if bit IP%CPD is on and bit IP%JWP is not on). If bit IP%CPD is not on, bit IP%JWP is ignored. | ||||||||||||||||||||||||||||||
| 7 | IP%NOA | Do not allow other processes to use the PID created when bit IP%CPD is on. If bit IP%CPD is not on, bit IP%NOA is ignored. | ||||||||||||||||||||||||||||||
| 8-17 | Reserved for Digital. | |||||||||||||||||||||||||||||||
| 18 | IP%CFP | The packet is privileged. This bit can be set only by a process with WHEEL capability enabled. Refer to the TOPS-20 Monitor Calls Reference Manual for a description of this bit. | ||||||||||||||||||||||||||||||
| 19 | IP%CFV | The packet is a page of 512 (decimal) words of data. | ||||||||||||||||||||||||||||||
| 20 | IP%CFZ | A zero-length message was sent. | ||||||||||||||||||||||||||||||
| 21 | Reserved for Digital. | |||||||||||||||||||||||||||||||
| 22 | IP%EPN | Page number in word .IPCFP of the packet descriptor block is 18 bits long | ||||||||||||||||||||||||||||||
| 23 | Reserved for Digital. | |||||||||||||||||||||||||||||||
| 24-29 | IP%CFE | Field for error code returned from <SYSTEM> INFO.
| ||||||||||||||||||||||||||||||
| 30-32 | IP%CFC | System and sender code. This code can be set only by a process with
WHEEL capability enabled, but the monitor will return the code so a
nonprivileged process can examine it.
| ||||||||||||||||||||||||||||||
| 33-35 | IP%CFM | Field for special messages. This code can be set only by a process
with WHEEL capability enabled, but the monitor will return the code so that
a nonprivileged process can examine it.
|
7.3.2 PIDs
Any process that wants to send or receive a packet must obtain a PID. The process can obtain a PID by sending a packet to <SYSTEM>INFO requesting that a PID be assigned. The process must also include a symbolic name that is to be associated with the assigned PID.
The symbolic name can be a maximum of 29 characters and can contain any characters as long as it is terminated by a zero word. There should be mutual understanding among processes as to the symbolic names used in order to initiate communication. Once the name is defined, any process referring to that name must specify it exactly character for character.
Before a process can send a packet, it must know the receiver's symbolic name or PID. If only the receiver's name is known, the sender must ask <SYSTEM>INFO for the PID associated with the name, since all communication is via PIDs.
The association between a PID and a name is broken:
- On a RESET% monitor call.
- When the process is killed or the job logs off the system.
- When a request to disassociate the PID from the name is made to <SYSTEM>INFO.
<SYSTEM>INFO will not allow a name already associated with a PID to be assigned again unless the owner of the name makes the request. Nor will <SYSTEM>INFO assign a PID once it has been used. This action protects against messages being sent to the wrong receiver by accident.
The PIDs of the sender and the receiver are indicated by words .IPCFS and .IPCFR, respectively, of the packet descriptor block.
7.3.3 Length and Address of Packet Data Block
Word .IPCFP of the packet descriptor block contains the length and the beginning address of the message. The length specified is one of two types, depending on the type of message (refer to Section 7.3.5). If the message is a short-form message, the length is the actual word length of the message. If the message is a long-form message, the length is 1000 (octal) words, that is, one page.
The address specified is either an address or a page number, depending on the type of message (refer to Section 7.3.5). When a message is sent, it is taken from this address. When a message is received, it is placed in this address.
7.3.4 Directories and Capabilities
Words .IPCFD and .IPCFC describe the sender at the time the message was sent and are used by the receiver to validate messages sent to it. These two words are not used when a message is sent, and if the sender of the packet supplies them, they are ignored. However, when a message is received, if the receiver of the packet has reserved space for these words in the packet descriptor block, the system supplies the appropriate values of the sender of the packet. The receiver of the packet does not have to reserve these words if it is not interested in knowing the sender's directories and capabilities.
7.3.5 Packet Data Block
The packet data block contains the message being sent or received. The message can be either a short-form message or a long-form message.
A short-form message is one to n words long, where n is defined by the installation. (Usually, n is assumed to be 10 words.) When a short-form message is sent or received, word .IPCFP of the packet descriptor block contains the actual word length of the message in the left half and the address of the first word of the message in the right half. A process always uses the short form when sending messages to <SYSTEM>INFO.
A long-form message is one page in length (1000 octal words). When a long-form message is sent or received, word .IPCFP of the packet descriptor block contains 1000 (octal) in the left half and the page number of the message in the right half. To send and receive a long-form message, both the sender and receiver must have bit IP%CFV (bit 19) set in the first word of the packet descriptor block, or else an error code is returned.
7.4 Sending and receiving messages
To send a message, the sending process must set up the first four words of the packet descriptor block. The process then executes the MSEND% monitor call. After execution of this call, the packet is sent to the intended receiver's input queue.
To receive a message, the receiving process must also set up the first four words of the packet descriptor block. The last two words for the directories and capabilities of the sender can be supplied, and the system will fill in the appropriate values. The process then executes the MRECV% monitor call. After execution of this call, a packet is retrieved from the receiver's input queue. The input queue is emptied on a first-message-in, first-message-out basis.
7.4.1 Sending a Packet
The MSEND% monitor call is used to send a message via IPCF. Messages are in the form of packets of information and can be sent to a specified PID or to the system process <SYSTEM>INFO. Refer to Section 7.5 for information on sending messages to <SYSTEM>INFO.
The MSEND% call accepts two words of arguments. The length of the packet descriptor block is given in AC1, and the beginning address of the packet descriptor block is given in AC2. Thus,
| AC1: | length of packet descriptor block. The length cannot be less than 4. |
| AC2: | address of packet descriptor block |
The packet descriptor block consists of the following four words:
| .IPCFL | Flags |
| .IPCFS | Sender's PID |
| .IPCFR | Receiver's PID |
| .IPCFP | Pointer to packet data block containing the message being sent. |
Refer to Section 7.3 for the details on the packet descriptor and packet data blocks.
The flags that are meaningful when sending a packet are described in Table 7-2. Refer to Table 7-1 for the complete list of flag bits.
| Bit | Symbol | Meaning |
|---|---|---|
| 0 | IP%CFB | Do not block process if no messages in queue; if set, error return if no messages. |
| 1 | IP%CFS | The sender's PID is given in word .IPCFS of the packet descriptor block. |
| 2 | IP%CFR | The receiver's PID is given in word .IPCFR of the packet descriptor block. |
| 3 | IP%CFO | Allow the sender to send one message above its send quota. |
| 4 | IP%TTL | Truncate message if larger than space reserved. |
| 5 | IP%CPD | Create a PID for the sender and return it in word .IPCFS of the packet descriptor block. The PID created is to be permanent and useable by other processes according to the setting of bits IP%JWP and IP%NOA. |
| 6 | IP%JWP | The PID created is to be job wide and permanent until the job logs out. If this bit is not on, the PID created is to be temporary until the process executes the RESET monitor call. |
| 7 | IP%NOA | The PID created is not to be used by other processes. |
| 18 | IP%CFP | The message being sent is privileged (refer to the TOPS-20 Monitor Calls Reference Manual). |
| 19 | IP%CFV | The message being sent is a long-form message (that is, a page). The page the message is being sent to cannot be a shared page; it must be a private page. |
| 22 | IP%EPN | Page number in word .IPCFP of the packet descriptor block is 18 bits long. |
When bit IP%CFS is on in the flag word, the sender's PID is taken from word .IPCFS of the packet descriptor block. This word is zero if bit IP%CPD is on in the flag word, indicating that a PID is to be created for the sender. In this case, the PID created is returned in word .IPCFS.
When bit IP%CFR is on in the flag word, the receiver's PID is taken from word .IPCFR of the packet descriptor block. If this word is 0, then the receiver of the message is <SYSTEM>INFO. Refer to Section 7.5 for information on sending messages to <SYSTEM>INFO.
On successful execution of the MSEND% monitor call, the packet is sent to the receiver's input queue. Word .IPCFS of the packet descriptor block is updated with the sender's PID. Execution of the user's program continues at the second location after the MSEND% call. (MSEND%)
If execution of the MSEND% call is not successful, the message is not sent, and an error code is returned in AC1. The execution of the user's program continues at the instruction following the MSEND% call.
7.4.2 Receiving a Packet
The MRECV% monitor call is used to retrieve a message from the process' input queue. Before a process can retrieve a message, it must know if the message is a long-form message and also must set up a packet descriptor block.
The MRECV% monitor call accepts two words of arguments. The length of the packet descriptor block is given in AC1, and the beginning address of the packet descriptor block is given in AC2. Thus,
| AC1: | length of packet descriptor block. The length cannot be less than 4. |
| AC2: | address of packet descriptor block |
The packet descriptor block can consist of the following nine words. The last five words are optional, and if supplied by the receiver, the values of the sender will be filled in by the system.
| .IPCFL | Flags |
| .IPCFS | Sender's PID |
| .IPCFR | Receiver's PID |
| .IPCFP | Pointer to packet data block where the message is to be placed. |
| .IPCFD | Connected and logged-in directories of the sender. |
| .IPCFC | Enabled capabilities of the sender. |
| .IPCSD | Number of sender's connected directory. |
| .IPCAS | Account string of sender. |
| .IPCLL | Byte pointer for destination of sender's node. |
Refer to Section 7.3 for the details on the packet descriptor and packet data blocks.
The flags that are meaningful when receiving a packet are described in Table 7-3. Refer to Table 7-1 for the complete list of flag bits.
| Bit | Symbol | Meaning |
|---|---|---|
| 0 | IP%CFB | If there are no packets in the receiver's input queue, do not block the process and return an error code if the queue is empty. If this bit is not on, the process waits until a packet arrives, if the queue is empty. |
| 1 | IP%CFS | Use PID referenced in word .IPCFS as sender's PID. |
| 2 | IP%CFR | The receiver's PID is given in word .IPCFR of the packet descriptor block. |
| 3 | IP%CFO | Allow one send request above quota. (Default send quota is 2.) |
| 4 | IP%TTL | Truncate the message if it is larger than the space reserved for it in the packet data block. If this bit is not on and the message is too large, an error code is returned and no message is received. |
| 5 | IP%CPD | Create PID for sender and return in word .IPCFS. |
| 6 | IP%JWP | Make created PID job wide (ignored unless IP%CPD set). |
| 7 | IP%NOA | Do not allow other processes to use created PID (ignored unless IP%CPD set). |
| 18 | IP%CFP | Packet is privileged (requires IPCF capability enabled). |
| 19 | IP%CFV | The message is expected to be a long-form message (that is, a page). The page the message is being stored into cannot be a shared page; it must be a private page. |
| 22 | IP%EPN | Page number in word .IPCFP of the packet descriptor block is 18 bits long. |
The information in word .IPCFS is not supplied by the receiver when the MRECV% call is executed. The system fills in the PID of the sender of the packet when the packet is retrieved.
Word .IPCFR is supplied by the receiver. If bit IP%CFR is on in the flag word, then the PID receiving the packet is taken from word .IPCFR of the packet descriptor block. If bit IP%CFR is not on in the flag word, then word .IPCFR contains either -1, to receive a packet for any PID belonging to this process, or -2, to receive a packet for any PID belonging to this job. When -1 or -2 is given, packets are not received in any particular order except that packets from a specific PID are received in the order in which they were sent. Any other values in this word cause an error code to be returned.
The information in words .IPCFD and .IPCFC is also not supplied by the receiver. If these two words have been specified by the receiver, the system fills in the information when the packet is retrieved. Word .IPCFD contains the sender's connected directory in the left half and the sender's logged-in directory in the right half. Word .IPCFC contains the enabled capabilities of the sender. These words describe the sender at the time the message was sent.
On successful execution of the MRECV% monitor call, the packet is retrieved and placed into the packet data block as indicated by word .IPCFP of the packet descriptor block. AC1 contains the length of the next packet in the queue in the left half and flags from the next packet in the right half (see below). This word returned in AC1 is called the associated variable of the next packet in the queue. If there is not another packet in the queue, AC1 contains zero. Execution of the user's program continues at the second instruction after the MRECV% call.
The flags returned in the right half of AC1 on successful execution of the MRECV% monitor call are described in Table 7-4.
| Bit | Symbol | Meaning |
|---|---|---|
| 30-32 | IP%CFC | System and sender code, set only by a privileged process. The packet was sent by <SYSTEM>IPCF if the code is 1(.IPCCC). The packet was sent by the system-wide <SYSTEM>INFO if the code is 2(.IPCCF). The packet was sent by the receiver's <SYSTEM>INFO if the code is 3(.IPCCP). |
| 33-35 | IP%CFM | Field for return of special messages. If the field contains 1(.IPCFN), then the process' input queue contains a packet that was sent to another PID, but was returned to the sender because it could not be delivered. |
If execution of the MRECV% call is not successful, a packet is not retrieved, and an error code is returned in AC1. The execution of the user's program continues at the instruction following the MRECV% call.
7.5 SENDING MESSAGES TO <SYSTEM>INFO
The <SYSTEM>INFO process is the central information utility for IPCF. It performs functions associated with names and PIDs, such as, assigning a PID or a name or returning a name associated with a PID.
A process can request functions to be performed by <SYSTEM>INFO by executing the MSEND% monitor call (refer to Section 7.4.1). The message portion of the packet (that is, the packet data block) sent to <SYSTEM>INFO contains the request being made. In other words, the total request to <SYSTEM>INFO is a packet consisting of a packet descriptor block and a packet data block containing the request.
Packet Descriptor Block
!=======================================================!
! flag word !
!-------------------------------------------------------!
! sender's PID !
!-------------------------------------------------------!
! 0 !
!-------------------------------------------------------!
! pointer to request !
!=======================================================!
Packet Data Block
!=======================================================!
! code ! function !
! ! !
!-------------------------------------------------------!
! PID !
!-------------------------------------------------------!
! function argument !
!=======================================================!
Refer to Section 7.4.1 for the descriptions of the words in the packet descriptor block. The receiver's PID (word .IPCFR) is 0 when sending a packet to <SYSTEM>INFO.
7.5.1 Format of <SYSTEM>INFO Requests
As mentioned previously, the packet data block (that is, the message portion) of the packet contains the request to <SYSTEM>INFO.
The first word (word .IPCI0) contains a user-defined code in the left half and the function being requested in the right half. The user-defined code is used to associate the response from <SYSTEM>INFO with the correct request. The functions that the process can request of <SYSTEM>INFO are described in Table 7-5.
The second word (word .IPCI1) contains a PID associated with a process that is to receive a duplicate of any response from <SYSTEM>INFO. If this word is zero, the response from <SYSTEM>INFO is sent only to the process making the request.
The third word (word .IPCI2) contains the argument for the function specified in the right half of word .IPCI0. The argument is different depending on the function being requested. The arguments for the functions are described in Table 7-5.
| Function | Argument | Meaning |
|---|---|---|
| .IPCIW | name | Return the PID associated with the given name (refer to Section 7.3.2 for the description of the name). |
| .IPCIG | PID | Return the name associated with the given PID. |
| .IPCII | name | in Assign the given name to the PID ASCIZ associated with the process making the request. The PID is permanent if IP%JWP was set in the flag word when the PID was originally created (refer to Table 7-1). |
| .IPCIJ | name in ASCIZ | Identical to .IPCII function. |
7.5.2 Format of <SYSTEM>INFO Responses
Responses from <SYSTEM>INFO are in the form of a packet sent to the process that made the request. A copy of the response is sent to the PID given in word .IPCI1, if any.
The message portion (that is, the packet data block) of the packet contains the response from <SYSTEM>INFO. The format of this response is
!=======================================================!
! code ! function !
! ! !
!-------------------------------------------------------!
! response !
!-------------------------------------------------------!
! response !
!=======================================================!
The first word (word .IPCI0) contains the user-defined code in the left half and the function that was requested in the right half. These values are copied from the values given in the request.
The second and third words (words .IPCI1 and .IPCI2) contain the response from the function requested of <SYSTEM>INFO. The response is different depending on the function requested. The responses from the functions are described in Table 7-6.
| Function Requested | Response |
|---|---|
| .IPCIW | The PID associated with the name given in the request is returned in word .IPCI1. |
| .IPCIG | The name associated with the PID given in the request is returned in word .IPCI1. |
| .IPCII | No response is returned. |
7.6 Performing IPCF utility functions
A process can request various functions to be performed by executing the MUTIL% monitor call. Some of these functions are enabling and disabling PIDs, creating and deleting PIDs, and returning quotas. Several of the functions that can be requested are privileged functions. These are described in the TOPS-20 Monitor Calls Reference Manual.
The MUTIL% monitor call accepts two words of argument. The length of the argument block is given in AC1, and the beginning address of the argument block is given in AC2.
The argument block has the following format:
!=======================================================!
! function code !
!-------------------------------------------------------!
! argument for function !
!-------------------------------------------------------!
! argument for function !
!=======================================================!
The arguments are different, depending on the function being requested. Any values resulting from the function requested are returned in the argument block, starting at the second word.
Table 7-7 describes the functions that can be requested, the arguments for the functions, and the values returned from the functions.
| Function | Meaning | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| .MUENB | Allow the PID given to receive packets. If the process executing the
call is not the owner of the PID, the process must be privileged.
| |||||||||||||||
| .MUDIS | Disable the PID given from receiving packets. If the process executing
the call is not the owner of the PID, the process must be
privileged.
| |||||||||||||||
| .MUGTI | Return the PID associated with <SYSTEM>INFO.
| |||||||||||||||
| .MUCPI | Create a private copy of <SYSTEM>INFO for the specified job. The
caller must have IPCF capability enabled.
| |||||||||||||||
| .MUDES | Delete the PID given. The process executing the call must own the PID
being deleted.
| |||||||||||||||
| .MUCRE | Create a PID for the process or job given. If the job number given is
not that of the process executing the call, the process must be privileged.
The flag bits that can be specified are IP%JWP and IP%NOA (refer to Table
7-1 for their descriptions).
| |||||||||||||||
| .MUSSQ | Set send and receive quotas for the specified PID. The caller must
have IPCF capability enabled. The new send quota is given in bits 18-26,
and the new receive quota is given in bits 27-35. The receive quota
applies to the specified PID, but the send quota applies to the job to
which that PID belongs.
| |||||||||||||||
| .MUFOJ | Return the number of the job associated with the PID given.
| |||||||||||||||
| .MUFJP | Return all PIDs associated with the job given.
| |||||||||||||||
| .MUFSQ | Return the send quota and the receive quota for the PID
given.
| |||||||||||||||
| .MUFFP | Return all PIDs associated with the process of the PID given.
| |||||||||||||||
| .MUSPQ | Set the maximum number of PIDs allowed for the specified job. The
caller must have IPCF capability enabled.
| |||||||||||||||
| .MUFPQ | Return the maximum number of PIDs allowed for the job given.
| |||||||||||||||
| .MUQRY | Return the packet descriptor block for the next packet in the queue of
the PID given.
| |||||||||||||||
| .MUAPF | Associate the PID given with the process given.
| |||||||||||||||
| .MUPIC | Place the specified PID on a software interrupt channel. An interrupt
is then generated when:
If the channel number is given as -1, the PID is removed from its current channel. The calling process and the process that owns the specified PID must belong to the same job.
| |||||||||||||||
| .MUDFI | Set the PID of <SYSTEM>INFO. An error is given if
<SYSTEM>INFO already has a PID. The caller must have IPCF capability
enabled.
| |||||||||||||||
| .MURSP | Return a PID from the system PID table. The PID is returned in word 2
of the argument block. The system PID table currently has the following
entries:
| |||||||||||||||
| .MUMPS | Return the maximum packet size for the PID given.
| |||||||||||||||
| .MUSKP | Set PID to receive deleted PID messages. Allows a controller task to
be notified if one of its subordinate tasks crashes. After this function
is performed, if the subordinate PID is ever deleted (via RESET or the
.MUDES MUTIL function), the monitor will send an IPCF message to the
controlling PID notifying it that the subordinate PID has been deleted.
This message contains .IPCKP in word 0 and the deleted PID in word 1.
| |||||||||||||||
| .MURKP | Return controlling PID for this subordinate PID.
|
On successful completion of the MUTIL% monitor call, the function requested is performed, and any value is returned are in the argument block. Execution of the user's program continues at the second location following the MUTIL% call.
If execution of the MUTIL% monitor call is not successful, no requested function is performed and an error code is returned in AC1. Execution of the user's program continues at the location following the MUTIL% call.