![[SLAC Controls Department]](/grp/cd/soft/images/logo_cd.gif){kind=logo}
![[SLAC Home Page]](/grp/cd/soft/images/logo_slac.gif){kind=logo}
7.1 INTRODUCTION . . . . . . . . . . . . . . . . . . . 7-1
7.2 MESSAGE CLASSES . . . . . . . . . . . . . . . . . 7-1
7.2.1 Asynchronous Messages . . . . . . . . . . . . . 7-2
7.2.2 Synchronous Messages . . . . . . . . . . . . . . 7-4
7.3 VMS SOFTWARE FOR ASYNCHRONOUS MESSAGES . . . . . . 7-5
7.3.1 MSG_SYNC . . . . . . . . . . . . . . . . . . . . 7-5
7.3.2 MSG_ONE . . . . . . . . . . . . . . . . . . . . 7-6
7.3.3 MSG_SEND . . . . . . . . . . . . . . . . . . . . 7-8
7.3.4 MSG_WAIT . . . . . . . . . . . . . . . . . . . 7-10
7.3.5 Additional Special Purpose Routines . . . . . 7-11
7.3.5.1 MSG_ESEND . . . . . . . . . . . . . . . . . 7-11
7.3.5.2 MSG_INIT . . . . . . . . . . . . . . . . . . 7-12
7.4 IRMX SOFTWARE FOR ASYNCHRONOUS MESSAGES . . . . 7-12
7.4.1 Receiving Messages From The VAX . . . . . . . 7-13
7.4.2 MSG_INIT . . . . . . . . . . . . . . . . . . . 7-13
7.4.3 MICRO_MBX . . . . . . . . . . . . . . . . . . 7-14
7.4.4 MMSG_SEND . . . . . . . . . . . . . . . . . . 7-14
7.4.5 Error Messages . . . . . . . . . . . . . . . . 7-17
7.5 USE OF ASYNCHRONOUS MESSAGES . . . . . . . . . . 7-17
7.5.1 Sample Function Codes . . . . . . . . . . . . 7-17
7.5.2 Example (Magnets) . . . . . . . . . . . . . . 7-21
7.6 USE OF SYNCHRONOUS MESSAGES . . . . . . . . . . 7-22
7.6.1 MPG_SYNC . . . . . . . . . . . . . . . . . . . 7-23
7.6.2 MPG_WAIT . . . . . . . . . . . . . . . . . . . 7-24
7.6.3 MPG_SET . . . . . . . . . . . . . . . . . . . 7-25
7.6.4 Example (BPM's) . . . . . . . . . . . . . . . 7-26
7.6.5 Ground Rules . . . . . . . . . . . . . . . . . 7-29 CHAPTER 7 MESSAGE COMMUNICATIONS IN SLC
7.1 INTRODUCTION Communication among processes in the SLC system falls roughly into two broad categories; database reads and writes, and direct messages. Philosophically, the database is used to represent the static state of the machine, while the message services are used to convey more transient data. For example, the database stores information on the states of the magnets, while messages are used to convey beam position data for a single pulse. In addition, messages are used to convey commands to the micro and command completion responses back to the VAX.
7.2 MESSAGE CLASSES Messages themselves fall into two categories: asynchronous messages which are transmitted over the cable network (or over mailboxes for messages within a single physical CPU), and synchronous messages which are transmitted over a dedicated subchannel of the communications cable.
MESSAGE COMMUNICATIONS IN SLC Page 7-27.2.1 Asynchronous Messages Asynchronous messages are used to transmit commands to the micros and command completion status back to the originating process. Other uses for the asynchronous messages are the transmission of data to the error logger, transmission of fault data from a micro to the Feedback process, and presumably many others yet unimagined. All asynchronous messages have a simple structure consisting of ten words of header information followed by up to 502 words of data: SOURCE Originator of message (4 bytes Ascii) DEST Destination thereof (4 bytes Ascii) T STMP Time stamp (8 byte VMS standard) FUNC The function code (I*2) DLEN Length of Data (I*2) data . . data o SOURCE and DEST are 4 byte Ascii strings containing either a Micro name, e.g. 'LI00', or for VAX processes, the string 'Vxxx' where xxx identifies an individual SCP or PARANOIA. By convention, xxx indicates the SLCNET interrupt id to handle this message. For internal VAX messages, the string contains a mailbox identifier.
MESSAGE COMMUNICATIONS IN SLC Page 7-3 o FUNC is a 2-byte code indicating the function to be performed. The high order byte gives routing information, e.g. to the magnet task or the BPM task in the micro. In general, the micros send a response message back to the VAX process which requested a command after the command has been completed. The highest bit of the function code is reserved to indicate a response message, so that by convention all response function codes are the same as the command function code with the response bit turned on. The low order byte gives specific command information, e.g. calibrate or trim commands to the micro magnet task. The highest bit of this byte is reserved to indicate TERSE commands, e.g. for a magnet check command, the terse bit indicates that the database will not be updated unless an error status is detected. All function codes are defined in the include files MSGFUNC and xxxFUNC where xxx is an abbreviation for some facility, e.g., BPMFUNC. o DLEN is an I*2 word indicating the number of words of data to follow. DLEN is considered part of the header and not counted in the data length. The sector micros maintain a queue of message blocks to execute. This queue is fed from two sources: o Asynchronous messages delivered over the network or sent by another subjob in the micro with destination SELF. These messages are received by a message server task in the micro and relayed to the mailbox of the task indicated by the code
MESSAGE COMMUNICATIONS IN SLC Page 7-4 in the high order byte of FUNC. Some messages may also be serviced by the message task directly. o Trickle-down messages from the pattern interrupt service routines which have been previously "created" by a correspondence command or other internal messages between tasks. These messages are passed in standard message format to the appropriate task's mailbox by the originating task.7.2.2 Synchronous Messages The synchronous messages are broadcast by the MPG to all sector micros at a rate of 360 hertz (although currently, and for the forseeable future, every other message is null). The message is fixed-format, consisting of two one-byte fields. The first (PP) is the pattern code. It is used by each micro to configure the machine for the next pulse. Each possible beam, including null and standby beams, are assigned a unique pattern. The linac sector micros will use PP to index a CAMAC package and write it to the hardware. In general, the operation will be the loading of Programmable Delay Units (PDU's) with the appropriate delay times for a particular beam. The second byte (YY) is a (dynamically programmable) micro command code. It is used to request a set of micros to synchronously perform some function, typically a read of the Beam Position Monitors.
MESSAGE COMMUNICATIONS IN SLC Page 7-57.3 VMS SOFTWARE FOR ASYNCHRONOUS MESSAGES All routines are Integer*4 functions which return an error status to the calling routine. These error codes are standard VMS format error codes which can be tested by ERR_SEND. Errors associated with these routines are sent to Paranoia where possible and otherwise indicated by COWRITE messages.
7.3.1 MSG_SYNC MSG_SYNC(msg_func, micro_list, timeout, msg_dlen, data, co_routine) MSG_SYNC constructs and sends a message to one or more micros and waits for the reponse message(s) before returning. MSG_SYNC calls MSG_SEND and (if MSG_SEND was successful in reaching at least one micro) MSG_WAIT (both described below) to do the send(s) and receive(s), respectively. This routine should be sufficient for most user applications. o "msg_func" is the I*2 function code to be executed. MSG_SYNC calls MSG_SEND with the msg_func supplied; it calls MSG_WAIT with function code of msg_func ORed with the response bit ('8000'X). o "micro_list" specifies where the message is to be sent. The destination can be a set of micros coded as a micro_list, a standard database type list with two header words followed by a list of Ascii micro names (e.g. LI01). Alternatively, it can be a single 4 byte Ascii micro name (detected by the high order byte of the 2nd word being non-zero).
MESSAGE COMMUNICATIONS IN SLC Page 7-6 o "timeout" is the I*4 maximum number of milliseconds the program is willing to wait for MSG_WAIT to complete. The call to MSG_SYNC, however, may take longer than timeout milliseconds to complete. o "msg_dlen" and "data" are optional arguments specifying the I*2 length in words and data to be included in the message to be sent. If omitted the data length is zero. o "co_routine" is an optional address of an I*4 function to be called as each read completes. The co-routine will be called with arguments (header,data) to pass the header and data from the message to the routine. The function should return a true value if the message read in was in fact one that the caller of MSG_SYNC was waiting for, and should return a false value otherwise. (Any co_routine which is coded as an argument to MSG_SYNC need only always return a true value, but see the description of MSG_WAIT below.) If coded, co_routine should be declared EXTERNAL in the calling program.7.3.2 MSG_ONE MSG_ONE(msg_func,microname,timeout,out_dlen,out_data,in_maxlen,in_msg) is a near-relative of MSG_SYNC, suitable for transactions involving a single micro. MSG_ONE has no co-routine argument (instead, incoming data will be copied to the user-supplied buffer "in_msg"). It is thus more self-contained than MSG_SYNC and (depending on your taste) possibly easier to use. MSG_ONE has the added attraction that it can
MESSAGE COMMUNICATIONS IN SLC Page 7-7 be used to receive long messages, i.e., messages with data length greater than the the usual limit of (NETMSGLEN-NETHEADERLEN) = 502 words. The micro message is actually sent in blocks, which are re-assembled by the MSG_ONE co-routine transparently to the caller. The arguments correspond closely to those of MSG_SYNC, namely: o "msg_func" is the same as for MSG_SYNC o "microname" is the four-byte ascii microname of the micro to be addressed. MSG_ONE will NOT take a micro-list for this argument. o "timeout" (I*4) is the number of milliseconds MSG_ONE will wait for a response from the micro o "out_dlen" (I*2) is the number of words of data in the out-going message to "microname" o "out_data" is the address of the buffer containing the data to be send o "in_maxlen" (I*2) is the length, in words, of the caller's buffer which is to receive the incoming message. It must be large enough to accomodate both the incoming data and NETHEADERLEN words of header. o "in_msg" is the address of the caller's buffer, into which the incoming message (header followed by data) will be copied.
MESSAGE COMMUNICATIONS IN SLC Page 7-8 Note that the entire message (header followed by data) will be copied to "in_msg". It is therefore advisable for routines invoking MSG_ONE to include NETPARM, which defines the parameter NETHEADERLEN: the number of header words which precede the data in a message. Routines needing to access parts of the header (e.g., DLEN) should also include MSGSTRUC. In addition to the status codes returned by MSG_SYNC, MSG_ONE may also return MSG_TRUNC (warning) if the incoming message was too long for the caller's buffer7.3.3 MSG_SEND MSG_SEND( msg_func, micro_list, msg_dlen, data) constructs and sends a message to a specified destination. MSG_SEND determines the appropriate routing for a message; internal VAX messages use MAILBOX facilities and external messages use SLCNET. The SLCNET messages are sent with an asynchronous write to the micros but the routine MSG_SEND waits for the write to complete before returning. The internal SLCNET timeout avoids hangups. o "msg_func" is the I*2 function code to be executed. The symbolic definition of the function codes, as well as the header pointers, etc., is found in the include file MSGFUNC or in the include files for the individual facilities which are listed there.
MESSAGE COMMUNICATIONS IN SLC Page 7-9 o "micro_list" specifies where the message is to be sent. The destination can be a set of micros coded as a micro_list, a standard database-type list with two header words followed by a list of Ascii micro names (e.g. LI01). Alternatively, it can be a single 4 byte Ascii micro name (detected by the high order byte of the 2nd word being non-zero). For sending messages to other VAX processes, the destination identifies an associated mailbox. o "msg_dlen" and "data" are arguments specifying the I*2 length in words and data to be included in the message. The arguments are optional and if not coded, the data length is 0. The following error codes may be returned by MSG_SEND: o MSG_OKOK (success) No problems of any kind o MSG_NULLRQST (warning) MSG_SEND was called with a null MICRO_LIST o MSG_NO_SUCH_SCP (warning) Requested VAX process destination doesn't exist o MSG_NO_SUCH_MICRO (warning) Requested micro destination does not exist (in this case MSG_SEND will still attempt to write to any other micros in the list) o MSG_NETWRIT (error) Network error in attempting to write to a micro
MESSAGE COMMUNICATIONS IN SLC Page 7-10 o MSG_OFFLINE (error) Micro is not online so network write was not attempted (note this check is not made for stand-alone programs; in this case MSG_SEND will attempt to write to the micro) o MSG_NOSEND (error) MSG_SEND was unable to write successfully to any of the requested destinations7.3.4 MSG_WAIT MSG_WAIT(msg_func, micro_list, timeout, co_routine) waits for a response to msg_func from the micros specified in micro_list. Messages with incorrect function codes or from incorrect micros produce a log-only warning message, but MSG_WAIT will continue to wait for correct responses until timeout. It is the responsibility of the user to synchronize calls to MSG_SEND and MSG_WAIT so that desired response messages are not lost. At least two precautions must be taken: the value of "timeout" in the call to MSG_WAIT must be appropriate to the request, and no call to MSG_WAIT should be made without a preceding call to MSG_SEND. Two calls to MSG_WAIT (or a call to MSG_SYNC followed by a call to MSG_WAIT) with no intervening MSG_SEND will cause the messages expected by the second MSG_WAIT to be lost. o "msg_func" is the I*2 function code for which a response is desired Where more than one code should be accepted, the hex code FF can be substituted for either byte as a wild card.
MESSAGE COMMUNICATIONS IN SLC Page 7-11 o "micro_list" is the list of one or more Ascii micro names as specified for MSG_SEND. o "timeout" is the I*4 maximum number of milliseconds the program is willing to wait for completion. o "co_routine" is the optional address of an I*4 function to be called as each read completes. As in the MSG_SYNC co_routine argument, "co_routine" should return a true value if the message was expected; false otherwise. However, since MSG_WAIT may be called with wild cards in the function code argument, it is possible that a message will creep in with an unwanted function code. In this case the false returned value from the co_routine will let MSG_WAIT know to keep waiting.7.3.5 Additional Special Purpose Routines There are two additional routines supplied by the message service which are not normally called from SCP user code.
7.3.5.1 MSG_ESEND - MSG_ESEND(msg_func,micro_list,msg_dlen,data) is a special-purpose version of MSG_SEND called only by ERR_SEND (see following chapter "Error Messages"). MSG_ESEND exists so that MSG_SEND may report network problems to Paranoia without having to call itself. MSG_ESEND sends internal VAX messages to Paranoia's mailbox. Its arguments have the same meaning as in MSG_SEND above,
MESSAGE COMMUNICATIONS IN SLC Page 7-12 but MICRO_LIST should always identify Paranoia's mailbox.7.3.5.2 MSG_INIT - MSG_INIT(GET_MBX) does all necessary initialization for the Message Service. Stand-alone programs using the message service (including indirect use, as through transparent camac) must call MSG_INIT before calling any other Message Service routines. Most users will find it convenient to call the routine STANDALONE_INIT rather than calling MSG_INIT directly. STANDALONE_INIT calls MSG_INIT and does other initialization necessary for stand-alone programs using the network. GET_MBX is a LOGICAL*1 input argument which is optional. If omitted or if coded .TRUE. MSG_INIT will create a mailbox for the process to receive incoming messages from other VAX processes as well as from SLCNET micros. The only status codes returned by MSG_INIT are MSG_OKOK if the initialization was successful, or MSG_CANTINIT if it wasn't. In the latter case no further Message Service requests from the process will be attempted.
7.4 IRMX SOFTWARE FOR ASYNCHRONOUS MESSAGES All routines are Integer*4 functions which return an error status to the calling routine. These error codes are standard VMS format error codes which can be tested by ERR_SEND.
MESSAGE COMMUNICATIONS IN SLC Page 7-137.4.1 Receiving Messages From The VAX Micro functions sharing the same high order byte of the function code are grouped in a job in the micro. The main routine of the main task of each job sets the variable TASK_ID in the common block MSG_MAIL to the high order function code it wishes to service. It calls the micro version of MSG_INIT, then performs any desired initialization and calls MICRO_MBX to wait for a message. When a message is received, MICRO_MBX copies it into the common block, MSG_MAIL, and returns. The main then calls its own driver routine to implement the low order byte of the function code. The driver routine gets the message from the common block by including the file SLCRMX:MSGMAIL.INC. The driver routine is responsible for all database updates and message responses to the VAX. When the driver routine returns, the main routine again calls MICRO_MBX to wait at the mailbox for further input. A sample main routine can be found in the file SLCRMX:TASKMAIN.F86.
7.4.2 MSG_INIT MSG_INIT(ascii-name) does initialization for the Message Service in each job. "ascii-name" is a four-character descriptive name for the subjob making the call. For example, the call to MSG_INIT in the BPMO subjob is ISS=MSG_INIT(4HBPMO) MSG_INIT gets a token for a mailbox for incoming messages, gets a SLCNET port for sending out-going messages, and gets its own job token. It then stores all the tokens and the ascii name in the common block MSG_GLOBAL. It also catalogs the main task as Name//'Task' so
MESSAGE COMMUNICATIONS IN SLC Page 7-14 that it may be identified by the MD86 debugger. (MSG_GLOBAL is initialized by a single call to the routine MSG_GLINIT by the root job.)7.4.3 MICRO_MBX MICRO_MBX(timeout) handles the actual message input in each task. "timeout" is an I*2 argument which is the number of hundredths of a second MICRO_MBX should wait at the mailbox before giving up. A timeout of #FFFFH means to wait indefinitely. MICRO_MBX will return when a message is received or when the timeout expires, whichever occurs first. When it receives a token for a segment containing a message, it copies the message into the common block MSG_MAIL. If the message is not an internal communication between jobs, it then deletes the token for the segment before returning. If the timeout expires before a message is received, the SOURCE field of MSG_MAIL is set to V017 (Paranoia) and the low order byte of the function code is cleared before returning.
7.4.4 MMSG_SEND MMSG_SEND(msg_func,destination,dlen,mmsg_buf,msg_mail) constructs and sends a message to a specified destination. MMSG_SEND will timeout and return an error status if the message is not accepted
MESSAGE COMMUNICATIONS IN SLC Page 7-15 by its destination VMS process within a reasonable time. This timeout is internal to MMSG_SEND and is currently 7 seconds. o "msg_func" is the I*2 function code to be executed. For most messages sent by a micro, this function is the Function code requested plus the Response bit. o "destination" is an I*4 (Ascii) variable specifying where the message is to be sent. Its value may be of the form Vxxx where xxx indicates the interrupt id to be used in the network write from the micro to a VAX process, or it may have the special values RESP or SELF. (Note that Fortran86 does NOT process string constants used as actual arguments as one might expect: such constants are passed as character strings rather than numeric variables. To pass an argument of RESP or SELF initialize an I*4 variable in a DATA statement using a Hollerith constant or pass a constant in Hollerith rather than string format;e.g., 4HSELF.) If Destination is specified as SELF, the message is sent to the mailbox of the task indicated by the high order byte of the function code. This is used for task to task communication within a micro. If Destination is specified as RESP, the message is sent to the process given by the Source field of the originating message in the common block MSGMAIL. In addition, the response bit is automatically added to the function code. o "dlen" is an I*2 argument specifying the length (in words) of the data to be included in the message. In most circumstances, dlen may be no larger than (NETMSGLEN-NETHEADERLEN) = 502 words, but if the message is
MESSAGE COMMUNICATIONS IN SLC Page 7-16 to be sent to a Vax process which will receive it via a call to MSG_ONE, dlen may be arbitrarily large. MMSG_SEND will break up the caller's data into blocks and send them one by one to the Vax process. MMSG_SEND will not return until all blocks are sent. In iRMX, the arguments must be specified, but no data will be transferred if dlen is 0. o "mmsg_buf" is the I*2 buffer used to contain the out-going message. The caller is responsible for putting the data in MMSG_BUF, starting with word NETHEADERLEN+1. The first NETHEADERLEN (currently 10) words are over-written by MMSG_SEND with the Message Service header, so it is important that they contain nothing of further interest either to the caller or to MMSG_SEND itself. In particular, this argument should NOT be the same as the msg_mail argument. MMSG_SEND will not disturb the data portion of mmsg_buf. o "msg_mail" is the buffer containing the most recent incoming message for the job (see description of MICRO_MBX above). Routines invoking MMSG_SEND should include the file SLCRMX:MSGMAIL.INC so that the buffer msg_mail is properly defined. The msg_mail argument is used by MMSG_SEND to determine the context from which it was called; in particular, which job is calling it and which VAX process to send return messages to. Therefore it is vital that msg_mail be passed to MMSG_SEND with its header (or at least the SOURCE and FUNC fields) intact. For the same reason, the caller must not use msg_mail for the fourth (mmsg_buf) argument.
MESSAGE COMMUNICATIONS IN SLC Page 7-177.4.5 Error Messages All error messages are handled by a utility routine ERR_SEND whose arguments include a VMS format error code, an argument count, and up to 8 arguments. ISS=ERR_SEND(vmscode,arg1,...,arg8,nargs)
7.5 USE OF ASYNCHRONOUS MESSAGES
7.5.1 Sample Function Codes 1. Network Database Requests The following example is not currently implemented, but might be useful as a diagnostic tool. NETMSG_REQUEST NETMSG_REQUEST + RESPONSE Data: Clist Data: Dlist This command causes a micro to construct a data block as specified by the Clist. The Clist is identical to that produced by DBLIST. The micro then sends a message back to the NETMSG_REQUEST Source with a function code of NETMSG_REQUEST+RESPONSE and data Dlist. The Dlist is the data specified by Clist and is precisely the format that would be produced by DBLGET. (Note: Real variables will be returned correctly in VMS format.)
MESSAGE COMMUNICATIONS IN SLC Page 7-18 2. Magnet Control Functions MAG_CALB, MAG_STDZ, MAG_TRIM, Mag_func + RESPONSE MAG_PTRB, MAG_CHCK, MAG_RSET, MAG_ZERO [+ TERSE] Data: none Data: VMS status code These commands instruct the micro magnet task to perform the specified function on all appropriate magnets. The database is updated unless the TERSE bit has also been specified for MAG_CHECK or MAG_PTRB (TERSE is not used with the other commands). If TERSE is specified, the database will only be updated if an error status has been detected. After the database has been updated, the magnet task sends a Mag_func+RESPONSE message to the Source, including error status information as data. 3. Camac Functions CAMAC_REQUEST CAMAC_REQUEST + RESPONSE Data: ..... Data: Return status ..... ..... This command instructs the micro Camac task to execute the instructions in the package prepared by appropriate calls to CAMIO, CAMALO, CAMADD etc. When the Camac function has been performed the task sends a response message to the Source containing the Status returned by the Camac operation, and data if requested. The details of the data transferred are decribed in the Camac chapter of the Principles of Operation
MESSAGE COMMUNICATIONS IN SLC Page 7-19 Manual. 4. Error messages ERROR_MSG [+ RESPONSE from iRMX] Data: Msg code Destination Number of arguments Argument list This command sends an error message to Paranoia using a reserved SLCNET interrupt_id and VMS mailbox. Depending on the severity code, Paranoia will log the message and perform appropriate actions. For errors signalled by the Micro, the message will be broadcast by Paranoia to the Source of the command which was being executed when the error was detected. 5. Analog Status Functions ANALOG_CHECK [+ TERSE] ANALOG_CHECK + RESPONSE Data: none Data: VMS status code This command instructs the micro analog status task to read all analog status modules and update appropriate status flags and data. If TERSE is specified, the database will be updated only if at least one status is bad. Otherwise, the database will be updated unconditionally. After the database has been updated, the analog status task sends a ANALOG_CHECK+RESPONSE message to the Source, including error status information as data.
MESSAGE COMMUNICATIONS IN SLC Page 7-20 6. Digital Status Functions DSTAT_CHANGE DSTAT_CHANGE + RESPONSE Data: Number of units Data: VMS status code DOPU unit number Output bit Desired state Next DOPU . . . This command instructs the micro to change the state of the output bit(s) specified to the desired state(s). When completed the task sends a command response message back to the Source including status information as data. The database will be updated. DSTAT_CHECK [+ TERSE] DSTAT_CHECK + RESPONSE Data: none Data: VMS status code This command instructs the micro digital status task to check all digital status modules. If TERSE is specified, the database will be updated only if something has changed since the last check. Otherwise, the database will be upda ted unconditionally. After the database has been updated, the digital status task sends a DSTAT_CHECK+RESPONSE message to the Source, including error status information as data.
MESSAGE COMMUNICATIONS IN SLC Page 7-217.5.2 Example (Magnets) To request a magnet check function from a list of micros, MICRO_LIST, the SCP must first call MSG_SEND. There is no data for a magnet check command, so the DLEN and DATA arguments need not be coded. The SCP then waits for completion from the micros. Since the SCP is not expecting data on the response messages and does not want to do anything with the possible error status returns, it does not need to declare a co_routine. ISS=MSG_SYNC(MGNT_CHECK,MICRO_LIST,TIMEOUT) The SCP can then test ISS to detect a Timeout or other network error. The SCP now knows that the database has new magnet information and may proceed to generate a display or whatever else it wishes. When the micro receives the message containing the magnet check command, the message task reads the high order byte of the message code to determine which micro task should service the message, and sends the message on to the mailbox of the magnet task. The main loop of the magnet task waits at the mailbox for a message to be received, copies the message into the common block MSGMAIL, and then calls MAGCNTL. CALL MAGCNTL MAGCNTL uses the low order byte of the message code to determine which control function to execute, and the appropriate subroutine is called. For magnet functions, there is no relevant data. When finished it will send a database update to DBEX since TERSE was not specified, and then call MMSG_SEND to send the completion response to the SCP,
MESSAGE COMMUNICATIONS IN SLC Page 7-22 including an I*4 word of VMS status information as data. ISS=MMSG_SEND(MGNT_CHECK+RESPONSE,source,2,status) MAGCNTL then returns to the main loop of the task to wait for a new magnet request message.7.6 USE OF SYNCHRONOUS MESSAGES Any operation involving a synchronous message also requires several asynchronous messages. Suppose a SCP wants to use synchronous messages to cause one or more micros to perform a synchronized activity. The usual sequence is as follows: 1. The SCP sends a preparation request to each of the affected micros. The data in the request includes the particular YY's to be subsequently broadcast by the MPG. The micros satisfy the request by making appropriate associations between the YY's and a sequence of actions. These actions may include doing some camac, processing data, and sending a reply back to the SCP. The SCP waits for acknowledgement from the micros that preparation is complete before proceeding to the next step. 2. The SCP sends a request to the MPG to broadcast the YY's, possibly only in the company of a particular PP or on a particular time-slot.
MESSAGE COMMUNICATIONS IN SLC Page 7-23 3. The MPG sends acknowledgement back to the SCP that the request has been received and is valid. 4. The YY's are broadcast by the MPG. 5. The YY's are seen by the micros; the actions which have been prepared are taken. 6. When the requested synchronized activity is complete (this may involve several iterations of steps 2-5) the micros send a response, possibly including data, to the SCP making the original preparation request. 7. At an appropriate time (e.g., when the SCP ceases being interested in that particular set of micros, or when the SCP is about to exit) the SCP asks the sector micros to clear all associations with the YY's it has been using. Special Message Service routines exist to facilitate those parts of such operations which involve the MPG. All are I*4 functions which return a VMS error status.7.6.1 MPG_SYNC MPG_SYNC(msg_func, micro_list, timeout, mpg_dlen, data, co_routine) sends a request to the MPG that the specified YY's be broadcast, and then waits for the acknowledgement from the MPG and the data returned from the micros in "micro_list".
MESSAGE COMMUNICATIONS IN SLC Page 7-24 o "msg_func" should be the function code expected in the reply messages from the micros in "micro_list" (but the response bit need not be set; MPG_SYNC will set it in any case). The function code used in the message sent to the MPG is fixed (it's always MPG_YYREQ) and so is not supplied to MPG_SYNC through an argument. o "micro_list" is a list containing all sector micros from whom a response is expected. It should NOT include the MPG; it is understood that MPG_SYNC will always wait for a response from the MPG (with function code MPG_YYREQ + RESPONSE). le;"mpg_dlen" is the length in words of the data to be sent to the MPG. le;"data" is the address of a buffer containing data to be sent to the MPG. "data" should be declared as an array of bytes. The first byte is the number NPULSE of pulses on which specific YY's are being requested. The second byte is always zero. The remainder of the message consists of NPULSE triplets of bytes, each of the form (ts,pp,yy). o "co_routine" is the name of a routine to process data in the return messages. See the co-routine argument description for MSG_SYNC above.7.6.2 MPG_WAIT MPG_WAIT(msg_func, micro_list, timeout, co_routine) waits for a response of "msg_func" from the sector micros specified in
MESSAGE COMMUNICATIONS IN SLC Page 7-25 "micro_list", and also waits for a response from the MPG with function code MPG+YYREQ + RESPONSE. This routine is called by MPG_SYNC; it is unlikely that other users will need to call it directly. o "msg_func" is the same as in MPG_SYNC above, except here the exact function code expected, including response bit, must be supplied. o "micro_list" is the same as the micro_list argument for MPG_SYNC described above. In particular, the MPG should NOT be included in "micro_list". o "timeout" is the same as the timeout argument in MPG_SYNC. o "co_routine" is also the same as in MPG_SYNC.7.6.3 MPG_SET MPG_SET(mpg) is a service routine which changes the MPG to be addressed in the other MPG_... routines. Normally this MPG will be MP00, but for software being used on the development system it is necessary to change this to MP01. Currently this can be done from the BPMO development panel. "mpg" is the four-byte ascii name of the MPG to be addressed in future MPG requests. It may be only MP01 or MP00; MPG_SET will return an error if any other value is supplied.
MESSAGE COMMUNICATIONS IN SLC Page 7-267.6.4 Example (BPM's) Here we walk through the steps involved when a SCP wishes to obtain BPM measurement data from a single sector micro, say LI01. We assume the data are to be used in a display which will be updated periodically and indefinitely (until someone turns it off). 1. The SCP sends a request to LI01 (function code BPMO_MEAS_PREP) to make associations for two YY's. The data in this request includes the YY's and timing information. The micro preparations are handled by the BPMO subjob. They include preparing two CAMAC packages, preparing a "trickle-down" message to contain the data from second (BPM read) camac package, and asking the timing subjob to store the tokens for the camac packages in its array YY_SEGMENT. The header for the trickle-down message is largely copied from the header of the BPMO_MEAS_PREP request message (except the function code is set to BPMO_MEAS_PROC). In this way, LI01 will know who the requesting SCP was when it processes the data acquired from the broadcast of the YY's. Finally LI01 sends a message with function code BPMO_MEAS_PREP + RESPONSE, data one longword of status. 2. The SCP then invokes MPG_SYNC as follows: ISS=MPG_SYNC(BPMO_MEAS_PROC,'LI00',dlen,data,BPMREAD) where the data consists of one word (COUNT) followed by several bytes, e.g. COUNT (# of YY's to be broadcast, here 2) PP1
MESSAGE COMMUNICATIONS IN SLC Page 7-27 TS1 YY1 (YY used to load timing device in LI01) PP2 TS2 YY2 (YY used to read the BPM data in LI01) where PP1=PP2 is the beam number and TS1=TS2 is the time slot selected from the BPMO panel by the operator and YY1,YY2 (not equal) are determined by the operation requested (here measurement in the linac) and the SCP_ID of the requestor. In this case "dlen" would be 4. MPG_SYNC first does a MSG_SEND to the MPG with the above data; then calls MPG_WAIT to wait for responses from both the MPG and LI01. It is necessary to wait for both at once. Because of the vagaries of the SLCNET poll-list there is no guarantee that the MPG's acknowledgement will be processed by the SCP before the response from LI01. (Also, with the present organization of the Message Service, it is not possible for a MSG_WAIT to immediately follow another MSG_WAIT or a MSG_SYNC.) 3. The MPG sends a message back to the requesting SCP with function code MPG_YYREQ+ RESPONSE. This is done before the YY's have actually been broadcast. But the time at which the SCP reads the MPG response message may be before or after the broadcast.
MESSAGE COMMUNICATIONS IN SLC Page 7-28 4. When the appropriate PP,TS combinations come up the MPG broadcasts the YY's. In fact they may never be broadcast if the requested PP-TS combination doesn't come up; the MPG as currently structured does not know in advance which combinations it will be broadcasting. 5. The first YY is seen by the micro. The timing subjob causes the associated camac package (loading PDU's) to be executed. The second YY is seen. Again Timing sends off the prepared camac package, this time a read of the BPM's. The data buffer for the camac is part of the data field in the previously prepared trickle-down message. The timing subjob then puts the segment token for the trickle-down message in the BPM subjob's (message service) mailbox. It knows the segment token and mailbox token becuase this information was stored in the header of the second camac package by the BPMO subjob during preparation (step 1). MICRO_MBX in the BPMO subjob receives the trickle-down message and wakes up the driver, which in turn looks at the function code in the message and calls the appropriate routine (MEASPROC) to handle it. 6. MEASPROC uses the data in the trickle-down message to generate the data for a response back to the requesting SCP. Because of the way the trickle-down message was constructed, the BPMO subjob can now call MMSG_SEND with destination = RESP, as if it were responding to a direct request from the SCP rather than one forwarded via the MPG.
MESSAGE COMMUNICATIONS IN SLC Page 7-29 7. The SCP has called MPG_SYNC with a co-routine able to sort out the different kinds of responses (MPG acknowledgement or sector micro returning data). It then processes the data and puts up the display. For the next update of the display, begin the cycle at step 2. 8. Finally, when the display is turned off, the SCP sends a message to LI01 telling it to "cancel the YY's"; i.e., delete the segments used for the camac packages and the trickle-down message, and clear the elements in the array YY_SEGMENT corresponding to the YY's. The message has function code BPMO_CANCEL. The data consists of the number of YY's (here = 2) followed by the list of YY's whose associations are to be broken. The micro fulfills the request, then responds with function code BPMO_CANCEL + RESPONSE, data being one longword of status. The SCP may now use the YY's for some other purpose without fear of spurious activity by LI01.7.6.5 Ground Rules Each SCP may only use YY's in the range SCP_ID * 16 < YY < (SCP_ID+1) * 16 + 1. The first eight of these are reserved for the BPMO facility.