VxWorks Reference Manual : Libraries
distNameLib - distributed name database library (VxFusion)
distNameAdd( ) - add an entry to the distributed name database
distNameFind( ) - find an object by name in the local database
distNameFindByValueAndType( ) - look up an object by value and type
distNameRemove( ) - remove an entry from the distributed name database
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.
distNameLib.h
distNameLib, distLib, distNameShow
distNameAdd( ) - add an entry to the distributed name database
STATUS distNameAdd ( char * name, /* name to enter in database */ void * value, /* value associated 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.
l l l. 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 bound to the symbolic name can be changed by calling distNameAdd( ) with a new value.
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.
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 either equal to 0 or greater than 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
STATUS distNameFind ( char * name, /* name to search for */ void * *pValue, /* pointer where to return value */ DIST_NAME_TYPE * pType, /* pointer 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( ).
- 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.
OK, or ERROR if the search fails.
distNameFindByValueAndType( ) - look up an object by value and type
STATUS distNameFindByValueAndType ( void * value, /* value to search for */ DIST_NAME_TYPE type, /* type of object searched */ char * name, /* pointer 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 searched. Searching on the value only might not return a unique object.
- S_distNameLib_INVALID_WAIT_TYPE
- The wait type should be either NO_WAIT or WAIT_FOREVER.
OK, or ERROR if the search fails.
distNameRemove( ) - remove an entry from the distributed name database
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.
- S_distNameLib_NAME_TOO_LONG
- The name to be removed from the database is too long.
OK, or ERROR if the operation fails.