PN-159 Revision 4 CDPACK ______ Fortran-callable routines for Interprocessor Communication ________________ ________ ___ ______________ _____________ Vicky White and David M. Berg Fermilab P.O.Box 500 Batavia, IL 60510 November 1984 This document describes a package of Fortran-callable routines which allow programs to exchange messages, using a communications driver. The routines are available for both the RSX and RT11 operating systems for the PDP-11, and for VMS on the VAX. Acknowledgments _______________ For their help in the design and testing of CDPACK, and especially the RT-11 system interface, we thank Peter Heinicke and Mark Pyatetsky. Keywords: CONNECTED MACHINES Systems Supported: VAX/VMS, RSX-11M, RT-11 CDPACK - Routines for Interprocessor Communication Page 2 1.0 GENERAL PRINCIPLES OF INTER-PROCESSOR COMMUNICATION 4 2.0 THE SUBROUTINE ARGUMENTS . . . . . . . . . . . . . . 6 3.0 THE SUBROUTINES . . . . . . . . . . . . . . . . . . 8 3.1 CDASGN(CHAN,DEV,UNIT,STAT) . . . . . . . . . . . . 8 3.2 CDOPEN(CHAN,RPTC,STAT) . . . . . . . . . . . . . . 8 3.3 CDCLOS(CHAN,RPTC,STAT) . . . . . . . . . . . . . . 9 3.4 CDXMTW(CHAN,XPTC,XBUF,XWC,STAT) . . . . . . . . . 9 3.5 CDXMT(CHAN,XPTC,XBUF,XWC,STAT) . . . . . . . . . . 9 3.6 CDRCVW(CHAN,RPTC,RBUF,MAXWC,STAT) . . . . . . . 10 3.7 CDRCV(CHAN,RPTC,RBUF,MAXWC,STAT) . . . . . . . . 10 3.8 CDSIGW(CHAN,XPTC,SIGNAL,STAT) . . . . . . . . . 11 3.9 CDSIG(CHAN,XPTC,SIGNAL,STAT) . . . . . . . . . . 11 3.10 CDWAIT(MBN) . . . . . . . . . . . . . . . . . . 11 3.11 CDSTAT(MBN,INF,STAT) . . . . . . . . . . . . . . 12 3.12 CDTMO(TIMVAL,TIMUNT) - (RSX And VAX Only) . . . 13 3.13 CDERRT(STAT,TXTBUF,BUFLEN,TXTLEN) . . . . . . . 13 3.14 CDERRM(STAT,IERR) . . . . . . . . . . . . . . . 14 3.15 CDERRN(STAT,ERNO) . . . . . . . . . . . . . . . 14 4.0 ALTERNATE SUBROUTINES . . . . . . . . . . . . . . 15 4.1 CDCHAN(CHAN) . . . . . . . . . . . . . . . . . . 15 4.2 CDRCVP(RPTC) . . . . . . . . . . . . . . . . . . 15 4.3 CDXMTP(XPTC) . . . . . . . . . . . . . . . . . . 15 4.4 CDRBUF(RBUF,MAXWC) . . . . . . . . . . . . . . . 16 4.5 CDXBUF(XBUF) . . . . . . . . . . . . . . . . . . 16 4.6 Error Returns For CDCHAN,CDRCVP,CDXMTP,CDRBUF,CDXBUF: . . . . . . 16 4.7 CDOUT(XWC,STAT) . . . . . . . . . . . . . . . . 16 4.8 CDOUTW(XWC,STAT) . . . . . . . . . . . . . . . . 17 4.9 CDIN(STAT) . . . . . . . . . . . . . . . . . . . 17 4.10 CDINW(STAT) . . . . . . . . . . . . . . . . . . 17 5.0 ROUTINES SPECIFIC TO EITHER RT11, RSX OR VAX/VMS . 18 5.1 CDMODE(QRCV,QDOWN,SLEEP,RCVTMO) . . . . . . . . 18 5.2 CDUSER(COMPLT,UNSOL) . . . . . . . . . . . . . . 19 5.3 VAX Specific Routines . . . . . . . . . . . . . 20 5.3.1 CD_SET_EFS(FIRST_EFN) . . . . . . . . . . . . 20 5.3.2 CDEFN(EFN) . . . . . . . . . . . . . . . . . . 20 5.3.3 CDERRL(ERLUN) . . . . . . . . . . . . . . . . 21 5.3.4 CDERMODE(NAME,FAC) . . . . . . . . . . . . . . 21 5.3.5 CDGPTC(CHAN,MYPTC,STAT) . . . . . . . . . . . 21 5.3.6 CDKILL(CHAN,STAT) . . . . . . . . . . . . . . 22 5.4 RSX Specific Routines . . . . . . . . . . . . . 22 5.4.1 Effect Of CDMODE QRCV Mode . . . . . . . . . . 22 5.4.2 CDERRL(ERLUN) . . . . . . . . . . . . . . . . 22 5.4.3 CDREJ(MBN,STAT) . . . . . . . . . . . . . . . 23 5.4.4 CDKILL(CHAN,STAT) . . . . . . . . . . . . . . 23 5.4.5 CDSTOP(MBN) . . . . . . . . . . . . . . . . . 23 5.4.6 CDWAKE(CHAN,STAT) . . . . . . . . . . . . . . 23 5.5 RT11 Specific Routines . . . . . . . . . . . . . 24 6.0 ERROR AND STATUS RETURNS . . . . . . . . . . . . . 25 6.1 Table Of Error Messages . . . . . . . . . . . . 25 6.2 Values Of The Status Block For VMS . . . . . . . 26 6.3 Values Of The Status Block For RSX . . . . . . . 27 CDPACK - Routines for Interprocessor Communication Page 3 6.4 Values Of The Status Block For RT11 . . . . . . 28 6.5 Hardware Error Register . . . . . . . . . . . . 28 7.0 USING CDPACK - SPACE FOR EXTRA PTC'S, OVERLAYS . . 29 7.1 Use Of Local Event Flags In RSX And VAX CDPACK . 30 7.2 Warnings . . . . . . . . . . . . . . . . . . . . 30 8.0 EXAMPLES OF USING CDPACK ROUTINES . . . . . . . . 31 8.1 Transmit A Message . . . . . . . . . . . . . . . 31 8.2 Receive A Message (Wait I/O) . . . . . . . . . . 32 8.3 Typical Receiver Code . . . . . . . . . . . . . 33 CDPACK - Routines for Interprocessor Communication Page 4 1.0 GENERAL PRINCIPLES OF INTER-PROCESSOR COMMUNICATION ____________ __________ __ _______________ _____________ Each program, or sub-application of a program, which intends to receive messages must declare which type of messages it wants by specifying the Packet Type Code (PTC) of the messages. It must also ______ ____ ____ specify which link device or devices it is using. The program then has an open 'read session' or connection for this Packet Type Code. A program may declare open connections on any number of link devices. For RSX and VAX systems an arbitrary number of packet type codes may be declared for each link device. For RT11 systems there is an overall maximum of sixteen packet type codes allowed. Two separate programs may not simultaneously request to receive messages of the same Packet Type Code on the same link device. The sender of a message must specify both a data buffer to be sent and the Packet Type Code to be associated with this message. Special single byte messages may also be sent. These are termed signals; they are transferred over a DR11W link using a programmed data transfer, rather than the normal DMA data transfer. The routines described below allow for the exchange of messages and signals between programs. A program may simultaneously use the package for communication on several different link devices, provided a different channel (or logical unit) is assigned to each different device. Although the basic CDPACK calls are identical for RSX ,RT11 and VAX systems, since the communications driver implementations are different some time-dependent communications between programs can perform differently on different systems. The only real difference between the RSX and VAX implementations versus the RT-11 one, concerns the way in which CDRCV[W] operates. In an RT11 system a request to receive a message must have been posted before the message actually is sent over the link device, otherwise the sender of the message will get an error. In an RSX or VAX system this is not necessary, since the arrival of a message initiates a 'wake-up' (AST) to the program which is the receiver of this type of message; i.e. owns this packet type code. The program can then issue the request to receive the message. However, for most normal use of the package in an RSX or VAX system the same rules as for RT11 should apply and the receiver should normally have issued a call to CDRCV[W] before the transmitter starts to send the message. The term 'message block number' is used extensively throughout the following description. Whenever a CDPACK request is made, the particular transaction is allocated an internal data area and an internal identifier. These are termed a message block and message block number respectively. When the transaction has completed and its ___ ___ status has been returned to the caller the message block data area is ______ ___ ____ ________ __ ___ ______ freed for re-use. CDPACK - Routines for Interprocessor Communication Page 5 Note that the status is returned immediately when 'Wait' type requests are used e.g. CDRCVW, CDXMTW, but when 'No-Wait' type requests are made the status is not returned to the caller, thus freeing the message block, until an explicit call to CDSTAT has been made. CDPACK - Routines for Interprocessor Communication Page 6 2.0 THE SUBROUTINE ARGUMENTS ________ __________ _________ The arguments which are used throughout the description are explained below: NOTE All variables and constants are type INTEGER unless otherwise stated (for PDP-11 systems this implies INTEGER*2 constants; for VAX systems this means INTEGER*4). The arguments are always passed by reference. CHAN A variable or constant giving the channel(RT/VAX) or logical unit number(RSX) to be assigned to the link device required. Under RT11 and VAX/VMS the channel number is returned by ________ CDASGN in the variable CHAN and must be saved by the user program for all future calls to CDPACK for this channel. Under RSX-11M the user program must specify a value for CHAN _______ and pass this to all CDPACK routines. RPTC Receive messages with this Packet Type Code XPTC Transmit message with this Packet Type Code XBUF Address of a 16-bit word aligned buffer of data to be transmitted XWC Number of 16-bit words of data in XBUF to be tranmitted RBUF Address of a 16-bit word aligned buffer to receive a message MAXWC Maximum number of 16-bit words which may be received in RBUF STAT Address of a status block which will be filled with status information, when the transfer either completes or times-out. The status block is an INTEGER array of dimension 2. MBN Variable to receive a message block number. Used to make enquiries about the status of a particular transfer when no-wait transfers are used; or the status of a particular open connection. MODE Transfer mode for either transmitting or receiving CDPACK - Routines for Interprocessor Communication Page 7 TIMUNT Unit in which timeout value (for wait) is specified TIMVAL Length of timeout in timeout units INF Variable used to return information on the state of one or more I/O operations or open connections DEV Two ASCII character device name of communications link device e.g. 'CD'. For VAX/VMS DEV must be a character string variable and may be the full device name - or logical name referring to the communication link device. UNIT Physical unit number of communications link device e.g. for device CD0, the unit number is 0. For VAX/VMS this argument if used will be appended to the character string DEV, as for the PDP-11 cases. However for VAX/VMS this argument may be omitted. CDPACK - Routines for Interprocessor Communication Page 8 3.0 THE SUBROUTINES ________ ___________ The following routines are available for all systems. 3.1 CDASGN(CHAN,DEV,UNIT,STAT) __________________________ Associates a channel(RT or VAX) or a logical unit(RSX) with the unit number UNIT of device DEV. This call must be made before any transfer calls or open connection requests can be made. Under RT-11, the first call to CDASGN also loads the CD handler and allocates three additional queue elements. Error returns: STAT(1) = 1 channel or logical unit CHAN has been successfully associated with the required link device STAT(1) /=1 see error tables at end 3.2 CDOPEN(CHAN,RPTC,STAT) ______________________ Specifies that the program wishes to RECEIVE messages with packet type code RPTC, arriving on the link device associated with channel CHAN. A call to CDOPEN must be made before such messages can be received. ____ Separate calls to CDOPEN must be made for each packet type code which the program wishes to receive. Messages may be TRANSMITTED by a program however, without any call to CDOPEN. A program may call CDOPEN an arbitrary number of times, for different Packet Type Codes and/or channels. However if more than one such call is to be made you may need to allow space in your program - see Section 7 for how to do this. Error returns: STAT(1) = 1 Success STAT(2) contains the message block number (MBN) for this open connection. STAT(1) /=1 see error tables at end An active message block is associated with each open connection. CDPACK - Routines for Interprocessor Communication Page 9 3.3 CDCLOS(CHAN,RPTC,STAT) ______________________ Specifies that messages with Packet Type Code RPTC, arriving on channel CHAN are no longer to be received by this program. Error returns: STAT(1) = 1 Open connection successfully closed STAT(1) /=1 see error tables at end 3.4 CDXMTW(CHAN,XPTC,XBUF,XWC,STAT) _______________________________ Transmit XWC 16-bit words of buffer XBUF with transmit Packet Type Code XPTC. Wait for completion, or driver timeout, of the transfer before returning from the subroutine call. Error returns: STAT(1) = 1 Message successfully transmitted STAT(2) contains the number of 16-bit words transferred (XWC) STAT(1) /=1 see error tables at end 3.5 CDXMT(CHAN,XPTC,XBUF,XWC,STAT) ______________________________ Transmit XWC 16-bit words of buffer XBUF with transmit Packet Type Code XPTC. Do not wait for the transfer to complete before returning from the subroutine call. Error returns: STAT(1) = 1 Message transmission successfully initiated. STAT(2) contains the message block number (MBN) to be used for all enquiries about the current status of the transfer. STAT(1) /=1 see error tables at end CDPACK - Routines for Interprocessor Communication Page 10 3.6 CDRCVW(CHAN,RPTC,RBUF,MAXWC,STAT) _________________________________ A call to CDOPEN(CHAN,RPTC,STAT) must have already been made successfully before a call to CDRCVW is made. Receive a message with Packet Type Code RPTC, into buffer RBUF. The maximum number of 16-bit words which can be received is MAXWC. Wait for completion of the operation, or optionally timeout(not for RT-11). Error returns: STAT(1) = 1 Message successfully received STAT(2) contains the number of 16-bit words actually received STAT(1) /=1 see error tables at end 3.7 CDRCV(CHAN,RPTC,RBUF,MAXWC,STAT) ________________________________ A call to CDOPEN(CHAN,RPTC,STAT) must have already been made successfully before a call to CDRCV is made. Receive a message with Packet Type Code RPTC, into buffer RBUF. The maximum number of 16-bit words which can be received is MAXWC. Do not wait for the message to arrive before returning from the subroutine call. Error returns: STAT(1) = 1 Receive buffer ready to receive next message for Packet Type Code RPTC on channel CHAN STAT(2) contains the message block number (MBN) to be used for all enquiries about the current status of the message. STAT(1) /=1 see error tables at end CDPACK - Routines for Interprocessor Communication Page 11 3.8 CDSIGW(CHAN,XPTC,SIGNAL,STAT) _____________________________ Transmit a single byte signal SIGNAL with transmit Packet Type Code XPTC. Wait for signal transmission to complete before returning from the subroutine call. Error returns: STAT(1) = 1 Signal successfully transmitted STAT(1) /=1 see error tables at end 3.9 CDSIG(CHAN,XPTC,SIGNAL,STAT) ____________________________ Transmit a single byte signal with transmit Packet Type Code XPTC. Do not wait for signal transmission to complete or timeout before returning from subroutine call. Error returns: STAT(1) = 1 Signal transfer successfully initiated STAT(2) contains the message block number (MBN) to be used for all enquiries about the current status of the transfer. STAT(1) /=1 see error tables at end 3.10 CDWAIT(MBN) ___________ Wait for a pending transfer with message block number MBN to complete. If the message block number MBN is that of an open connection with no pending transfer, wait for a signal or message to arrive. If MBN = 0 the wait is for some completion or action, on any of the active __ ___ __ ___ ______ channels, and the corresponding message block number is returned in ________ ________ MBN. No information is returned by the CDWAIT call; a call to CDSTAT with the same MBN must be made to get information about the actual transfer which has completed. If MBN is not a valid active message block number then a return from the subroutine call will be made immediately. A call to CDSTAT with this MBN would then indicate that the message block number was invalid. CDPACK - Routines for Interprocessor Communication Page 12 3.11 CDSTAT(MBN,INF,STAT) ____________________ This routine is used to enquire about the state of any transfer which was initiated with a CDXMT, CDRCV, CDOUT, CDIN or CDSIG request, or to enquire about the state of any open connection. The message block number MBN which was returned in the second status word when the transfer was initiated, or the open connection made, must be specified in the call to CDSTAT. If MBN = 0 then information about the FIRST message block number which has a completed or timed out transfer will be returned. After a call to CDSTAT has been made, for a message block number on which a transfer has completed or timed out, that message block number is no longer associated with an 'active' transfer. Further calls to CDSIG, CDXMT, CDRCV or CDOPEN may then result in the same message block number being re-used and associated with a new transfer or open connection. Status returns: Value of INF Meaning STAT(1) STAT(2) ------------ ------- ------- ------- -1 This message block is not active - - 0 Open connection - no new transfers - - 1 Transmission of message pending - - 2 Receive of message pending - - 3 Tranmission of message completed as for CDXMTW or timed out 4 Receive of message completed or timed out as for CDRCVW * 5 Pending message, no buffer available yet - WC of pending message 6 New signal arrived Signal Signal number ------------------------------------------------------------------------ * The value 5 for INF may occur under the RSX or VAX/VMS system. Here the program is informed when there is a pending message on the link and normally should respond by issuing a READ request, thus allowing the transfer of the data over the link to proceed. ------------------------------------------------------------------------ CDPACK - Routines for Interprocessor Communication Page 13 3.12 CDTMO(TIMVAL,TIMUNT) - (RSX And VAX Only) ____________________ Set timeout value to be used when RECEIVING messages with CDRCVW or CDINW, provided the timeout mode of transfer has been set up (see CDMODE). TIMUNT specifies the unit in which the timeout is to be counted 1=ticks, 2=seconds, 3=minutes, 4=hours Any other value for TIMUNT is interpreted as ticks. TIMVAL specifies the length of the timeout in units of TIMUNT If TIMVAL= 0 then no timeout will be used. A default value of 10 seconds is used for a receive timeout if CDTMO is not called. NOTE: A transmitted message may also fail with a timeout error status. This timeout however is internal to the CD device drivers. It is approximately 10 seconds and is not settable by the user. Such a timeout occurs only when a receiver for a transmitted message exists, but fails to actually receive the message within this 10 second period. 3.13 CDERRT(STAT,TXTBUF,BUFLEN,TXTLEN) _________________________________ The errors and status returns given in the two word status block STAT are listed in Section 7 , for RSX , RT11 and VAX/VMS systems. For uniformity between systems and between programs each type of error has its own CDPACK error number and text. This routine fills the buffer TXTBUF with the text of the appropriate error message. BUFLEN length of TXTBUF available in bytes (Integer) TXTLEN Integer variable to receive the length (in bytes) of the text placed in array TXTBUF TXTBUF INTEGER or LOGICAL*1 array to receive ASCII text of the error message. NOTE: For VAX/VMS, if a character string variable is used for the text it must be passed to the routine CDERRT as %REF(TXTBUF) If the channel and Packet Type Code have been set up by calls to CDCHAN and CDXMTP or CDRCVP then that information will be included in CDPACK - Routines for Interprocessor Communication Page 14 the text of the message. 3.14 CDERRM(STAT,IERR) _________________ Prints out a message giving the standard error number and error text for the error and status information in the status block STAT. The message is printed out on the terminal. For RSX and VAX- see routine CDERRL(ERLUN) to specify the unit to be used to output the error message. IERR is an INTEGER variable used to return the system error code on printing of the message. 3.15 CDERRN(STAT,ERNO) _________________ The standard CDPACK error number for this type of error will be returned in ERNO. ERRNO is an INTEGER variable. CDPACK - Routines for Interprocessor Communication Page 15 4.0 ALTERNATE SUBROUTINES ______________ ___________ The calls CDXMT[W],CDSIG[W] and CDRCV[W], provide the basic calls to transfer messages with all input parameters specified on each subroutine call. Sometimes it is desirable to be able to set up the input parameters for a transfer operation in separate calls, ahead of the actual transfer request. The following routines are provided for this. 4.1 CDCHAN(CHAN) ____________ All future calls to CDPACK now refer to channel CHAN 4.2 CDRCVP(RPTC) ____________ All future calls to CDIN[W] now refer to receive Packet Type Code RPTC 4.3 CDXMTP(XPTC) ____________ All future calls to CDOUT[W] now refer to transmit Packet Type Code XPTC CDPACK - Routines for Interprocessor Communication Page 16 4.4 CDRBUF(RBUF,MAXWC) __________________ All future messages received from calls made to CDIN will be received into buffer RBUF. The maximum size of message which can be received is MAXWC 16-bit words. 4.5 CDXBUF(XBUF) ____________ All future messages transmitted via calls made to CDOUT will be from data buffer XBUF. 4.6 Error Returns For CDCHAN,CDRCVP,CDXMTP,CDRBUF,CDXBUF: _____ _______ ___ ___________________________________ There are NO ERROR RETURNS on calls to these routines. Any errors in specifying the arguments will only be reported on the next call to transmit or receive a message. 4.7 CDOUT(XWC,STAT) _______________ Transmit a message of length XWC 16-bit words. The channel, transmit Packet Type Code and buffer to be used for the message must have been previously set up by calls to CDCHAN,CDXMTP and CDXBUF. Error returns: as for CDXMT CDPACK - Routines for Interprocessor Communication Page 17 4.8 CDOUTW(XWC,STAT) ________________ As CDOUT, but wait for completion or timeout on the message transfer before returning from the subroutine call Error returns: as for CDXMTW 4.9 CDIN(STAT) __________ Receive a message. The channel, receive Packet Type Code, receive buffer and maximum message size in 16-bit words must have been previously set up by calls to CDCHAN,CDRCVP,CDRBUF. A call to CDOPEN for the appropriate channel and receive packet type code must also have previously been made. Do not wait for completion or timeout of the transfer. Error returns: as for CDRCV 4.10 CDINW(STAT) ___________ Receive a message. The channel, receive Packet Type Code, receive buffer and maximum message size in 16-bit words must have been previously set up by calls to CDCHAN,CDRCVP,CDRBUF. A call to CDOPEN for the appropriate channel and receive packet type code must also have previously been made. Wait for completion or timeout of the transfer. Error returns: as for CDRCVW CDPACK - Routines for Interprocessor Communication Page 18 5.0 ROUTINES SPECIFIC TO EITHER RT11, RSX OR VAX/VMS _____________ ________ __ ______ _____ ___ __ _______ Also included in this section are common routines whose interpretation is slightly different on different systems. These routines are not needed to perform data transfers between ______ programs. They provide additional features, specific to the particular communications driver involved. 5.1 CDMODE(QRCV,QDOWN,SLEEP,RCVTMO) _______________________________ Sets up the mode of operation to be used on subsequent transmit and receive operations. QRCV logical argument (not applicable for RT11) If TRUE a call to CDRCV[W] will cause a receive request to be queued to the communications driver to await arrival of a suitable message. Under RSX this will make a task have 'outstanding I/O requests' and therefore be non-checkpointable. If FALSE the request to the driver will only be issued when there is a message pending awaiting a buffer to be received into. The task will then be checkpointable even though is has issued a call to CDRCV[W] The response time for receiving a message is higher in this mode. ** Default - RSX ** FALSE ** Default - VAX/VMS ** TRUE QDOWN logical argument (RSX and VAX only) If TRUE any transfer request will be queued to the communications driver even if the link is down. If FALSE all transfer requests issued when the link is down will complete with an error status. ** Default ** FALSE SLEEP logical argument (only applicable for RSX) If TRUE then on the next receive or transmit request the communications driver will be asked to detach from the interrupts of the link device. CDPACK - Routines for Interprocessor Communication Page 19 ** Default ** FALSE After a receive or transmit request has been successfully executed with SLEEP = TRUE then the mode automatically reverts to NOT SLEEP mode and requires an additional call to CDMODE to reset it to SLEEP mode. RCVTMO logical argument (RSX and VAX only) If TRUE then a receive message request, in a wait call will have a timeout set up for its completion. ** Default** FALSE On VAX only, an argument which is not used may be omitted e.g. CALL CDMODE(,,,RCVTMO) 5.2 CDUSER(COMPLT,UNSOL) ____________________ Sets up the addresses of user routines to be called when either a transfer completes or an unsolicited message arrives. COMPLT is the name of a user routine which will be called whenever a transfer completes. It is a normal routine (in that you return from it by a normal RETURN). However it is called from AST level (RSX and VAX) or from a completion routine (RT-11). For RSX, this routine is called with an argument MBN giving the message block number of the completed transfer. UNSOL is the name of a user routine which will be called whenever an unsolicited message (data buffer or signal) arrives. It is also a normal routine, but is called from AST level (RSX and VAX) or completion routine (RT-11). For RSX, this routine is called with an argument MBN giving the message block number of the open connection on which the message arrived. Omitting the argument COMPLT cancels the calling of a user routine when a transfer completes. Similarly omitting the argument UNSOL disables the calling of a user routine on unsolicited message. The user routines currently declared at the actual time of the transfer completion, or unsolicited message arrival, are the ones called. NOTE: This feature must be used with care. A user AST or completion routine may need to be written in Macro for PDP operating systems. For RT-11 and RSX, CDPACK routines may be called from completion routine/AST level. However CDSTAT must still be called to declare the CDPACK - Routines for Interprocessor Communication Page 20 message block no longer active. For VAX systems NO CALLS TO CDPACK __ _____ __ ______ MAY BE MADE FROM AST CODE - CDPACK is NOT RE-ENTRANT CODE FOR VAX. ___ __ ____ ____ ___ ____ ___ __________ ____ ___ ___ For PDP-11 operating systems, however, CDPACK is written as re-entrant code (except for the routines CDASGN, CDERRT and CDERRM). 5.3 VAX Specific Routines ___ ________ ________ 5.3.1 CD_SET_EFS(FIRST_EFN) _____________________ Specify the first event flag number of the four consecutive event flags, which are used by the CDPACK routines. FIRST_EFN is an INTEGER variable or constant. If this routine is not called the four event flags used by the package default to 21,22,23,24. Error returns: none. Specifying an invalid event flag number will result in error returns from other CDPACK routines, indicating an invalid Event flag has been used. 5.3.2 CDEFN(EFN) __________ Specify a local event flag EFN to be set when either a transfer on any channel completes or times out, or when a message or signal arrives on any one of the open connection associated with the calling program. This enables a program to wait on the logical 'OR' of several events; one or more of which may be link activity. Error returns: none. Specifying an invalid event flag number will result in error returns from other CDPACK routines, indication invalid Event flag has been used. CDPACK - Routines for Interprocessor Communication Page 21 5.3.3 CDERRL(ERLUN) _____________ Specifies that error messages output using routine CDERRM should be written out on FORTRAN unit ERLUN. Error returns: none. CDERRM gives the system error message on the write to this logical unit. Default value for this logical unit number is 6. 5.3.4 CDERMODE(NAME,FAC) __________________ NAME and FAC are logical arguments which determine whether the error status name and facility code are to be supplied on all subsequent calls to CDERRT or CDERRM. Default is both true. For example, with NAME and FAC both true, an error message might be 1 CDPACK_SUCCESS, Successful transfer or operation with just NAME set to false that error message would become 1 CDPACK, Successful transfer or operation with just FAC set to false that error message would become 1 SUCCESS, Successful transfer or operation and with both NAME and FAC set false you would get 1 Successful transfer or operation 5.3.5 CDGPTC(CHAN,MYPTC,STAT) _______________________ Routine called by a program which wishes to use a packet type code temporarily for the duration of its run, in order to receive messages. This routine is equivalent to CDOPEN. However the packet type code allocated for temporary use is returned by this routine in the INTEGER ________ variable MYPTC. Error returns: see table of error returns at end CDPACK - Routines for Interprocessor Communication Page 22 5.3.6 CDKILL(CHAN,STAT) _________________ Cancel all outstanding I/O requests on this channel, or any other channel assigned to the same link device as this one. Error returns: see table of error returns at end 5.4 RSX Specific Routines ___ ________ ________ 5.4.1 Effect Of CDMODE QRCV Mode ______ __ ______ ____ ____ The default mode of operation in RSX when waiting for a message to arrive with a CDRCV or CDRCVW call does not issue a QIO to the communications driver until the message is actually pending. If the QRCV mode is specified then a QIO will be queued to the communications driver, thus causing the task to have outstanding I/O requests and be non-checkpointable. This mode should therefore be used with care. 5.4.2 CDERRL(ERLUN) _____________ Specifies that error messages output using routine CDERRM should be written out on logical unit ERLUN. Error returns: none. CDERRM gives the system error message on the write to this logical unit. Default value for this logical unit number is 5. CDPACK - Routines for Interprocessor Communication Page 23 5.4.3 CDREJ(MBN,STAT) _______________ Reject the pending message for message block number MBN, which is pending awaiting a receive buffer to be specified. Error returns: see table of error returns at end 5.4.4 CDKILL(CHAN,STAT) _________________ Cancel all outstanding I/O requests on this channel, or any other channel assigned to the same link device as this one. Error returns: see table of error returns at end 5.4.5 CDSTOP(MBN) ___________ Same as CDWAIT but puts the task in the stop state if there is no outstanding I/O. Error returns: see table of error returns at end 5.4.6 CDWAKE(CHAN,STAT) _________________ Inform the communications driver that the device associated with channel CHAN has been released by the owning program and should be controlled by the communications driver. Error returns: see table of error returns at end CDPACK - Routines for Interprocessor Communication Page 24 5.5 RT11 Specific Routines ____ ________ ________ ------- none ------- CDPACK - Routines for Interprocessor Communication Page 25 6.0 ERROR AND STATUS RETURNS __________ ___ ______ _______ All numbers in the tables below are decimal. 6.1 Table Of Error Messages __________ __ _____ ________ -1 Unknown CDPACK error 0 Operation is pending 1 Successful operation 2 Channel not assigned to link device 3 Channel can not be assigned to link device 4 Maximum number of open sessions or message blocks exceeded 5 Communications driver not resident 6 Invalid channel number 7 Invalid device 8 Invalid PTC 9 No open session for this PTC 10 PTC already owned 11 No receiver for this PTC 12 Illegal or zero length transmit or receive buffer 13 Message rejected by receiver 14 Timeout from driver during transmission 15 Fatal hardware error on device 16 No message to receive 17 Incomplete transfer of message 18 Timeout on request to driver 19 Driver Bug check 20 CDPACK Bug check 21 Device not disconnected 22 Vector for device in use 23 Transfers pending for this PTC 24 Message block not active 25 All transfers cancelled 26 Link Down 27 Bad arguments in CDPACK call 28 CDASGN called after initialisation 29 Receiver end of message error 30 Signal not acknowledged 31 Dynamic memory exhausted 32 Invalid START/STOP request (VAX) 33 PTC already owned by caller 34 No Unibus mapping registers available (VAX) 35 Buffered data path cannot be allocated (VAX) 36 Link has not been STARTed CDPACK - Routines for Interprocessor Communication Page 26 6.2 Values Of The Status Block For VMS ___________ __ ___ ______ _____ ___ ___ Error STAT(1) STAT(2) Routines involved 0 0 CDRCV,CDXMT,CDIN,CDOUT,CDSIG 1 SS$_SUCCESS depends on all routines routine 3 SS$_NOIOCHAN CDASGN 4 CD_NOSPACE(302) CDOPEN,CDRCV[W],CDXMT[W],CDSIG[W] CDIN[W],CDOUT[W] 5 SS$_DEVOFFLINE CDOPEN,CDXMT[W],CDOUT[W],CDSIG[W] 6 SS$_IVCHAN CDASGN 7 SS$_IVDEVNAM CDASGN 8 SS$_BADPARAM CDOPEN,CDCLOS,CDRCV[W],CDXMT[W], CDSIG[W],CDIN[W],CDOUT[W] 9 SS$_DEVNOTALLOC CDCLOS,CDRCV[W],CDIN[W] 10 SS$_DEVALLOC CDRCV[W] CD_DUP CDOPEN 11 SS$_NOSUCHOBJ CDXMT[W],CDOUT[W],CDSIG[W] 12 SS$_BUFBYTALI CDRCV[W],CDXMT[W],CDOUT[W],CDIN[W] SS$_BUFNOTALIGN 13 SS$_REJECT CDXMT[W],CDOUT[W] 14 SS$_HANGUP error register CDRCV[W],CDXMT[W],CDOUT[W],CDIN[W] CDSIG[W] 15 SS$_CTRLERR error register CDRCV[W],CDXMT[W],CDOUT[W],CDIN[W] 16 SS$_NOWRT CDRCV[W],CDIN[W] 17 SS$_DATAOVERUN WC transferred CDXMT[W],CDRCV[W],CDOUT[W],CDIN[W] 18 SS$_TIMEOUT CDXMTW,CDRCVW,CDINW,CDOUTW 19 SS$_BUGCHECK CDXMT[W],CDRCV[W],CDSIG[W] CDIN[W],CDOUT[W] 21 SS$_DISCONNECT CDWAKE 23 SS$_DEVACTIVE CDCLOS,CDKILL 25 SS$_CANCEL CDKILL SS$_ABORT any routine 26 SS$_PROTOCOL CDOPEN,CDXMT[W],CDOUT[W],CDSIG[W] 27 SS$_ASTFLT CDOPEN CD_ARGS any routine 29 SS$_REMRSRC CDXMT[W] 30 SS$_NOSIGNAL CDSIG[W] 31 SS$_INSFMEM any routine 32 SS$_DEVREQERR (no CDPACK routine currently) 33 SS$_DEVALRALLOC CDOPEN 34 SS$_DEVICEFULL (no CDPACK routine currently) 35 SS$_DIRFULL (no CDPACK routine currently) 36 SS$_DEVINACT any routine CDPACK - Routines for Interprocessor Communication Page 27 6.3 Values Of The Status Block For RSX ___________ __ ___ ______ _____ ___ ___ Error STAT(1) STAT(2) Routines involved 1 1 (IS.SUC) depends on all routines routine 2 - 5 (IE.ULN) CDOPEN,CDRCV[W],CDXMT[W],CDOUT[W] CDIN[W],CDSIG[W] 3 - 90 (IE.LNL) CDASGN 4 4(+512) CDOPEN,CDRCV[W],CDXMT[W],CDSIG[W] CDIN[W],CDOUT[W] 5 -106 CDOPEN,CDXMT[W],CDOUT[W],CDSIG[W] 6 - 96 (IE.ILU) CDASGN 7 - 92 (IE.IDU) CDASGN 8 -112 (IE.IPT) CDOPEN,CDCLOS,CDRCV[W],CDXMT[W], CDSIG[W],CDIN[W],CDOUT[W] 9 -103 (IE.DNE) CDCLOS,CDRCV[W],CDIN[W] 10 -100 (IE.PTO) CDOPEN 11 - 73 (IE.URJ) CDXMT[W],CDOUT[W],CDSIG[W] 12 - 6 (IE.SPC) CDRCV[W],CDXMT[W],CDOUT[W],CDIN[W] 13 - 88 (IE.REJ) CDXMT[W],CDOUT[W] 14 - 3 (IE.DNR) driver state CDRCV[W],CDXMT[W],CDOUT[W],CDIN[W] CDSIG[W] 15 - 59 (IE.FHE) error register CDRCV[W],CDXMT[W],CDOUT[W],CDIN[W] 16 -104 (IE.NRP) CDRCV[W],CDIN[W] 17 - 13 (IE.DAO) WC transferred CDXMT[W],CDRCV[W],CDOUT[W],CDIN[W] 18 18(+512) CDXMTW,CDRCVW,CDINW,CDOUTW 19 -102 (IE.NEX) or CDXMT[W],CDRCV[W],CDSIG[W] -111 (IE.BUG) CDIN[W],CDOUT[W] 20 20(+512) any routine 21 - 89 (IE.NDS) CDWAKE 22 - 94 (IE.VIU) CDWAKE 23 - 95 (IE.IOQ) CDCLOS CDIN[W],CDOUT[W] 24 24(+512) CDSTAT,CDREJ,CDEFN 25 - 15 (IE.ABO) CDKILL 26 -101 (IE.LDN) CDOPEN,CDXMT[W],CDOUT[W],CDSIG[W] 27 27(+512) any routine 28 28(+512) CDASGN 29 -110 (IE.EME) CDXMT[W] 30 -93 (IE.SNA) CDSIG[W] CDPACK - Routines for Interprocessor Communication Page 28 6.4 Values Of The Status Block For RT11 ___________ __ ___ ______ _____ ___ ____ Error STAT(1) STAT(2) Routines involved 1 1 All routines 2 2 CDOPEN,CDRCV[W],CDXMT[W],CDOUT[W] CDIN[W],CDSIG[W] 3 30 CDASGN 4 3 CDOPEN,CDRCV[W],CDSND[W],CDSIG[W] CDIN[W],CDOUT[W] 8 11 CDOPEN,CDCLOS,CDRCV[W],CDXMT[W], CDSIG[W],CDIN[W],CDOUT[W] 9 5 CDCLOS,CDRCV[W],CDIN[W] 11 -20 CDXMT[W],CDOUT[W],CDSIG[W] 12 7 CDRCV[W],CDXMT[W],CDOUT[W],CDIN[W] 13 -60 CDXMT[W],CDOUT[W] 14 -50 error register CDRCV[W],CDXMT[W],CDOUT[W],CDIN[W] 15 -40 error register CDRCV[W],CDXMT[W],CDOUT[W],CDIN[W] 17 -10 WC transferred CDXMT[W],CDOUT[W],CDRCV[W],CDIN[W] 18 -30 CDXMTW,CDRCVW,CDOUTW 20 10 any routine 25 -70 CDXMT[W],CDRCV[W],CDSIG[W] 26 -100 CDXMT[W],CDRCV[W],CDSIG[W] 6.5 Hardware Error Register _____________ _____ ________ The contents of the error register indicate what type of hardware error occurred. The error bits are described below: Bit 0 Error register flag - always set Bit 1-7 not used Bit 8 set if using burst mode Bit 9 Data late Bit10 memory parity error on memory read Bit11 power fail during DMA Bit12 cycle request whilst processing Bit13 attention bit - set by interupting partner machine Bit14 attempting to transfer to or from non-existent memory Bit15 Error bit - set if any of bits 9-15 are set CDPACK - Routines for Interprocessor Communication Page 29 7.0 USING CDPACK - SPACE FOR EXTRA PTC'S, OVERLAYS __________ ______ _ _____ ___ _____ ______ ________ The CDPACK package of routines uses the named common CDCM82 for its internal tables and flags. This common area should therefore NOT be used by the program itself. The following discussion on space and overlays applies only to the PDP-11 operating systems RT-11 and RSX. (For VAX there is an overall maximum of 50 message blocks currently). If the program is overlaid it is important that the common CDCM82 reside in the root segment. CDCM82 normally contains space for three message blocks to be active simultaneously. Each open connection for a packet type code is an active message block and each transfer request that is made uses a message block until the transfer either completes or times out and the status of the transfer has been passed to the program. If three message blocks are sufficient then unless it is necessary to explicitly declare CDCM82 common in order to force it into the root (RT), then no mention of the common need be made in the user program. Similarly the common CDCM83, which directly follows CDCM82, need only be explicitly referenced if that is necessary in order to force it into the root segment. If space for more message blocks is needed the user of the package must declare the common CDCM82 in the program specifying a suitable number of words of space. CDCM82 should be length (words) 20 + 8*number of message blocks + 3*number of channels used The common CDCM83 is used by the package to determine the length of CDCM82 and should therefore not be used by the program. Under RT-11 CDCM83 also contains space for three additional queue elements. For RT11 both commons should be explicitly referenced and great care should be taken to see that the commons are actually adjacent - see the map. The PSECT ..CD.. is used by the package for its _____ ______ AST/completion routines and must also be put into the root of an ____ ____ __ ___ ____ ___ ____ __ __ overlaid program. ________ ________ When using RSX version 4 a COMMON with the attribute SAV will automatically be placed in the root segment. From Fortran a common may be given this attribute by SAVE /CDCM82/ in addition to the normal COMMON declaration CDPACK - Routines for Interprocessor Communication Page 30 7.1 Use Of Local Event Flags In RSX And VAX CDPACK ___ __ _____ _____ _____ __ ___ ___ ___ ______ The RSX and VAX versions of CDPACK both use local event flags internally. The RSX version uses by default an event flag number equal to the logical unit number used in the CDPACK call. The VAX version uses four event flags. The four event flags may be set to any four consecutive Event flag numbers by a call to CD_SET_EFS(FIRST_EF_NUM). The event flags default to values 21,22,23,24. The first of these four event flags is used for indication of the completion of any "no-wait" calls for any channel. This particular event flag can be changed independently by a call to CDEFN. The second event flag is used for timeout on "no-wait" I/O, but is actually used only when the mode QRCV = .FALSE. has been set using CDMODE. The last two event flags are used internally in the package in the QIO and QIOW calls made to the communications driver. 7.2 Warnings ________ 1. you should not mix Wait and no-wait CDRCV's on the same ___ ______ ___ ___ ____ ___ _______ _______ channel in RSX systems, if you are using the mode of CDRCV, which does not actually issue a read request to the driver until a message arrives over the link. It would be possible to get some confusing results if a CDRCV was later followed by a CDRCVW on the same channel. 2. Any use of the 'User Completion routine/AST Hook' should be done with care. Completion/AST level code may need to be written in Macro and matters of re-entrancy of code must be carefully considered. 3. On the VAX CDPACK is NOT RE-ENTRANT and therefore should not ______ __ ___ __________ be called from AST routines. Both PDP-11 implementations of CDPACK are re-entrant and CDPACK routines may be called from AST/Completion routines. CDPACK - Routines for Interprocessor Communication Page 31 8.0 EXAMPLES OF USING CDPACK ROUTINES _____________ __ _____ ______ ________ Note: these examples are written in "machine-independent" FORTRAN for simplicity. VAX users would have to define a logical name CD0: to be equivalent to their real link device eg. CDA0 or CDA1, in order to actually run the examples below. Normally code written only for the vax would have CDASGN calls of the form CALL CDASGN(CHAN,'CDA0:',,ISTAT) or CALL CDASGN(CHAN,'CDA',IUNIT,ISTAT) where IUNIT could take value 0 or 1 depending on whether a real DR11-W link were in use, or a virtual internal link. 8.1 Transmit A Message ________ _ _______ INTEGER CHAN,RPTC,EVXPTC INTEGER*2 IBUF(nnn) !note buffer length is always 16-bit WC. DIMENSION ISTAT(2) C C assign channel to link device 'CD' unit 0 C for RSX CHAN must be a suitable number for a logical unit C number before calling CDASGN. For VAX and RT-11 the channel number C will be returned in variable CHAN. C CALL CDASGN(CHAN,'CD',0,ISTAT) IF(ISTAT(1).EQ.1) GOTO 10 C C error on assigning channel to link device C CALL CDERRM(ISTAT,IERR) .....other error handling C C transmit message to a receiver who has an open session for C packet type code EVXPTC C 10 CALL CDXMTW(CHAN,EVXPTC,IBUF,IWC,ISTAT) IF(ISTAT(1).NE.1) CALL CDERRM(ISTAT,IERR) ..... ..... CDPACK - Routines for Interprocessor Communication Page 32 8.2 Receive A Message (Wait I/O) _______ _ _______ _____ ____ INTEGER CHAN,RPTC,EVXPTC INTEGER*2 IBUF(nnn) !note buffer length is always 16-bit WC. DIMENSION ISTAT(2) C C assign channel to link device 'CD' unit 1 C for RSX CHAN must be a suitable number for a logical unit C number before calling CDASGN. For VAX and RT-11 the channel number C will be returned in variable CHAN. C CALL CDASGN(CHAN,'CD',1,ISTAT) IF(ISTAT(1).EQ.1) GOTO 10 C error on assigning channel to link device C CALL CDERRM(ISTAT,IERR) ....other error handling C C open a read session for packet type code RPTC - i.e. declare C that you intend to receive messages with packet type code RPTC C 10 CALL CDOPEN(CHAN,RPTC,ISTAT) IF(ISTAT(1).EQ.1) GOTO 20 CALL CDERRM(ISTAT,IERR) ...other error handling C C Wait for message to arrive C 20 CALL CDRCVW(CHAN,RPTC,IBUF,MAXLEN,ISTAT) !receive message IF(ISTAT(1).NE.1) CALL CDERRM(ISTAT,IERR) .... .... CDPACK - Routines for Interprocessor Communication Page 33 8.3 Typical Receiver Code _______ ________ ____ INTEGER CHAN,RPTC,EVXPTC INTEGER*2 BUF(nnn) !note buffer length is always 16-bit WC. DIMENSION ISTAT(2),IMBN(2) C C assign channel to link device 'CD' unit 0 C for RSX CHAN must be a suitable number for a logical unit C number before calling CDASGN. For VAX and RT-11 the channel number C will be returned in variable CHAN. C CALL CDASGN(CHAN,'CD',0,ISTAT) ! assign channel to CD0: IF(ISTAT(1).EQ.1) GOTO 10 CALL CDERRM(ISTAT,IERR) ...other error handling C C open a read session for packet type code RPTC C 10 CALL CDOPEN(CHAN,RPTC,ISTAT) IF(ISTAT(1).EQ.1) GOTO 20 CALL CDERRM(ISTAT,IERR) ...other error handling C C declare buffer to receive message into and check status of C CDRCV request C 20 CALL CDRCV(CHAN,RPTC,IBUF,MAXLEN,IMBN) IF(IMBN(1).EQ.1) GOTO 30 ! check status is ok CALL CDERRM(IMBN,IERR) ! else report error using ...error handling... ! one of the standard error .... ! routines 30 ..... ...do other stuff ... C C now find out the status of this receive - the message block number C for this read was returned in IMBN(2) on the call to CDRCV C CALL CDSTAT(IMBN(2),INF,ISTAT) ! see if any messages arrived? IF(INF.NE.0) GOTO 20 ....i/o not done yet - do something else or CALL CDWAIT(IMBN(2)) ..... C C MESSAGE HAS ARRIVED C 20 GOTO( , , , ,...) INF !decide what has happened ..... ......