VxWorks API Reference : OS Libraries
distNameLib - distributed name database library (VxFusion option)
distNameAdd( ) - add an entry to the distributed name database (VxFusion option)
distNameFind( ) - find an object by name in the local database (VxFusion option)
distNameFindByValueAndType( ) - look up the name of an object by value and type (VxFusion option)
distNameRemove( ) - remove an entry from the distributed name database (VxFusion option)
This library contains the distributed objects distributed name database and routines for manipulating it. Symbolic names are bound to values, such as message queue identifiers or simple integers. Entries can be found by name or by value and type. The distributed name database is replicated throughout the system, with a copy sitting on each node.
The distributed name database library is initialized by calling distInit( ) in distLib.
This module is distributed as a component of the unbundled distributed message queues option, VxFusion.
distNameLib.h
distNameAdd( ) - add an entry to the distributed name database (VxFusion option)
STATUS distNameAdd ( char * name, /* name to enter in database */ void * value, /* ptr to value to associate with name */ int valueLen, /* size of value in bytes */ DIST_NAME_TYPE type /* type associated with name */ )
This routine adds the name of a specified object, along with its type and value, to the distributed objects distributed name database. All copies of the distributed name database within the system are updated.
The name parameter is an arbitrary, null-terminated string with a maximum of 20 characters, including the null terminator.
The value associated with name is located at value and is of length valueLen, currently limited to 8 bytes.
By convention, type values of less than 0x1000 are reserved by VxWorks; all other values are user definable. The following types are pre-defined in distNameLib.h :
The byte-order of pre-defined types is preserved in a byte-order-heterogeneous network.
Type Name Value Datum T_DIST_MSG_Q = 0 distributed message queue T_DIST_NODE = 16 node ID T_DIST_UINT8 = 64 8-bit unsigned integer T_DIST_UINT16 = 65 16-bit unsigned integer T_DIST_UINT32 = 66 32-bit unsigned integer T_DIST_UINT64 = 67 64-bit unsigned integer T_DIST_FLOAT = 68 float (32-bit) T_DIST_DOUBLE = 69 double (64-bit) The value (and type!) bound to a symbolic name can be changed by calling distNameAdd( ) with a new value (and type).
This routine returns OK, even if some nodes on the system do not respond to the add request broadcast. A node that does not acknowledge a transmission is assumed to have crashed. You can use the distCtl( ) routine in distLib to set a routine to be called in the event that a node crashes.
If you add a distributed object ID (T_DIST_MSG_Q) to the database, another reference to the object is built. This reference is stored in the database. After the return of distNameAdd( ), value holds the reference (a new object ID). Use the ID returned by distNameAdd( ) each time you want to address the global object bound to name. Subsequent updates of the binding in the database are transparent. The original object ID specifies exactly the locally created object.
This routine is distributed as a component of the unbundled distributed message queues option, VxFusion.
OK, or ERROR if the operation fails.
- S_distNameLib_NAME_TOO_LONG
- The name being added to the database is too long.
- S_distNameLib_ILLEGAL_LENGTH
- The argument valueLen is not in the range 1 to 8.
- S_distNameLib_DATABASE_FULL
- The database is full.
- S_distNameLib_INCORRECT_LENGTH
- The argument valueLen is incorrect for the pre-defined type.
distNameFind( ) - find an object by name in the local database (VxFusion option)
STATUS distNameFind ( char * name, /* name to search for */ void * * pValue, /* where to return ptr to value */ DIST_NAME_TYPE * pType, /* where to return type */ int waitType /* NO_WAIT or WAIT_FOREVER */ )
This routine searches the distributed name database for an object matching a specified name. If the object is found, a pointer to the value and its type are copied to the address pointed to by pValue and pType. If the type is T_DIST_MSG_Q, the identifier returned can be used with generic message queue handling routines in msgQLib, such as msgQSend( ), msgQReceive( ), and msgQNumMsgs( ).
This routine is distributed as a component of the unbundled distributed message queues option, VxFusion.
OK, or ERROR if the search fails.
- S_distNameLib_NAME_TOO_LONG
- The name to be found in the database is too long.
- S_distNameLib_INVALID_WAIT_TYPE
- The wait type should be either NO_WAIT or WAIT_FOREVER .
distNameFindByValueAndType( ) - look up the name of an object by value and type (VxFusion option)
STATUS distNameFindByValueAndType ( void * value, /* value to search for */ DIST_NAME_TYPE type, /* type of object for which to search */ char * name, /* where to return name */ int waitType /* NO_WAIT or WAIT_FOREVER */ )
This routine searches the distributed name database for an object matching a specified value and type. If the object is found, its name is copied to the address pointed to by name.
Unlike the smNameFindByValue( ) routine, used with the shared-memory objects name database, this routine must know the type of the object being searched for. Searching on the value only might not return a unique object.
This routine is distributed as a component of the unbundled distributed message queues option, VxFusion.
OK, or ERROR if the search fails.
- S_distNameLib_INVALID_WAIT_TYPE
- The wait type should be either NO_WAIT or WAIT_FOREVER .
distNameRemove( ) - remove an entry from the distributed name database (VxFusion option)
STATUS distNameRemove ( char * name /* name of object to remove */ )
This routine removes an object, that is bound to name, from the distributed name database. All copies of the distributed name database get updated.
This routine returns OK, even if some nodes on the system do not respond to the remove request broadcast. A node that does not acknowledge a transmission is assumed to have crashed. You can use the distCtl( ) routine in distLib to set a routine to be called in the event that a node crashes.
Removing the name of a distributed object ID (T_DIST_MSG_Q) does not invalidate the object ID.
This routine is distributed as a component of the unbundled distributed message queues option, VxFusion.
OK, or ERROR if the operation fails.
- S_distNameLib_NAME_TOO_LONG
- The name to be removed from the database is too long.