--- name: "pvm_putinfo" section: "3" platform: "linux" package: "pvm-dev" version: "3.4.2-8" release: "Debian 3.0 (Woody)" platforms: ["linux"] url: "https://new.carta.tech/pvm_putinfo" --- # pvm\_putinfo(3) Store and retrieve messages in global mailbox. ## NAME pvm\_putinfo, pvm\_recvinfo, pvm\_getmboxinfo, pvm\_delinfo - Store and retrieve messages in global mailbox. ## SYNOPSIS ``` C int index = pvm_putinfo( char *name, int bufid, int flags ) int bufid = pvm_recvinfo( char *name, int index, int flags ) int info = pvm_delinfo( char *name, int index, int flags ) int info = pvm_getmboxinfo( char *pattern, int *nclasses, struct pvmmboxinfo **classes ) struct pvmmboxinfo { char *mi_name; /* class name */ int mi_nentries; /* # of entries for this class */ int *mi_indices; /* mbox entry indices */ int *mi_owners; /* mbox entry owner tids */ int *mi_flags; /* mbox entry flags */ }; Fortran call pvmfputinfo( name, bufid, flags, index ) call pvmfrecvinfo( name, index, flags, bufid ) call pvmfdelinfo( name, index, flags, info ) call pvmfgetmboxinfo( pattern, name, nclasses, nentries, index, owner, flags, info ) ``` ## PARAMETERS - name **Database key (class name), any null-terminated string.** - index **Database key (class index), \>= 0.** **Default index = 0.** - flags **User specified options. (see below)** - bufid **Handle of message buffer to put in database, or message returned.** **A returned bufid \< 0 indicates an error.** - info **Resulting status code.** - pattern **GNU regular expression (pattern) to match on names in mailbox database.** **Additionally, the singular "\*" will match on all names.** - nclasses **Number of classes matching pattern.** - classes **Array of pvmmboxinfo mailbox entries matching pattern.** - nentries **Number of entries for a given class.** - owner **Task id that inserted entry into mailbox database.** ## DESCRIPTION **These functions implement a "message mailbox" database** **that can be used by PVM tasks to advertise information to** **other PVM tasks.** **An example would be to advertise names or locations** **of services. Another example would be to advertise** **a common "context" on which two tasks may communicate.** **The database entries are PVM messages keyed by** **a user specified name and an optional index value.** **The name may be any null-terminated string and the index a** **non-negative integer.** **The index value is assigned by PVM and is used to** **uniquely identify one of multiple named instances** **within the database.** **Entries are "owned" by the task that created them.** **An entry is automatically removed from the database when** **the owner task exits unless the database entry was** **created with flag PvmMboxPersistent.** **When a task exits and leaves an entry in the mailbox,** **the owner tid of that entry is marked as zero (0) to** **indicate that there is no longer an active owner task.** *pvm\_putinfo* **inserts a record in the database, given a key and data (message).** **It returns mailbox index number if the record is successfully stored,** **PvmExists if a record with the given key already exists,** **or PvmDenied if an attempt is made to overwrite a locked record.** **The following options are added together as the flags parameter** **to pvm\_putinfo.** - PvmMboxDefault **Inserts entry as the only named instance for a given name.** **This entry may only be modified and deleted by its owner.** **It is automatically deleted when its owner exits.** - PvmMboxPersistent **Entry remains in the database when the owner task exits.** **Entries are removed from the database when PVM is halted** **or a reset is issued from the console.** - PvmMboxMultiInstance **Permits multiple entry instances of the same name.** **PVM will assign an index key to each instance.** - PvmMboxOverWritable **Permits other tasks to overwrite and delete this** **database entry.** *pvm\_recvinfo* **operates just like a pvm\_recv() except the message is coming** **from the database.** **The message should be unpacked after pvm\_recvinfo().** **Like pvm\_recv, pvm\_recvinfo returns a pointer to a message buffer** **containing the record matching the key \ from the database.** **Returned value \< 0 indicates an error.** **The following options are added together as the flags parameter** **to pvm\_recvinfo.** - PvmMboxDefault **Exact match on key \ is returned.** **Returns PvmNotFound if exact match not found.** - PvmMboxFirstAvail **The first entry in \ with index greater than or equal to** **the specified index parameter is retuned.** **PvmMboxFirstAvail with index = 0 will produce the same** **results as using PvmMboxDefault.** - PvmMboxReadAndDelete **Return entry and delete from database.** **Task must be permitted to do both read and delete otherwise** **an error will occur.** **bufid returns PvmNotFound if entry does not exist and** **will return PvmDenied if the record exists but may not be deleted.** *pvm\_delinfo* **deletes database entry specified by the key \.** **Returns PvmOK if the record was deleted, PvmNotFound if** **the record does not exist, or PvmDenied if an attempt is** **made to remove a "locked" record.** **There are no flags presently specified for pvm\_delinfo.** *pvm\_getmboxinfo* **returns an array of pvmmboxinfo for all class names in the database.** **This is used, for example, by programs that clean up the database** **or for applications to find out what is available.** *classes* returns a pointer to the array allocated by libpvm and freed on the next call to pvm\_getmboxinfo. The Fortran function returns information on one entry per call. Thus, if called repeatedly until an info value of *PvmNotFound* is returned, all entries matching the given pattern will have been returned. If a new pattern is desired, calling pvmfgetnames() with info = -1 will reset the entry name list and obtain a new list for the given pattern. ## EXAMPLES ``` C: /* * create and insert mailbox entry */ sprintf( service, "Task_A_service" ); sprintf( message, "Greetings from task A." ); pvm_initsend( PvmDataDefault ); pvm_pkint( &mytid, 1, 1 ); pvm_pkint( &context, 1, 1 ); pvm_pkstr( message ); if (( pvm_putinfo( service, pvm_getsbuf(), PvmMboxDefault )) == PvmExists ){ printf( "can't register - service already running0 ); exit( -1 ); } /* * look for and retrieve specified mailbox */ sprintf( service, "Task_A_service" ); if (( msg_buf = pvm_recvinfo(service, 0, PvmMboxFirstAvail )) >= 0 ){ pvm_setrbuf( msg_buf ); pvm_upkint( &their_tid, 1, 1 ); pvm_upkint( &their_context, 1, 1 ); pvm_upkstr( message ); } Fortran: we need the fortran examples... ``` ## ERRORS The following error conditions can be returned by one or more of these functions: - PvmBadParam An invalid value was specified for *bufid* argument. - PvmNoSuchBuf Message buffer *bufid* doesn't exist. - PvmNoMem Libpvm is unable to allocate memory to pack data. - PvmExists The requested key is already in use (pvm\_putinfo). - PvmNotFound The requested key does not exist (pvm\_recvinfo, pvm\_delinfo). - PvmDenied The key is locked by another task and cannot be replaced or deleted. ## SEE ALSO pvm\_initsend(3PVM), pvm\_getsbuf(3PVM), pvm\_pack(3PVM),