Topic       : TOS - das Betriebssystem
Author      : 
Version     : tos.hyp (5. März 2013)
Subject     : Programmieren/Atari
Nodes       : 3001
Index Size  : 93602
HCP-Version : 5
Compiled on : Atari
@charset    : atarist
@lang       : 
@default    : Titel
@help       : 
@options    : +g -i -s +x +zz -t4
@width      : 70
View Ref-File5.11.16  Pmsg                                                      TOS

 Name:         »Pmsg« - Empfangen und Senden von Nachrichten.

 Gemdosnummer: 293

 Deklaration:  int32_t Pmsg ( int16_t mode, int32_t mbox, void *msg );

 Beschreibung: Die Funktion sendet bzw. empfängt eine Nachricht zu 
               bzw. von einer Mailbox. Die jeweils auszuführende 
               Operation kann über die Bits des Parameters mode 
               festgelegt werden. Es bedeutet:

                mode    Operation

                0x0000  Blockiert den Prozess bis aus der übergebenen 
                        Mailbox mit der ID mbox eine Nachricht gelesen 
                        werden kann und speichert diese in der 
                        Struktur, auf die msg zeigt.
                0x0001  Blockiert den Prozess bis ein Prozess auf eine 
                        Nachricht aus der Mailbox mit der ID mbox 
                        wartet und diese Nachricht aus der Struktur, 
                        auf die msg zeigt, ausliest.
                0x0002  Blockiert den Prozess bis ein Prozess auf eine 
                        Nachricht aus der Mailbox mit der ID mbox 
                        wartet und diese Nachricht aus der Struktur, 
                        auf die msg zeigt, ausliest und in der Mailbox 
                        mit der Kennung 0xffffxxxx eine Nachricht 
                        liegt (dabei ist xxxx die PID des aktuellen 
                        Prozesses).
                0x8000  Durch eine ODER-Verknüpfung mit diesem Wert 
                        kann die Operation im nicht-blockierenden 
                        Modus ausgeführt werden.

               Die Nachrichten sind 5 Wörter lang, und zwar zwei 
               Langworte und ein Short (in dieser Reihenfolge). Dabei 
               können die 2 Langwörter vom Prozess mit beliebiger 
               Information gefüllt werden, während im Short die PID 
               des Senders einzutragen ist.

               Nach dem die Nachricht verschickt worden ist, enthält 
               dieses Short die PID des Prozesses, der die Nachricht 
               gelesen hat. Umgekehrt enthält dieser nach dem Lesen 
               einer Nachricht die PID des Prozesses, der die 
               Nachricht geschrieben hat.

               Wenn in mode das höchstwertige Bit gesetzt ist, und es 
               keinen Leser bzw. Schreiber für die Mailbox mbox gibt, 
               wird der Wert -1 zurückgeliefert. Anderenfalls wartet 
               eine Leseoperation bis eine Nachricht geschrieben 
               wurde, bzw. eine Schreiboperation bis ein lesender 
               Prozess bereit ist.

               Im Modus 2 gibt der Schreiber an, daß er auf eine 
               Antwort warten möchte. Die Idee dabei ist, daß dieser 
               Prozess sich schlafen legen kann, und zu einem späteren 
               Zeitpunkt von dem Prozess der die Nachricht erhält, 
               wieder aufgeweckt werden kann. Dabei wird garantiert, 
               daß der Prozess, welcher die Original-Nachricht erhält 
               beim Schreiben der Antwort nicht blockiert wird.

 Ergebnis:     Die Funktion kann folgende Rückgabewerte liefern:

                E_OK :    kein Fehler aufgetreten.
                EINVFN :  ungültiger Wert für den Parameter mode.
                -1 :      Bit-15 ist gesetzt, und Pmsg würde 
                          blockieren.

 Verfügbar:    Verfügbar, wenn ein 'MiNT' Cookie mit einer 
               Versionsnummer von mindestens 0.90 existiert.

 Gruppe:       Prozessfunktionen

 Querverweis:  Binding