PN - 159 Revision 1 [white.doc]pn159.rno CDPACK Fortran-callable routines for Interprocessor Communication Ben Burch Peter Heinicke Mark Pyatetsky Vicky White October 20th 1982 (April 8th 1982 - Original Version) A package of Fortran-callable routines is described which allows programs to communicate with other programs, using a communications driver. The routines are available for both RSX and RT11 operating systems CDPACK Page 2 1.0 GENERAL PRINCIPLES OF INTER-PROCESSOR COMMUNICATION 3 _______ __________ __ _______________ _____________ 2.0 THE SUBROUTINE ARGUMENTS . . . . . . . . . . . . . . 4 ___ __________ _________ 3.0 THE SUBROUTINES . . . . . . . . . . . . . . . . . . 4 ___ ___________ 3.1 CDASGN(CHAN,DEV,UNIT,STAT) . . . . . . . . . . . . 4 3.2 CDOPEN(CHAN,RPTC,STAT) . . . . . . . . . . . . . . 5 3.3 CDCLOS(CHAN,RPTC,STAT) . . . . . . . . . . . . . . 5 3.4 CDXMTW(CHAN,XPTC,XBUF,XWC,STAT) . . . . . . . . . 5 3.5 CDXMT(CHAN,XPTC,XBUF,XWC,STAT) . . . . . . . . . . 6 3.6 CDRCVW(CHAN,RPTC,RBUF,MAXWC,STAT) . . . . . . . . 6 3.7 CDRCV(CHAN,RPTC,RBUF,MAXWC,STAT) . . . . . . . . . 6 3.8 CDSIGW(CHAN,XPTC,SIGNAL,STAT) . . . . . . . . . . 7 3.9 CDSIG(CHAN,XPTC,SIGNAL,STAT) . . . . . . . . . . . 7 3.10 CDWAIT(MBN) . . . . . . . . . . . . . . . . . . . 7 3.11 CDSTAT(MBN,INF,STAT) . . . . . . . . . . . . . . . 7 3.12 CDTMO(TIMVAL,TIMUNT) - RSX Only At Present . . . . 8 3.13 CDERRT(STAT,TXTBUF,BUFLEN,TXTLEN) . . . . . . . . 8 3.14 CDERRM(STAT,IERR) . . . . . . . . . . . . . . . . 9 3.15 CDERRN(STAT,ERNO) . . . . . . . . . . . . . . . . 9 4.0 ALTERNATE SUBROUTINES . . . . . . . . . . . . . . . 9 _________ ___________ 4.1 CDCHAN(CHAN) . . . . . . . . . . . . . . . . . . . 9 4.2 CDRCVP(RPTC) . . . . . . . . . . . . . . . . . . . 9 4.3 CDXMTP(XPTC) . . . . . . . . . . . . . . . . . . 10 4.4 CDRBUF(RBUF,MAXWC) . . . . . . . . . . . . . . . 10 4.5 CDXBUF(XBUF) . . . . . . . . . . . . . . . . . . 10 4.6 CDOUT(XWC,STAT) . . . . . . . . . . . . . . . . 10 4.7 CDOUTW(XWC,STAT) . . . . . . . . . . . . . . . . 10 4.8 CDIN(STAT) . . . . . . . . . . . . . . . . . . . 10 4.9 CDINW(STAT) . . . . . . . . . . . . . . . . . . 11 5.0 ROUTINES SPECIFIC TO EITHER RT11 OR RSX . . . . . 11 ________ ________ __ ______ ____ __ ___ 5.1 CDMODE(QRCV,QDOWN,SLEEP,RCVTMO) . . . . . . . . 11 5.2 CDUSER(RTNADD) . . . . . . . . . . . . . . . . . 12 5.3 RSX Specific Routines . . . . . . . . . . . . . 12 5.3.1 Effect Of CDSTAT QRCV Mode . . . . . . . . . . 13 5.3.2 CDKILL(CHAN,STAT) . . . . . . . . . . . . . . 13 5.3.3 CDREJ(MBN,STAT) . . . . . . . . . . . . . . . 13 5.3.4 CDWAKE(CHAN,STAT) . . . . . . . . . . . . . . 13 5.3.5 CDEFN(CHAN,EFN,STAT) . . . . . . . . . . . . . 13 5.3.6 CDSTOP . . . . . . . . . . . . . . . . . . . . 13 5.3.7 CDERRL(ERLUN) . . . . . . . . . . . . . . . . 14 5.3.8 CDGPTC(CHAN,MYPTC,STAT) . . . . . . . . . . . 14 5.4 RT11 Specific Routines . . . . . . . . . . . . . 14 6.0 ERROR AND STATUS RETURNS . . . . . . . . . . . . . 15 _____ ___ ______ _______ 6.1 Table Of Error Messages . . . . . . . . . . . . 15 _____ __ _____ ________ 6.2 Values Of The Status Block For RSX . . . . . . . 16 ______ __ ___ ______ _____ ___ ___ 6.3 Values Of The Status Block For RT11 . . . . . . 17 ______ __ ___ ______ _____ ___ ____ 6.4 Hardware Error Register . . . . . . . . . . . . 17 ________ _____ ________ 7.0 USING CDPACK - SPACE FOR EXTRA PTC'S, OVERLAYS . . 17 _____ ______ _ _____ ___ _____ ______ ________ 7.1 Warnings . . . . . . . . . . . . . . . . . . . . 18 8.0 EXAMPLES OF USING CDPACK ROUTINES . . . . . . . . 19 ________ __ _____ ______ ________ 8.1 Transmit A Message . . . . . . . . . . . . . . . 19 8.2 Receive A Message (Wait I/O) . . . . . . . . . . 19 8.3 Typical Receiver Code . . . . . . . . . . . . . 20 CDPACK Page 3 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 ______ ____ ____ communications 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 communications devices. For RSX systems an arbitrary number of packet type codes may be declared for each communications 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 communications 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 be sent. These are termed signals. They are transferred over the 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 communication devices, provided a different channel (or logical unit) is assigned to each different device. Although the basic CDPACK calls are identical for RSX and RT11 systems, since the communications driver implementations are different some time-dependent communications between programs can perform differently in the two systems. The only real difference between the RSX and RT implementations 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 communications device, otherwise the transmitter of the message will get an error. In an RSX system this is not necessary, since the arrival of a message initiates a 'wake-up' (AST) to the task which is the receiver of this type of messages. The task can then post the request to receive the message. However for most normal use of the package in an RSX system the same rules as for RT11 should apply and the receiver should normally have issued a call to CDRCV[W] before the transmitter initiates the transmission of a 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 been returned to the caller the message block data area is freed for re-use. CDPACK Page 4 2.0 THE SUBROUTINE ARGUMENTS ________ __________ _________ The arguments which are used throughout the description are explained below: ** NOTE ** All variables and constants are type INTEGER*2 CHAN A variable or constant giving the channel(RT) or logical unit number(RSX) to be assigned to the communication device required NOTE: under RT11 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 may choose 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 word aligned buffer of data to be transmitted XWC Number of words of data in XBUF to be tranmitted RBUF Address of a word aligned buffer to receive a message MAXWC Maximum number of words which may be received in RBUF STAT Address of a 2 word status block which will be filled with status information, when the transfer either completes or times-out. 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 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 device e.g. 'CD' UNIT Physical unit number of communications device e.g. for device CD0, the unit number is 0. 3.0 THE SUBROUTINES ________ ___________ The following routines are available for both RSX and RT systems. 3.1 CDASGN(CHAN,DEV,UNIT,STAT) Associates a channel(RT) or a logical unit(RSX) with the unit number UNIT of device DEV. This call must be made before any transfer calls can be made. CDPACK Page 5 Under RT-11, the first call to CDASGN also load 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 communications device STAT(1) < 0 see error tables at end 3.2 CDOPEN(CHAN,RPTC,STAT) Specify that the program wishes to RECEIVE messages with packet type code RPTC, arriving on the communications 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) < 0 see error tables at end An active message block is associated with each open connection. 3.3 CDCLOS(CHAN,RPTC,STAT) Specify 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) < 0 see error tables at end 3.4 CDXMTW(CHAN,XPTC,XBUF,XWC,STAT) Transmit XWC words of buffer XBUF with transmit Packet Type Code XPTC. Wait for completion, or timeout of the transfer before returning from the subroutine call. (No timeout is currently available under RT-11) Error returns: STAT(1) = 1 Message successfully transmitted STAT(2) contains the number of words CDPACK Page 6 transferred (XWC) STAT(1) < 0 see error tables at end 3.5 CDXMT(CHAN,XPTC,XBUF,XWC,STAT) Transmit XWC words of buffer XBUF with transmit Packet Type Code XPTC. Do not wait for the transfer to complete. 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) < 0 see error tables at end 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 words which can be received is MAXWC. Wait for completion of the operation, or optionally timeout(RSX only). Error returns: STAT(1) = 1 Message successfully received STAT(2) contains the number of words actually received STAT(1) < 0 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 words which can be received is MAXWC. Do not wait for the message to arrive, or a timeout to occur 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) < 0 see error tables at end CDPACK Page 7 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 or timeout before returning from subroutine call. Error returns: STAT(1) = 1 Signal successfully transmitted STAT(1) < 0 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) < 0 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 message blocks. No information is returned by the CDWAIT call, a call to CDSTAT 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. 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. CDPACK Page 8 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 or timed out as for CDXMTW 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 communications driver. Here the task 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. 3.12 CDTMO(TIMVAL,TIMUNT) - RSX Only At Present Set timeout value to be used on all data transmissions CDXMT[W], CDSIG[W] and also on receipt of messages with wait CDRCVW, if the timeout mode of transfer has been set up (see CDMODE). TIMUNT specifies the unit in which the timeout TIMVAL is to be counted 1= ticks,2=seconds,3=minutes,4=hours Any other value for TIMUNT is interpreted as ticks. If TIMVAL= 0 then no timeout will be used A default value of 5 seconds is used for a timeout if CDTMO is not called. 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 both RSX and RT11 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*2) CDPACK Page 9 TXTLEN = Integer*2 variable to receive the length (in bytes) of the text placed in array 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 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 - see routine CDERRL(ERLUN) to specify the logical 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. 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. 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 CDPACK Page 10 4.3 CDXMTP(XPTC) All future calls to CDOUT[W] now refer to transmit Packet Type Code XPTC 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 words. 4.5 CDXBUF(XBUF) All future messages transmitted via calls made to CDOUT will be from data buffer XBUF. 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.6 CDOUT(XWC,STAT) Transmit a message of length XWC 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 4.7 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.8 CDIN(STAT) Receive a message. The channel, receive Packet Type Code, receive buffer and maximum message size in 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. CDPACK Page 11 Error returns: as for CDRCV 4.9 CDINW(STAT) Receive a message. The channel, receive Packet Type Code, receive buffer and maximum message size in 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 5.0 ROUTINES SPECIFIC TO EITHER RT11 OR RSX _____________ ________ __ ______ ____ __ ___ Also included in this section are common routines whose interpretation is slightly different on the two 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. This will make the 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 QDOWN logical argument (RSX only at present) 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 CDPACK Page 12 SLEEP logical argument (not applicable for RT11) If TRUE then on the next receive or transmit request the communications driver will be asked to detach from the interrupts of the communications device ** 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 If TRUE then a receive message request, in a wait call will have a timeout set up for its completion ** Default** FALSE An argument which is not used may be omitted e.g. CALL CDMODE(,,,RCVTMO) 5.2 CDUSER(RTNADD) Sets up the address of a user completion routine(RT11) or AST(RSX) to be called when a CDXMT or CDRCV completes. For RSX this completion routine will also be called when a signal arrives. RTNADD is a variable containing the address of the user completion routine. A call to CDUSER with RTNADD=0 will cancel users completion routine being specified on further calls to CDPACK. NOTE: This feature must be used with care. A user AST or completion routine must be written in Macro. CDPACK routines may be called from completion routine/AST level. However CDSTAT must still be called to declare the message block no longer active. After a call to CDUSER has been made all subsequent CDRCV, CDOPEN or CDXMT calls will on completion, or signal arrival cause this routine to be entered. This is true even if a subsequent call to CDUSER has been made to either zero or change the routine address. It is the address currently specified at the time of issuing the CDRCV,CDOPEN or CDXMT which determines whether a completion routine/AST will be called. 5.3 RSX Specific Routines CDPACK Page 13 5.3.1 Effect Of CDSTAT 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.3.2 CDKILL(CHAN,STAT) - Cancel all outstanding I/O requests on this channel. Error returns: see table of error returns at end 5.3.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.3.4 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 5.3.5 CDEFN(CHAN,EFN,STAT) - Specify a local event flag EFN to be set when either a transfer on channel CHAN completes or times out, or when a message or signal arrives on any one of the open connection associated with channel CHAN. This enables a program to wait on the logical 'OR' of several events; one or more of which may be link activity. Error returns: see error tables at end 5.3.6 CDSTOP - Same as CDWAIT but puts the task in the stop state if there is no outstanding I/O. NOTE: Routines CDKILL,CDREJ,CDWAKE,CDEFN and CDSTOP are not yet available. CDPACK Page 14 5.3.7 CDERRL(ERLUN) - Specifies that error messages output using routine CDERRM should be written out on logical unit ERLUN. - no error returns from this routine. CDERRM gives the system error message on the write to this logical unit. Default value for this logical unit number is 5. 5.3.8 CDGPTC(CHAN,MYPTC,STAT) - Routine called by a task 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 Variable MYPTC. error returns: see table of error returns at end 5.4 RT11 Specific Routines ----- to be added ------- CDPACK Page 15 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 communications device 3 Channel can not be assigned to communications device 4 Maximum number of open sessions or message blocks exceeded 5 Communication driver not resident 6 Invalid channel number 7 Invalid communication device or unit 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 CDPACK Page 16 6.2 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 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.CNR) 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) error register 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) CDXMT[W],CDRCV[W],CDSIG[W] 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 -93 (IE.EME) CDXMT[W] 30 -110 (IE.SNA) CDSIG[W] CDPACK Page 17 6.3 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 transfer WC 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.4 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 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. If the program is overlaid it is important that the common CDCM82 reside in the root segment. CDPACK Page 18 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) 18 + 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 7.1 Warnings 1. you should not mix Wait and no-wait CDRCV's on the same channel in RSX systems, if you are using the normal 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 must be written in Macro. CDPACK Page 19 8.0 EXAMPLES OF USING CDPACK ROUTINES _____________ __ _____ ______ ________ 8.1 Transmit A Message DIMENSION ISTAT(2) C C assign channel to communications device 'CD' unit 0 C for RSX CHAN must be a suitable number for a logical unit C number before calling CDASGN. For 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 communications 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) ..... ..... 8.2 Receive A Message (Wait I/O) DIMENSION ISTAT(2) C C assign channel to communications device 'CD' unit 1 C for RSX CHAN must be a suitable number for a logical unit C number before calling CDASGN. For 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 communications 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 CDPACK Page 20 CALL CDERRM(ISTAT,IERR) ...other error handling C C Wait for message to arrive C 20 CALL CDRCVW(CHAN,RPTC,BUF,MAXLEN,ISTAT) !receive message IF(ISTAT(1).NE.1) CALL CDERRM(ISTAT,IERR) .... .... 8.3 Typical Receiver Code DIMENSION ISTAT(2),IMBN(2) C C assign channel to communications device 'CD' unit 0 C for RSX CHAN must be a suitable number for a logical unit C number before calling CDASGN. For 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,BUF,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 CDPACK Page 21 20 GOTO( , , , ,...) INF !decide what has happened ..... ......