# radlib Library Reference

Version 2.12.0

## Index

### Buffers (radbuffers.h)

Buffer sizes are determined by the following three macros defined in radsysdefs.h. Buffer sizes start at SYS_BUFFER_SMALLEST_SIZE (+4) and are increased by powers of 2 up to SYS_BUFFER_LARGEST_SIZE (+4), with SYS_BUFFER_NUMBER_OF_SIZES different sizes. The definition of counts for each buffer size is in the array sysBufferCounts, defined in radsysdefs.c. These can be tailored to system buffer requirements and available memory.

radBuffersInit
radBufferGet
radBufferRls
radBuffersExit
radBuffersExitAndDestroy
radBuffersGetTotal
radBuffersGetAvailable

### Config Files (radconffile.h)

radCfOpen
radCfClose
radCfFlush
radCfPutComment
radCfPutCommentBefore
radCfIsCommentBefore
radCfIsCommentAfter
radCfGetFirstEntry
radCfGetNextEntry
radCfGetEntry
radCfPutEntry

### CRC Utilities (radcrc.h)

CCITT CRC utilities.

radCRC16Calculate
radCRC32Calculate

### SQL Database Interface (raddatabase.h)

Optional MySQL or PostGreSQL database library which may be included when radlib is configured via the "--enable-mysql" or "--enable-pgresql" argument to the configure script. Requires a running MySQL or PostgreSQL server and the mysqlclient or pq library (libmysqlclient.a or libpq.a). Other database servers can be supported - all engine-specific source code is segregated in .../database/mysql or .../database/postgresql. Databases, users and user access privileges must be setup outside of the radlib interface - radlib can create/delete tables/rows and manipulate them for given databases and users. Local or remote servers can be accessed.

Database Methods
raddatabaseOpen
raddatabaseClose
raddatabaseQuery
raddatabaseGetResults
raddatabaseRefreshResults
raddatabaseReleaseResults
Table Methods
raddatabaseTableIfExists
raddatabaseTableCreate
raddatabaseTableDelete
raddatabaseTableTruncate
raddatabaseTableDescriptionGet
raddatabaseTableQueryRow
raddatabaseTableInsertRow
raddatabaseTableModifyRows
raddatabaseTableDeleteRows
Result Set Methods
raddatabaseResultsGetFirst
raddatabaseResultsGetNext
raddatabaseResultsGetPrev
raddatabaseResultsGetLast
Row Description Methods
raddatabaseRowDescriptionCreate
raddatabaseRowDescriptionAddField
raddatabaseRowDescriptionRemoveField
raddatabaseRowDescriptionDelete
Field Manipulation Methods
raddatabaseFieldGet
raddatabaseFieldGetType
raddatabaseFieldGetIntValue
raddatabaseFieldGetBigIntValue
raddatabaseFieldGetFloatValue
raddatabaseFieldGetDoubleValue
raddatabaseFieldGetTimeDateValue
raddatabaseFieldGetCharValue
raddatabaseFieldGetCharLength
raddatabaseFieldSetTypeInt
raddatabaseFieldSetTypeBigInt
raddatabaseFieldSetTypeFloat
raddatabaseFieldSetTypeDouble
raddatabaseFieldSetTypeDateTime
raddatabaseFieldSetTypeChar
raddatabaseFieldSetToNull
raddatabaseFieldSetToNotNull
raddatabaseFieldSetIntValue
raddatabaseFieldSetBigIntValue
raddatabaseFieldSetFloatValue
raddatabaseFieldSetDoubleValue
raddatabaseFieldSetDateTimeValue
raddatabaseFieldSetCharValue

### Events (radevents.h)

radEventsInit
radEventsExit
radEventsAdd
radEventsRemove
radEventsGetMask
radEventsSend
radEventsProcess

### Doubly-Linked Lists (radlist.h)

To use the list utility, one first creates (or resets) the list. Subsequent calls to this utility take the RADLIST_ID as the first parameter. In order for a structure to be an item or "node" on the list, the structure must include the NODE structure as it's first member. This allows different types of objects to be stored on the same list.

radListCreate
radListReset
radListDelete
radListInsertAfter
radListInsertBefore
radListAddToFront
radListAddToEnd
radListRemove
radListRemoveFirst
radListRemoveLast
radListGetNumberOfNodes
radListGetFirst
radListGetLast
radListGetNext
radListGetPrevious

### System Logging (radmsgLog.h)

The message logging utility uses the syslog system facility. Messages can have the following priorities:
`enum MsgLogPriorities
{
PRI_STATUS = LOG_INFO,
PRI_MEDIUM = LOG_WARNING,
PRI_HIGH = LOG_CRIT,
PRI_CATASTROPHIC = LOG_ALERT
};`

radMsgLogInit
radMsgLogExit
radMsgLog
radMsgLogData

### Message ID-Based Message Router and API (radmsgRouter.h)

Message ID-based messaging requires the radlib message router to be run prior to any application processes. The message router is installed at $prefix/bin/radmrouted. See radmsgRouter.h for start up details. This API supports sending and receiving messages through the radmrouted daemon.
Message routing can be done across processors using a common message ID namespace. The radmrouted instance running on each processor "associates" to his peer(s) using TCP/IP sockets. A radmrouted instance may be a server and/or client. Messages routed on one processor are routed to all associated processors and delivered to all consumers on each processor for that message type. It makes interprocessor communications transparent. See "radmrouted Daemon Usage" below for command line options which enable multiprocessor communications.

radMsgRouterInit
radMsgRouterExit
radMsgRouterProcessExit
radMsgRouterMessageRegister
radMsgRouterMessageDeregister
radMsgRouterMessageIsRegistered
radMsgRouterMessageSend
radMsgRouterStatsDump
radmrouted Daemon Usage

### Process Framework (radprocess.h)

This utility brings together many of the radlib concepts into one set of APIs. This is the preferred API for implementing radlib processes and applications. It greatly simplifies the asynchronous capabilities of a well constructed radlib application.

radProcessInit
radProcessExit
radProcessSetExitFlag
radProcessWait
radProcessGetName
radProcessGetPid
radProcessIORegisterDescriptor
radProcessIODeRegisterDescriptor
radProcessIORegisterSTDIN
radProcessSignalCatchAll
radProcessSignalCatch
radProcessSignalRelease
radProcessSignalIgnore
radProcessSignalGetHandler
radProcessQueueGetName
radProcessQueueAttach
radProcessQueueDettach
radProcessQueueJoinGroup
radProcessQueueQuitGroup
radProcessQueueSend
radProcessQueueSendGroup
radProcessQueueIsAttached
radProcessQueueKeepBuffer
radProcessQueueStopHandlerList
radProcessQueuePrependHandler
radProcessQueueRemoveHandler
radProcessTimerCreate
radProcessTimerDelete
radProcessTimerStart
radProcessTimerStop
radProcessTimerStatus
radProcessTimerSetUserParm
radProcessEventsAdd
radProcessEventsRemove
radProcessEventsGetEnabled
radProcessEventsSend

### Process List Management (radproclist.h)

radPlistCreate
radPlistDestroy
radPlistAdd
radPlistStart
radPlistGetNumberRunning
radPlistExecByEntryPoint
radPlistExecAll
radPlistAddPid
radPlistRemovePid
radPlistAddandStart
radPlistProcessReady
radPlistFindByEntryPoint

### Process Utilities (radprocutils.h)

radStartProcess

### Message Queues (radqueue.h)

Process message queues are implemented using named pipes. Therefore, "queue names" should be the full path name to a pipe device file, which will be created by radQueueInit if it does not exist. This utility is best used as part of the radProcess framework.

radQueueSystemInit
radQueueSystemExit
radQueueInit
radQueueExit
radQueueGetFD
radQueueGetName
radQueueAttach
radQueueDettach
radQueueJoinGroup
radQueueQuitGroup
radQueueRecv
radQueueSend
radQueueSendGroup
radQueueIsAttached

### Semaphores (radsemaphores.h)

radSemProcessInit
radSemSetDestroy
radSemCreate
radSemTake
radSemGive
radSemGiveMultiple
radSemTest
radSemDelete
radSemDebug

### SHA-1 and SHA-256 Secure Hashing Utilities (radsha.h)

The SHA algorithms were designed by the National Security Agency (NSA) and published as US government standards. The SHA-256 implementation is derived from the FreeBSD implementation. Host endianness is determined when radlib is configured and the SHA utilities work properly on big or little endian hosts.

radSHA1ComputeBlock
radSHA1ComputeFile
radSHA256ComputeBlock
radSHA256ComputeFile

### Shared Memory (radshmem.h)

Shared memory is the lynch pin of radlib interprocess communications. System buffers and message queues depend upon the existence (and robustness) of shared memory.

radShmemIfExist
radShmemInit
radShmemGet
radShmemLock
radShmemUnlock
radShmemExit
radShmemExitAndDestroy

### TCP Stream Sockets (radsocket.h)

radSocketServerCreate
radSocketServerAcceptConnection
radSocketClientCreate
radSocketClientCreateAny
radSocketDestroy
radSocketGetDescriptor
radSocketGetHost
radSocketGetPort
radSocketReadExact
radSocketWriteExact
radSocketSetBlocking
radSocketSetDebug

### Sorted Lists (radsortlist.h)

radSortListInit
radSortListExit
radSortListInsert
radSortListRemove
radSortListFind

### SQLite Database Interface (radsqlite.h)

Optional SQLite database library which may be included when radlib is configured via the "--enable-sqlite" argument to the configure script. Requires the SQLite development library (libsqlite.a). Preserves much of the raddatabase.h API but is simplified for the SQLite capabilities and API design. Can be enabled in parallel with raddatabase-supported database engines.

Database Methods
radsqliteOpen
radsqliteClose
radsqliteQuery
radsqliteGetResults
radsqliteRefreshResults
radsqliteReleaseResults
Table Methods
radsqliteTableIfExists
radsqliteTableCreate
radsqliteTableDelete
radsqliteTableTruncate
radsqliteTableDescriptionGet
radsqliteTableQueryRow
radsqliteTableInsertRow
radsqliteTableModifyRows
radsqliteTableDeleteRows
Result Set Methods
radsqliteResultsGetFirst
radsqliteResultsGetNext
radsqliteResultsGetPrev
radsqliteResultsGetLast
Row Description Methods
radsqliteRowDescriptionCreate
radsqliteRowDescriptionAddField
radsqliteRowDescriptionRemoveField
radsqliteRowDescriptionDelete
Field Manipulation Methods
radsqliteFieldGet
radsqliteFieldGetType
radsqliteFieldGetBigIntValue
radsqliteFieldGetDoubleValue
radsqliteFieldGetCharValue
radsqliteFieldGetCharLength
radsqliteFieldSetTypeBigInt
radsqliteFieldSetTypeDouble
radsqliteFieldSetTypeChar
radsqliteFieldSetToNull
radsqliteFieldSetToNotNull
radsqliteFieldSetBigIntValue
radsqliteFieldSetDoubleValue
radsqliteFieldSetCharValue

### Stacks (First In-Last Out) (radstack.h)

Stacks are implemented as a special case of the radlist utility. STACK_NODEs should be included as the first element of object definitions (structures) in the same way NODEs are for the list utility.

radStackInit
radStackExit
radStackPush
radStackPop
radStackCount

### State Machines (radstates.h)

State machines are composed of an array of state handlers and a mechanism to "stimulate" the current state. State transitions occur when the current state's handler returns a new state value. The return value of a given state handler is thus stored as the new current state. The use of radStatesSetState is strongly discouraged, except to set the initial state during initialization.

radStatesInit
radStatesExit
radStatesAddHandler
radStatesRemHandler
radStatesProcess
radStatesSetState
radStatesGetState
radStatesReset

### radlib System Control (radsystem.h)

This utility prepares radlib system facilities so that radProcessInit can be invoked. By specifying a system ID to these functions, it allows unrelated radlib "systems" (sets of processes) to run concurrently.

radSystemInit
radSystemExit
radSystemGetUpTimeMS
radSystemGetUpTimeSEC
radSystemGetUpTimeSTR

### radlib System Utilities (radsysutils.h)

radUtilsSetIntervalTimer
radUtilsGetIntervalTimer
radUtilsEnableSignal
radUtilsDisableSignal
radUtilsBecomeDaemon
radUtilsSleep

### Red-Black Text Search (radtextsearch.h)

This utility provides fast text string search given a well-known set of text strings (the universe). An ordinal value is stored with each text string in a red-black binary tree. Once the tree is populated with the universe of possible text strings and corresponding ordinal values, the find method can be used to retrieve the corresponding ordinal if a matching text string is found.

radtextsearchInit
radtextsearchExit
radtextsearchInsert
radtextsearchRemove
radtextsearchFind

### Thread Utilities (radthread.h)

Provide a uniform way to create and destroy utility threads from radlib processes.
Communication between the parent and thread can be accomplished in three ways:
1) Using the radthread internal queues via radthreadSendToThread, radthreadReceiveFromThread, radthreadSendToParent, raddthreadReceiveFromParent.
2) If the parent is using radProcessWait to receive messages and wait on file descriptor IO, the producer threads can use radMsgRouterMessageSend to send data to the Consumer (parent). The parent thread must have registered with radMsgRouterInit and for the message the thread sends via radMsgRouterMessageRegister. The thread can send messages not intended for the parent process as well.
3) Modifying shared data directly. Parents and threads should use the radthreadLock and radthreadUnlock functions if modifying any shared data. This should be done with great caution. In particular, radMsgRouterMessageSend locks and unlocks the thread mutex directly so the mutex cannot be held when calling it.
All threads should periodically test for an exit request from the parent using the radthreadShouldExit function. Parents calling radthreadWaitExit will block until the thread terminates. If the parent needs to know when the thread exits, the thread should send a message via radMsgRouterMessageSend to indicate it is exiting.

Parent Actions:
radthreadCreate
radthreadWaitExit
radthreadSendToThread
radthreadReceiveFromThread
Thread Actions:
radthreadSendToParent
radthreadReceiveFromParent
radthreadShouldExit
Parent or Thread Actions:
radthreadLock
radthreadUnlock

### Timers (radtimers.h)

radTimerListCreate
radTimerListDelete
radTimerCreate
radTimerDelete
radTimerStart
radTimerStop
radTimerStatus
radTimerSetUserParm

### Time Utilities (radtimeutils.h)

radTimeGetMSSinceEpoch
radTimeGetSECSinceEpoch

### UDP Datagram Sockets (radUDPsocket.h)

radUDPSocketCreate
radUDPSocketDestroy
radUDPSocketGetDescriptor
radUDPSocketBind
radUDPSocketSetBroadcast
radUDPSocketSetMulticastTXInterface
radUDPSocketSetMulticastTTL
radUDPSocketSetMulticastLoopback
radUDPSocketAddMulticastMembership
radUDPSocketDropMulticastMembership
radUDPSocketRecvFrom
radUDPSocketSendTo
radUDPSocketSetBlocking
radUDPSocketSetDebug

## Descriptions

### `radBuffersInit()`

int radBuffersInit (int minBufferSize, int maxBufferSize, int *numberOfEachSize)

#### Description

Called from process initialization (normally by radSystemInit). Not normally called directly by application methods. Creates the system buffer pool.

#### Return Value

OK or ERROR

#### Notes

radSemProcessInit must be called before this method (also usually called from radSystemInit).

#### Parameters

Type | Name | Description
int | minBufferSize | smallest buffer size in the pool
int | maxBufferSize | largest buffer size in pool
int * | numberOfEachSize | array of buffer counts

### `radBufferGet()`

`void *radBufferGet (int size);`

#### Description

Request a system buffer of size "size".

#### Return Value

The buffer pointer or NULL if none available.

#### Notes

#### Parameters

Type | Name | Description
int | size | The length in bytes of the buffer requested

### `radBufferRls()`

`int radBufferRls (void *buffer);`

#### Description

Release a system buffer back into the free pool.

#### Return Value

OK or ERROR

#### Notes

#### Parameters

Type | Name | Description
void * | buffer | Buffer pointer obtained from a successful radBufferGet call.

### `radBuffersExit()`

`void radBuffersExit (void);`

#### Description

Detach from the system buffer pool. Does NOT destroy the system buffer pool. Not normally called from application methods (called from radSystemExit).

#### Return Value

None

### `radBuffersExitAndDestroy()`

`void radBuffersExitAndDestroy (void);`

#### Description

Detach from the system buffer pool. DOES mark the system buffer pool for destroy. Not normally called from application methods (called from radSystemExit).

### `radBuffersGetTotal()`

`ULONG radBuffersGetTotal (void);`

#### Description

Retrieve the total number of buffers (all sizes, free and allocated) in the system.

#### Return Value

The total free and allocated buffers in the system.

### `radBuffersGetAvailable()`

`ULONG radBuffersGetAvailable (void);`

#### Description

Retrieve the number of available (free) buffers in the system.

#### Return Value

The number of free buffers of any size in the system.

### `radCfOpen()`

`CF_ID radCfOpen (char *file);`

#### Description

Creates a lock on the file, opens the given config file, creating local record keeping about the file. If the file does not already exist, a new file is created. Returns the CF_ID or NULL indicating an error. The file will remain locked until radCfClose is called.

#### Return Value

If successful, a valid CF_ID to be used with all subsequent radCF methods. NULL is returned if there is an error.

#### Notes

This function reads the entire file into a RAM copy for use by the rest of the radCF utilities. Any changes made to the config file via these methods will NOT take effect until the application calls radCfFlush!

#### Parameters

Type | Name | Description
char * | file | Full path name of the config file

### `radCfClose()`

`void radCfClose (CF_ID file);`

#### Description

Releases the lock on the file, closes the file and cleans up local information about it.

#### Return Value

None

#### Parameters

Type | Name | Description
CF_ID | file | radCF ID

### `radCfFlush()`

`int radCfFlush (CF_ID file);`

#### Description

Flushes the file to disk.

#### Return Value

OK or ERROR

#### Notes

This call MUST be made for any changes to config files to be saved to the disk file itself.

#### Parameters

Type | Name | Description
CF_ID | file | radCF ID

### `radCfPutComment()`

`int radCfPutComment (CF_ID file, char *text);`

#### Description

Creates a comment line at the end of the config file.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
CF_ID | file | radCF ID
char * | text | Text string to add as a comment

### `radCfPutCommentBefore()`

`int radCfPutCommentBefore (CF_ID file, char *id, char *instance, char *commentText);`

#### Description

Inserts a comment before the given entry.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
CF_ID | file | radCF ID
char * | id | ID value string
char * | instance | Instance string (can be NULL)
char * | commentText | Text string to add as a comment

### `radCfIsCommentBefore()`

`int radCfIsCommentBefore (CF_ID file, char *id, char *instance, char *commentText);`

#### Description

Checks for a comment before the given entry.

#### Return Value

TRUE or FALSE

#### Parameters

Type | Name | Description
CF_ID | file | radCF ID
char * | id | ID value string
char * | instance | Instance string (can be NULL)
char * | commentText | Text string to add as a comment

### `radCfIsCommentAfter()`

`int radCfIsCommentAfter (CF_ID file, char *id, char *instance, char *commentText);`

#### Description

Checks for a comment after the given entry.

#### Return Value

TRUE or FALSE

#### Parameters

Type | Name | Description
CF_ID | file | radCF ID
char * | id | ID value string
char * | instance | Instance string (can be NULL)
char * | commentText | Text string to add as a comment

### `radCfGetFirstEntry()`

`int radCfGetFirstEntry (CF_ID file, char *id, char *instance, char *value);`

#### Description

Retrieves the first entry for a particular ID. instance and value are both filled with the appropriate information when an entry is found.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
CF_ID | file | radCF ID
char * | id | ID value string
char * | instance | Instance string (can be NULL)
char * | value | Value string if found

### `radCfGetNextEntry()`

`int radCfGetNextEntry (CF_ID file, char *id, char *instance, char *value);`

#### Description

Gets the next entry for a particular ID. instance and value are both filled with the appropriate information when a new entry is found.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
CF_ID | file | radCF ID
char * | id | ID value string
char * | instance | Instance string (can be NULL)
char * | value | Value string if found

### `radCfGetEntry()`

`int radCfGetEntry (CF_ID file, char *id, char *instance, char *value);`

#### Description

Retrieves a particular config file entry specified by the "id" and "instance" inputs.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
CF_ID | file | radCF ID
char * | id | ID value string
char * | instance | Instance string (can be NULL)
char * | commentText | Value string if found

### `radCfPutEntry()`

`int radCfPutEntry (CF_ID file, char *id, char *instance, char *value, char *comment);`

#### Description

Creates/Updates a configuration entry in the file given the id, instance, and value. New entries will be placed at the end of the file.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
CF_ID | file | radCF ID
char * | id | ID value string
char * | instance | Instance string (can be NULL)
char * | value | Value string
char * | comment | Comment string

### `radCRC16Calculate()`

`USHORT radCRC16Calculate (void *block, int byteLength);`

#### Description

Calculate the 16-bit CRC-CCITT for the given memory block.

#### Return Value

The USHORT CRC value.

#### Notes

The 16-bit CRC uses the standard CCITT polynomial: x^16+x^12+x^5+1. Uses "all bits set" as the seed value, i.e. 0xFFFF.

#### Parameters

Type | Name | Description
void * | block | memory block to calculate the 16 bit CRC over
int | byteLength | byte length of the memory block

### `radCRC32Calculate()`

`ULONG radCRC32Calculate (void *block, int byteLength);`

#### Description

Calculate the 32-bit CRC-CCITT for the given memory block.

#### Return Value

The ULONG CRC value.

#### Notes

The 32-bit CRC uses the standard polynomial: x^32+x^26+x^23+x^22+x^16+x^12+x^11+x^10+x^8+x^7+x^5+x^4+x^2+x+1. Uses "all bits set" as the seed value, i.e. 0xFFFFFFFF.

#### Parameters

Type | Name | Description
void * | block | memory block to calculate the 16 bit CRC over
int | byteLength | byte length of the memory block

### `raddatabaseOpen()`

`DATABASE_ID raddatabaseOpen
(
const char *host,
const char *username,
const char *password,
const char *dbName
);`

#### Description

Connect to a database server.

#### Return Value

Returns the DATABASE_ID or NULL

#### Notes

The database (dbName), user (userName), password (password) and access permissions for the database must be setup in the database server prior to use by the radlib database utilities.

#### Parameters

Type | Name | Description
const char * | host | FQDN or IP address of database server; if NULL, 'localhost' is used
const char * | userName | database username (cannot be NULL)
const char * | password | database user password (cannot be NULL)
const char * | dbName | database name - if NULL, no specific database is opened and all tableNames in calls below MUST be of the form 'dbName.tableName'

### `raddatabaseClose()`

`void raddatabaseClose
(
DATABASE_ID dbId
);`

#### Description

Close the connection to a database server.

#### Return Value

None

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call

### `raddatabaseQuery()`

`int raddatabaseQuery
(
DATABASE_ID dbId,
const char *query,
int createResults
);`

#### Description

Issue an SQL query to the database server.

#### Return Value

Returns OK or ERROR if there is a db server error, query error, or 'createResults' is set to TRUE and no result set is generated by the 'query'.

#### Notes

If results are generated it can be VERY slow and eat up a lot of heap space; the good news is that once the RESULT_SET_ID is retrieved using raddatabaseTableGetResults, it can persist as long as the user needs to keep it without adverse effects on the database server or the radlib host system.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
const char * | query | Well-formed SQL query statement
int | createResults | flag indicating if a result set should be generated

### `raddatabaseGetResults()`

`RESULT_SET_ID raddatabaseGetResults
(
DATABASE_ID dbId
);`

#### Description

Retrieve the result set (if there is one) - should be called immediately after raddatabaseTableQuery if the query was intended to generate a result set (SELECT, SHOW, etc.).

#### Return Value

Returns RESULT_SET_ID or NULL

#### Notes

RESULT_SET_ID should be released via raddatabaseTableResultsRelease once the user is finished with it.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call

### `raddatabaseRefreshResults()`

`RESULT_SET_ID raddatabaseRefreshResults
(
DATABASE_ID dbId,
RESULT_SET_ID origResultSet
);`

#### Description

Refresh a result set based on the original query.

#### Return Value

Returns RESULT_SET_ID or NULL

#### Notes

RESULT_SET_ID should be released via raddatabaseTableResultsRelease once the user is finished with it.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
RESULT_SET_ID | origResultSet | original result set returned by raddatabaseGetResults

### `raddatabaseReleaseResults()`

`void raddatabaseReleaseResults
(
DATABASE_ID dbId,
RESULT_SET_ID resultSet
);`

#### Description

Release a result set.

#### Return Value

None

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
RESULT_SET_ID | resultSet | result set returned by raddatabaseGetResults

### `raddatabaseTableIfExists()`

`int raddatabaseTableIfExists
(
DATABASE_ID dbId,
const char tableName );`

#### Description

Does 'tableName' table exist?

#### Return Value

Returns TRUE or FALSE

#### Notes

If raddatabaseOpen was called with a NULL database name, then this and all references to tableName in this API should be of the form 'Database.tableName'.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
const char * | tableName | name of table to check for existence

### `raddatabaseTableCreate()`

`int raddatabaseTableCreate
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowDescription /* see raddatabaseRowDescriptionCreate */
);`

#### Description

Create a table named 'tableName'.

#### Return Value

Returns OK or ERROR

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
const char * | tableName | name of table to be created
ROW_ID | rowDescription | describes the row structure for the new table (see raddatabaseRowDescriptionCreate)

### `raddatabaseTableDelete()`

`int raddatabaseTableDelete
(
DATABASE_ID dbId,
const char *tableName
);`

#### Description

Drop the table named 'tableName'.

#### Return Value

Returns OK or ERROR

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
const char * | tableName | name of table to be deleted

### `raddatabaseTableTruncate()`

`int raddatabaseTableTruncate
(
DATABASE_ID dbId,
const char *tableName
);`

#### Description

Truncate (empty) the table named 'tableName'.

#### Return Value

Returns OK or ERROR

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
const char * | tableName | name of table to be truncated

### `raddatabaseTableDescriptionGet()`

`ROW_ID raddatabaseTableDescriptionGet
(
DATABASE_ID dbId,
const char *tableName`

#### Description

Create a row description to use for row insertion/retrieval.

#### Return Value

Returns ROW_ID or NULL

#### Notes

The ROW_ID must be deleted with raddatabaseRowDescriptionDelete after the user is finished with it. Sets the FIELD_VALUE_IS_NULL bit in field->type for all fields - this means the user must clear this bit for field values to be used in queries/insertions/deletions (see the raddatabaseFieldSetXXXValue functions, which clear the FIELD_VALUE_IS_NULL bit for you).

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
const char * | tableName | retrieve the row description for this table

### `raddatabaseTableQueryRow()`

`RESULT_SET_ID raddatabaseTableQueryRow
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowDescription
);`

#### Description

Query a table to create a result set given a row description.

#### Return Value

Returns RESULT_SET_ID or NULL

#### Notes

Columns to be included in the result set should have FIELD_DISPLAY set in the appropriate FIELD_ID.type within 'rowDescription'; columns NOT to be included in the WHERE clause should have FIELD_VALUE_IS_NULL set in FIELD_ID.type; fields in the where clause are 'ANDed' together. Can be slow and eat up a lot of heap space - the good news is that once the RESULT_SET_ID is retrieved, it can persist as long as the user needs to keep it without adverse effects on the db server or the radlib host. RESULT_SET_ID should be released via raddatabaseTableResultsRelease once the user is finished with it. Only the populated fields in 'rowDescription' will be used to match records in the table (i.e., multiple rows can be matched).

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
const char * | tableName | table to query
ROW_ID | rowDescription | description with fields of interest populated

### `raddatabaseTableInsertRow()`

`int raddatabaseTableInsertRow
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowId
);`

#### Description

Insert a row into a table.

#### Return Value

Returns OK or ERROR

#### Notes

'rowId' is created with raddatabaseTableDescriptionGet then field values were populated with raddatabaseFieldGet, raddatabaseFieldSetXXXValue, etc. prior to this call. If a 'NOT NULL' field in the table has a NULL value in rowId, it's an error.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
const char * | tableName | table to insert the row into
ROW_ID | rowId | row description with fields of interest populated

### `raddatabaseTableModifyRows()`

`int raddatabaseTableModifyRows
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID matchId,
ROW_ID newData
);`

#### Description

Modify rows in 'tableName' matching 'matchId' with the field values defined in 'newData'.

#### Return Value

Returns OK or ERROR

#### Notes

Only the non-NULL fields in 'matchId' will be used to match records in the table (i.e., multiple rows can be matched). All fields in 'newData' will be updated in the rows which match 'matchId'- if a NULL value is given for a NOT NULL field in the table it is an error. Thus if you don't want to modify a column value, remove it from the 'newData' row desription with raddatabaseRowDescriptionRemoveField.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
const char * | tableName | table to modify
ROW_ID | matchId | row description with fields to match populated
ROW_ID | newData | row description with ONLY fields to be modified present

### `raddatabaseTableDeleteRows()`

`int raddatabaseTableDeleteRows
(
DATABASE_ID id
);`

#### Description

Delete rows in 'tableName' matching 'matchId'.

#### Return Value

Returns OK or ERROR

#### Notes

Only the non-NULL fields will be used to match records in the table (i.e., multiple rows can be matched).

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful raddatabaseOpen call
ROW_ID | matchId | row description with fields to match populated

### `raddatabaseResultsGetFirst()`

`ROW_ID raddatabaseResultsGetFirst
(
RESULT_SET_ID id
);`

#### Description

Retrieve the first row of a result set.

#### Return Value

Returns ROW_ID or NULL if the result set is empty

#### Notes

Allows traversal of the rows in a result set.

#### Parameters

Type | Name | Description
RESULT_SET_ID | id | result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow

### `raddatabaseResultsGetNext()`

`ROW_ID raddatabaseResultsGetNext
(
RESULT_SET_ID id
);`

#### Description

Retrieve the next row of a result set.

#### Return Value

Returns ROW_ID or NULL if there is no next row

#### Notes

Allows traversal of the rows in a result set.

#### Parameters

Type | Name | Description
RESULT_SET_ID | id | result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow

### `raddatabaseResultsGetPrev()`

`ROW_ID raddatabaseResultsGetPrev
(
RESULT_SET_ID id
);`

#### Description

Retrieve the previous row of a result set.

#### Return Value

Returns ROW_ID or NULL if there is no previous row

#### Notes

Allows traversal of the rows in a result set.

#### Parameters

Type | Name | Description
RESULT_SET_ID | id | result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow

### `raddatabaseResultsGetLast()`

`ROW_ID raddatabaseResultsGetLast
(
RESULT_SET_ID id
);`

#### Description

Retrieve the last row of a result set.

#### Return Value

Returns ROW_ID or NULL if the result set is empty

#### Notes

Allows traversal of the rows in a result set.

#### Parameters

Type | Name | Description
RESULT_SET_ID | id | result set obtained from raddatabaseGetResults or raddatabaseTableQueryRow

### `raddatabaseRowDescriptionCreate()`

`ROW_ID raddatabaseRowDescriptionCreate
(
void
);`

#### Description

Create an empty row description to use when describing a new table.

#### Return Value

Returns ROW_ID or NULL

#### Notes

ROW_ID should be released via raddatabaseRowDescriptionDelete once the user is finished with it.

### `raddatabaseRowDescriptionAddField()`

`int raddatabaseRowDescriptionAddField
(
ROW_ID id,
const char *name,
UINT type,
int maxLength
);`

#### Description

Add a new field to a row description.

#### Return Value

Returns OK or ERROR

#### Parameters

Type | Name | Description
ROW_ID | id | Value returned from successful raddatabaseRowDescriptionCreate call
const char * | name | name of the field to add
UINT | type | type of field to add (see radatabase.h)
int | maxLength | maximum length of field to add if it is a string

### `raddatabaseRowDescriptionRemoveField()`

`int raddatabaseRowDescriptionRemoveField
(
ROW_ID id,
const char *name
);`

#### Description

Remove a field identified by 'name' from the row description.

#### Return Value

Returns OK or ERROR

#### Parameters

Type | Name | Description
ROW_ID | id | Value returned from successful raddatabaseRowDescriptionCreate call
const char * | name | name of field to be removed

### `raddatabaseRowDescriptionDelete()`

`void raddatabaseRowDescriptionDelete
(
ROW_ID id
);`

#### Description

Release a row description and the corresponding fields.

#### Return Value

None

#### Parameters

Type | Name | Description
ROW_ID | id | Value returned from successful raddatabaseRowDescriptionCreate call

### `raddatabaseFieldGet()`

`FIELD_ID raddatabaseFieldGet
(
ROW_ID id,
const char *fieldName
);`

#### Description

Get the field identified by 'fieldName'.

#### Return Value

Returns FIELD_ID or NULL

#### Parameters

Type | Name | Description
ROW_ID | id | valid row description ID
const char * | fieldName | name of field to retrieve

### `raddatabaseFieldGetType()`

`UINT raddatabaseFieldGetType
(
DATABASE_ID id
);`

#### Description

Retrieve the field type bitmask (see raddatabase.h).

#### Return Value

Returns the field type bitmask

#### Notes

enum DbFieldTypes { FIELD_INT = 0x00000001, FIELD_STRING = 0x00000002, FIELD_BIGINT = 0x00000004, FIELD_FLOAT = 0x00000008, FIELD_DOUBLE = 0x00000010, FIELD_DATETIME = 0x00000020, FIELD_TYPE_CLEAR = 0xFF000000, /* used to clear field type only */ FIELD_VALUE_IS_NULL = 0x80000000, /* for queries & results only */ FIELD_DISPLAY = 0x40000000 /* for queries only */ };

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID to retrieve type from

### `raddatabaseFieldGetIntValue()`

`int raddatabaseFieldGetIntValue
(
FIELD_ID id
);`

#### Description

Retrieve the integer value of the field (must be of type FIELD_INT).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `raddatabaseFieldGetBigIntValue()`

`long long raddatabaseFieldGetBigIntValue
(
FIELD_ID id
);`

#### Description

Retrieve the big integer value of the field (must be of type FIELD_BIGINT).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `raddatabaseFieldGetFloatValue()`

`float raddatabaseFieldGetFloatValue
(
FIELD_ID id
);`

#### Description

Retrieve the float value of the field (must be of type FIELD_FLOAT).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `raddatabaseFieldGetDoubleValue()`

`double raddatabaseFieldGetDoubleValue
(
DATABASE_ID id
);`

#### Description

Retrieve the double value of the field (must be of type FIELD_DOUBLE).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `raddatabaseFieldGetTimeDateValue()`

`char *raddatabaseFieldGetTimeDateValue
(
FIELD_ID id
);`

#### Description

Retrieve the DATETIME value of the field (must be of type FIELD_DATETIME).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `raddatabaseFieldGetCharValue()`

`char *raddatabaseFieldGetCharValue
(
FIELD_ID id
);`

#### Description

Retrieve the string value of the field (must be of type FIELD_STRING).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `raddatabaseFieldGetCharLength()`

`int raddatabaseFieldGetCharLength
(
FIELD_ID id
);`

#### Description

Retrieve the string length of the field (must be of type FIELD_STRING).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `raddatabaseFieldSetTypeInt()`

`int raddatabaseFieldSetTypeInt
(
FIELD_ID id
);`

#### Description

Set the field type to FIELD_INT.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `raddatabaseFieldSetTypeBigInt()`

`int raddatabaseFieldSetTypeBigInt
(
FIELD_ID id
);`

#### Description

Set the field type to FIELD_BIGINT.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `raddatabaseFieldSetTypeFloat()`

`int raddatabaseFieldSetTypeFloat
(
FIELD_ID id
);`

#### Description

Set the field type to FIELD_FLOAT.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `raddatabaseFieldSetTypeDouble()`

`int raddatabaseFieldSetTypeDouble
(
FIELD_ID id
);`

#### Description

Set the field type to FIELD_DOUBLE.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `raddatabaseFieldSetTypeDateTime()`

`int raddatabaseFieldSetTypeDateTime
(
FIELD_ID id
);`

#### Description

Set the field type to FIELD_DATETIME.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `raddatabaseFieldSetTypeChar()`

`int raddatabaseFieldSetTypeChar
(
FIELD_ID id
);`

#### Description

Set the field type to FIELD_STRING.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `raddatabaseFieldSetToNull()`

`int raddatabaseFieldSetToNull
(
FIELD_ID id
);`

#### Description

Set the field flag to NULL (empty).

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `raddatabaseFieldSetToNotNull()`

`int raddatabaseFieldSetToNotNull
(
FIELD_ID id
);`

#### Description

Set the field flag to NOT NULL (not empty).

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `raddatabaseFieldSetIntValue()`

`int raddatabaseFieldSetIntValue
(
FIELD_ID id,
int value
);`

#### Description

Set the integer field value.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID
int | value | value to set

### `raddatabaseFieldSetBigIntValue()`

`int raddatabaseFieldSetBigIntValue
(
FIELD_ID id,
long long value
);`

#### Description

Set the big integer field value.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID
long long | value | value to set

### `raddatabaseFieldSetFloatValue()`

`int raddatabaseFieldSetFloatValue
(
FIELD_ID id,
float value
);`

#### Description

Set the float field value.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID
float | value | value to set

### `raddatabaseFieldSetDoubleValue()`

`int raddatabaseFieldSetDoubleValue
(
FIELD_ID id,
double value
);`

#### Description

Set the double field value.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID
double | value | value to set

### `raddatabaseFieldSetDateTimeValue()`

`int raddatabaseFieldSetDateTimeValue
(
FIELD_ID id,
const char *value,
int valueLength
);`

#### Description

Set the DATETIME field value.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID
const char * | value | value to set
int | valueLength | string length of value to set

### `raddatabaseFieldSetCharValue()`

`int raddatabaseFieldSetCharValue
(
FIELD_ID id,
const char *value,
int valueLength
);`

#### Description

Set the string field value.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID
const char * | value | value to set
int | valueLength | string length of value to set

### `radEventsInit()`

`EVENTS_ID radEventsInit
(
T_QUEUE_ID queueId,
UINT initialEvents,
void (*evtCallback) (UINT eventsRx, UINT data, void *parm),
void *userParm
);`

#### Description

Initialize events processing for this process - called once by each process (usually from radProcessInit). evtCallback will be called when an event(s) is signaled.

#### Return Value

Returns the valid EVENTS_ID or NULL

#### Notes

Events require an initialized message queue to deliver events.

#### Parameters

Type | Name | Description
T_QUEUE_ID | queueId | Valid queue ID for this process
UINT | initialEvents | Initial event mask of enabled events
void (*) | evtCallback | Callback function used to deliver events
void * | userParm | Data pointer delivered with events - use this to store work pointers for event processing

### `radEventsExit()`

`void radEventsExit (EVENTS_ID id);`

#### Description

Exits the events processing for this process. Usually called from radProcessExit.

#### Return Value

None

#### Parameters

Type | Name | Description
EVENTS_ID | id | Valid events system ID

### `radEventsAdd()`

`int radEventsAdd (EVENTS_ID id, UINT newEvents);`

#### Description

Add events to the receive mask.

#### Return Value

OK or ERROR

#### Notes

The receive mask is NOT replaced with this new mask but rather bitwise OR'd with the given mask.

#### Parameters

Type | Name | Description
EVENTS_ID | id | Valid events system ID
UINT | newEvents | mask of new events to "add"

### `radEventsRemove()`

`int radEventsRemove (EVENTS_ID id, UINT remEvents);`

#### Description

Remove events from the receive mask.

#### Return Value

OK or ERROR

#### Notes

The receive mask is NOT replaced with this new mask but rather bitwise AND'd with the compliment of the remEvents.

#### Parameters

Type | Name | Description
EVENTS_ID | id | Valid events system ID
UINT | remEvents | mask of events to "remove"

### `radEventsGetMask()`

`UINT radEventsGetMask (EVENTS_ID id);`

#### Description

Retrieve the current receive event mask. These are the events which, when received, will be delivered to the callback handler.

#### Return Value

The current receive event mask.

#### Parameters

Type | Name | Description
EVENTS_ID | id | Valid events system ID

### `radEventsSend()`

`int radEventsSend (EVENTS_ID id, char *destQName, UINT eventsToSend, UINT data);`

#### Description

Send an event(s) to another process by queue name.

#### Return Value

OK or ERROR

#### Notes

If radProcessInit was initialized and destName == NULL, sends the events to the calling process.

#### Parameters

Type | Name | Description
EVENTS_ID | id | Valid events system ID
char * | destQName | Queue name of the destination process
UINT | eventsToSend | Event mask of events to send
UINT | data | Data to be delivered with the events

### `radEventsProcess()`

`int radEventsProcess (EVENTS_ID id, UINT eventsRx, UINT data);`

#### Description

This routine should be called with the result mask of a received event "message". It is usually only called directly by radProcessWait.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
EVENTS_ID | id | Valid events system ID
UINT | eventsRx | Received events mask
UINT | data | Received event data

### `radListCreate()`

`RADLIST_ID radListCreate (void);`

#### Description

Dynamically creates a RADLIST structure and initializes it to empty.

#### Return Value

If successful, a valid RADLIST_ID to be used with all subsequent list methods. NULL is returned if there is an error.

### `radListReset()`

`RADLIST_ID radListReset (RADLIST_ID list);`

#### Description

Initializes the given list to empty.

#### Return Value

The RADLIST_ID passed in.

#### Parameters

Type | Name | Description
RADLIST_ID | list | list to initialize

### `radListDelete()`

`void radListDelete (RADLIST_ID list);`

#### Description

Deletes the memory associated with a dynamically allocated list. This should not be called if the list was allocated statically (i.e., declared as type RADLIST).

#### Return Value

None

#### Parameters

Type | Name | Description
RADLIST_ID | id | list ID to be destroyed

### `radListInsertAfter()`

`void radListInsertAfter
(
RADLIST_ID list,
NODE_PTR afterThisOne, /* NULL inserts at front */
NODE_PTR node
);`

#### Description

Inserts the new object referenced by node after the object referenced by afterThisOne.

#### Return Value

None

#### Notes

afterThisOne must already be in the list. List nodes CANNOT be inserted on multiple lists.

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest
NODE_PTR | afterThisOne | Existing list node to insert after
NODE_PTR | node | New node to insert into the list

### `radListInsertBefore()`

`void radListInsertBefore
(
RADLIST_ID list,
NODE_PTR beforeThisOne, /* NULL inserts at front */
NODE_PTR node
);`

#### Description

Inserts the new object referenced by node before the object referenced by beforeThisOne.

#### Return Value

None

#### Notes

beforeThisOne must already be in the list. List nodes CANNOT be inserted on multiple lists.

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest
NODE_PTR | beforeThisOne | Existing list node to insert before
NODE_PTR | node | New node to insert into the list

### `radListAddToFront()`

`void radListAddToFront
(
RADLIST_ID list,
NODE_PTR node
);`

#### Description

Inserts the new object referenced by node at the front of the list.

#### Return Value

None

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest
NODE_PTR | node | New node to insert into the list

### `radListAddToEnd()`

`void radListAddToEnd
(
RADLIST_ID list,
NODE_PTR node
);`

#### Description

Inserts the new object referenced by node at the end of the list.

#### Return Value

None

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest
NODE_PTR | node | New node to insert into the list

### `radListRemove()`

`void radListRemove
(
RADLIST_ID list,
NODE_PTR removeThisOne
);`

#### Description

Removes the node referenced by removeThisOne from the list.

#### Return Value

None

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest
NODE_PTR | removeThisOne | Node to remove from the list

### `radListRemoveFirst()`

`NODE_PTR radListRemoveFirst
(
RADLIST_ID list
);`

#### Description

Removes the first node from the list.

#### Return Value

If the list was not empty, the NODE_PTR of the first node is returned, otherwise NULL

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest

### `radListRemoveLast()`

`NODE_PTR radListRemoveLast
(
RADLIST_ID list
);`

#### Description

Removes the last node from the list.

#### Return Value

If the list was not empty, the NODE_PTR of the last node is returned, otherwise NULL

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest

### `radListGetNumberOfNodes()`

`int radListGetNumberOfNodes
(
RADLIST_ID list
);`

#### Description

Retrieves the number of nodes on the list.

#### Return Value

The number of nodes

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest

### `radListGetFirst()`

`NODE_PTR radListGetFirst
(
RADLIST_ID list
);`

#### Description

Retrieves the first node on the list. Does not remove it from the list.

#### Return Value

If the list is not empty, the first node on the list, otherwise NULL

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest

### `radListGetLast()`

`NODE_PTR radListGetLast
(
RADLIST_ID list
);`

#### Description

Retrieves the last node on the list. Does not remove the node from the list.

#### Return Value

If the list is not empty, the last node on the list, otherwise NULL

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest

### `radListGetNext()`

`NODE_PTR radListGetNext
(
RADLIST_ID list,
NODE_PTR afterThisOne /* NULL => listGetFirst */
);`

#### Description

Retrieves the node after the node referenced by afterThisOne from the list. Does not remove the node from the list.

#### Return Value

If afterThisOne is not the last node on the list, the next node on the list, otherwise NULL

#### Notes

If afterThisOne is NULL, this call is the same as radListGetFirst.

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest
NODE_PTR | afterThisOne | Node to retrieve after

### `radListGetPrevious()`

`NODE_PTR radListGetPrevious
(
RADLIST_ID list,
NODE_PTR beforeThisOne /* NULL => listGetLast */
);`

#### Description

Retrieves the node before the node referenced by beforeThisOne from the list. Does not remove the node from the list.

#### Return Value

If beforeThisOne is not the first node on the list, the next node on the list, otherwise NULL

#### Notes

If beforeThisOne is NULL, this call is the same as radListGetLast.

#### Parameters

Type | Name | Description
RADLIST_ID | list | List ID of interest
NODE_PTR | beforeThisOne | Node to retrieve before

### `radMsgLogInit()`

`int radMsgLogInit
(
char *procName,
int useStderr,
int timeStamp
);`

#### Description

Initializes logging for the calling process. Normally only called directly by radProcessInit.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
char * | procName | Process name to be displayed with messages
int | useStderr | If TRUE, will log to stderr as well as the system log
int | timeStamp | If TRUE, include millisecond timestamps with messages

### `radMsgLogExit()`

`int radMsgLogExit (void);`

#### Description

Exits the calling process from system logging capabilities. Normally only called directly by radProcessExit.

#### Return Value

OK or ERROR

### `radMsgLog()`

`int radMsgLog (int priority, char *format, ...);`

#### Description

Log a message - allow variable length parameter list.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
int | priority | PRI_STATUS, PRI_MEDIUM, ...
char * | format | format string ala printf
Variable | Variable | format arguments ala printf

### `radMsgLogData()`

`void radMsgLogData (void *data, int length);`

#### Description

Log data in a pointer dumping style. Displays hex and ASCII in a tabular form to the syslog.

#### Return Value

None

#### Parameters

Type | Name | Description
void * | data | pointer to dump from
int | length | Length (in bytes) of data to dump

### `radMsgRouterInit()`

`int radMsgRouterInit (char *workingDir)`

#### Description

Register the message router API for the calling process.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
char * | workingDir | specifies where the pid file and FIFOs for the message router process are maintained

### `radMsgRouterExit()`

`void radMsgRouterExit (void);`

#### Description

Deregister the message router API for the calling process

### `radMsgRouterProcessExit()`

`void radMsgRouterExit (int pid);`

#### Description

Deregister the message router API for "pid" process

### `radMsgRouterMessageRegister()`

`int radMsgRouterMessageRegister (ULONG msgID)`

#### Description

Request to receive 'msgID' messages.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
ULONG | msgID | specifies the msgID to be received - '0' and '0xFFFFFFFF' are reserved

### `radMsgRouterMessageDeregister()`

`int radMsgRouterMessageDeregister (ULONG msgID)`

#### Description

Request to stop receiving 'msgID' messages.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
ULONG | msgID | specifies the msgID to stop reception of - '0' and '0xFFFFFFFF' are reserved

### `radMsgRouterMessageIsRegistered()`

`int radMsgRouterMessageIsRegistered (ULONG msgID)`

#### Description

Request if any consumers are registered for 'msgID' messages.

#### Return Value

TRUE or FALSE

#### Parameters

Type | Name | Description
ULONG | msgID | specifies the msgID to query - '0' and '0xFFFFFFFF' are reserved

### `radMsgRouterMessageSend()`

`int radMsgRouterMessageSend
(
ULONG msgID,
void *msg,
ULONG byteLength
);`

#### Description

Send a message through the message router - all processes which have registered to receive 'msgID' will receive a copy of the message. 'msg' will be copied - ownership of 'msg' is NOT transferred but remains with the caller.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
ULONG | msgID | message ID to send
void * | msg | application message to send
ULONG | byteLength | byte length of 'msg'

### `radMsgRouterStatsDump()`

`void radMsgRouterStatsDump (void);`

#### Description

Request the message router to dump statistics to the log file.

### `radmrouted Daemon Usage`

    USAGE: [prefix]/radmrouted radSystemID workingDirectory [listenPort] [remoteIP:remotePort]

        radSystemID           1-255, same system ID used by other processes in this group
        workingDirectory      where to store FIFO and pid files for radmrouted
        listenPort            (optional) socket sever listen port to accept remote connections
        remoteIP:remotePort   (optional) remote host IP:port to connect to

### `radProcessInit()`

`int radProcessInit
(
char *processName,
char *queueName,
int numTimers,
int runAsDaemon,
void (*messageHandler)
(char *srcQueueName, UINT msgType, void *msg, UINT length, void *userData),
void (*eventHandler)
(UINT eventsRx, UINT rxData, void *userData),
void *userData
);`

#### Description

Initialize process management; called once during process initialization. Automatically sets up the following utilities for a new process: Message Logging (radmsgLog.h) Message Queue (radqueue.h) IO processing (ala "select") Timer List with 'numTimers' timers (radtimers.h) Event handler (radevents.h)

#### Return Value

OK or ERROR

#### Notes

This function should be called after radSystemInit.

#### Parameters

Type | Name | Description
char * | processName | Name of the calling process
char * | queueName | Full path name of the queue for this process
int | numTimers | Determines the max number of timers for this process
BOOL | runAsDaemon | Determines if the process can have a controlling terminal and if msgLog's go to stderr or not
void (*) | messageHandler | The callback for queue messages
void (*) | eventHandler | The callback for events
void * | userData | Passed to the event and message callbacks

### `radProcessExit()`

`void radProcessExit (void);`

#### Description

Exit from radlib process framework.

#### Return Value

None

#### Notes

This function should be called immediately before radSystemExit.

### `radProcessSetExitFlag()`

`void radProcessSetExitFlag (void);`

#### Description

Set the internal exit flag. radProcessWait will dump out immediately once this is set.

#### Return Value

None

### `radProcessWait()`

`int radProcessWait (int timeout);`

#### Description

Wait for messages, timers, events, and user IO blocks in one call. Blocks execution until input stimulus is available or timeout expires. This method should be the focal point of a process's main loop - often (and preferably) it is the only invocation in the main loop. If timeout (in milliseconds) is greater than 0, this function will return TIMEOUT even if no input stimulus triggered after timeout milliseconds.

#### Return Value

OK, ERROR, or TIMEOUT if timeout occurred

#### Parameters

Type | Name | Description
int | timeout | If 0, will wait indefinitely for input stimulus, otherwise will timeout after this number of milliseconds

### `radProcessGetName()`

`char *radProcessGetName (char *store);`

#### Description

Get the calling process's name.

#### Return Value

Returns the store pointer, where the name is copied.

#### Parameters

Type | Name | Description
char * | store | Character pointer to valid memory where the name is copied

### `radProcessGetPid()`

`pid_t radProcessGetPid (void);`

#### Description

Retrieve the calling process's pid (process ID).

#### Return Value

The calling process's pid

### `radProcessIORegisterDescriptor()`

`PROC_IO_ID radProcessIORegisterDescriptor
(
int fd,
void (*ioCallback) (int fd, void *userData),
void *userData
);`

#### Description

Register a file descriptor for radProcessWait inclusion. ioCallback will be executed if data or an error occurs on fd. userData will be passed to ioCallback.

#### Return Value

PROC_IO_ID or ERROR

#### Parameters

Type | Name | Description
int | fd | File descriptor to add to radProcessWait list
void (*) | ioCallback | Function called when data or error occurs on fd
void * | userData | This pointer is passed into ioCallback when data occurs

### `radProcessIODeRegisterDescriptor()`

`int radProcessIODeRegisterDescriptor (PROC_IO_ID id);`

#### Description

Deregister a file descriptor for radProcessWait inclusion.

#### Return Value

None

#### Parameters

Type | Name | Description
PROC_IO_ID | id | ID obtained during successful radProcessIORegisterDescriptor call

### `radProcessIORegisterSTDIN()`

`PROC_IO_ID radProcessIORegisterSTDIN
(
void (*ioCallback) (int fd, void *userData),
void *userData
);`

#### Description

Register STDIN for radProcessWait inclusion. This is a special case of radProcessIORegisterDescriptor.

#### Return Value

PROC_IO_ID or ERROR

#### Parameters

Type | Name | Description
void (*) | ioCallback | Function called when data or error occurs on fd
void * | userData | Passed to ioCallback

### `radProcessSignalCatchAll()`

`int radProcessSignalCatchAll (void (*defaultHandler) (int signum));`

#### Description

Initialize all signals (except SIGKILL and SIGSTOP) to be caught by defaultHandler.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
void (*) | defaultHandler | default signal handler

### `radProcessSignalCatch()`

`int radProcessSignalCatch (int signum, void (*handler) (int signum));`

#### Description

Assign a specific handler to a specific signal (signum).

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
int | signum | signal number
void (*) | handler | signal handler

### `radProcessSignalRelease()`

`int radProcessSignalRelease (int signum);`

#### Description

Set signum back to the default system handler.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
int | signum | signal number

### `radProcessSignalIgnore()`

`int radProcessSignalIgnore (int signum);`

#### Description

Set signum to be ignored when raised.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
int | signum | signal number

### `radProcessSignalGetHandler()`

`void (*(radProcessSignalGetHandler (int signum))) (int);`

#### Description

Retrieve the current handler for signum.

#### Return Value

The function pointer or NULL

#### Parameters

Type | Name | Description
int | signum | signal number

### `radProcessQueueGetName()`

`char *radProcessQueueGetName (char *store);`

#### Description

Retrieve calling process's queue name.

#### Return Value

Queue name (stored in store)

#### Parameters

Type | Name | Description
char * | store | where the queue name is copied

### `radProcessQueueAttach()`

`int radProcessQueueAttach (char *newName, int group);`

#### Description

Attach to an individual queue based on queue name so messages can be sent to it.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
char * | newName | Queue name to attach to
int | group | Group number of the queue

### `radProcessQueueDettach()`

`int radProcessQueueDettach (char *oldName, int group);`

#### Description

Detach from an individual queue based on queue name.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
char * | oldName | queue to detach from
int | group | Group number of queue

### `radProcessQueueJoinGroup()`

`int radProcessQueueJoinGroup (int groupNumber);`

#### Description

Add calling process's queue to a group and add the group to calling process's address list.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
int | groupNumber | Group to join

### `radProcessQueueQuitGroup()`

`int radProcessQueueQuitGroup (int groupNumber);`

#### Description

Remove calling process's queue from a group and remove a group from calling process's address list.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
int | groupNumber | Group to join

### `radProcessQueueSend()`

`int radProcessQueueSend (char *destQueue, UINT msgType, void *sysBuffer, UINT length);`

#### Description

Write to a queue. Assumes sysBuffer is a valid pointer to a system buffer. System buffer ownership is transferred to the receiving queue.

#### Return Value

OK, ERROR, or ERROR_ABORT if the destination queue is gone

#### Notes

Calling process should detach from the destination queue on ERROR_ABORT.

#### Parameters

Type | Name | Description
char * | destQueue | destination queue name
UINT | msgType | application-defined message type to send
void * | sysBuffer | system buffer to send
UINT | length | length of message to send

### `radProcessQueueSendGroup()`

`int radProcessQueueSendGroup (int destGroup, UINT msgType, void *sysBuffer, UINT length);`

#### Description

Write message to all queues in a group. Checks to make sure the group hasn't changed - if it has it refreshes the address list before sending. Assumes sysBuffer is a valid pointer to a system buffer.

#### Return Value

OK or ERROR

#### Notes

The system buffer is released if this call returns OK. Calling process must release if ERROR is returned.

#### Parameters

Type | Name | Description
int | destGroup | destination queue group
UINT | msgType | application-defined message type to send
void * | sysBuffer | system buffer to send
UINT | length | length of message to send

### `radProcessQueueIsAttached()`

`int radProcessQueueIsAttached (char *queueName);`

#### Description

Determine if calling process is attached to the given queue name.

#### Return Value

TRUE or FALSE

#### Parameters

Type | Name | Description
char * | queueName | destination queue

### `radProcessQueueKeepBuffer()`

`void radProcessQueueKeepBuffer (void);`

#### Description

ONLY called from inside a message queue handler to indicate that retention of the buffer is desired; if not called, the buffer will be released as usual after the last handler in the traversal list has been invoked. It is the caller's responsibility to free the buffer after assuming ownership of it.

#### Return Value

None

### `radProcessQueueStopHandlerList()`

`void radProcessQueueStopHandlerList (void);`

#### Description

ONLY called from inside a message queue handler - if more than one message queue handler has been defined via 'radProcessQueuePrependHandler', then this function is used to indicate that the traversal of the handler list should stop when the calling handler returns (i.e., the calling handler "matches" the message received).

#### Return Value

None

### `radProcessQueuePrependHandler()`

`int radProcessQueuePrependHandler
(
void (*msgHandler) (char *srcQueueName, UINT msgType, void *msg, UINT length, void *userData)
);`

#### Description

Prepend (insert at front) an additional message queue handler to the existing list of message handlers. This allows other utilities/objects/etc. to insert a message handler to process specific utility messages without the radlib application process having to have knowledge of those messages. This will not interrupt normal application message reception (although the utility/object doing the insertion should ensure that message types it is using do not conflict with the application message type definitions). This is completely backward compatible with existing radlib applications.

#### Return Value

A unique identifier > 0 that can be used to remove the message handler later (see 'radProcessQueueRemoveHandler') or ERROR

#### Parameters

Type | Name | Description
void (*) function pointer | msgHandler | message handler to be inserted at the front of the message handler list; should take arguments as described above

### `radProcessQueueRemoveHandler()`

`int radProcessQueueRemoveHandler (int handlerID);`

#### Description

Remove a message queue handler from the existing list of message handlers. 'handlerID must be a valid return value from a previous call to 'radProcessQueuePrependHandler' (this implies the default handler provided in 'radProcessInit' CANNOT be removed).

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
int | handlerID | a valid return value from a previous call to 'radProcessQueuePrependHandler'

### `radProcessTimerCreate()`

`TIMER_ID radProcessTimerCreate (TIMER_ID timer, void (*routine) (void *parm), void *parm);`

#### Description

Create a timer on the process's timer list.

#### Return Value

TIMER_ID or NULL if there is an error

#### Parameters

Type | Name | Description
TIMER_ID | timer | If not NULL, will re-initialize the given timer instead of creating a new one (pass NULL to create new one)
void (*) | routine | timer callback routine
void * | parm | pointer to be passed to the callback routine

### `radProcessTimerDelete()`

`void radProcessTimerDelete (TIMER_ID timer);`

#### Description

Delete the timer specified by timer.

#### Return Value

None

#### Parameters

Type | Name | Description
TIMER_ID | timer | timer to delete

### `radProcessTimerStart()`

`void radProcessTimerStart (TIMER_ID timer, int time);`

#### Description

Start the timer.

#### Return Value

None

#### Parameters

Type | Name | Description
TIMER_ID | timer | timer to start
int | time | duration of timer in milliseconds

### `radProcessTimerStop()`

`void radProcessTimerStop (TIMER_ID timer);`

#### Description

Stop a running timer before it expires.

#### Return Value

None

#### Parameters

Type | Name | Description
TIMER_ID | timer | timer to stop

### `radProcessTimerStatus()`

`int radProcessTimerStatus (TIMER_ID timer);`

#### Description

Determine if the given timer is running.

#### Return Value

TRUE or FALSE

#### Parameters

Type | Name | Description
TIMER_ID | timer | timer to status

### `radProcessTimerSetUserParm()`

`void radProcessTimerSetUserParm (TIMER_ID timer, void *newParm);`

#### Description

Reset the user parm (pointer passed to the callback) for a timer.

#### Return Value

None

#### Parameters

Type | Name | Description
TIMER_ID | timer | timer to modify
void * | newParm | new user parm

### `radProcessEventsAdd()`

`int radProcessEventsAdd (UINT newEvents);`

#### Description

Add events to the receive mask (see radEventsAdd).

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
UINT | newEvents | new events to receive

### `radProcessEventsRemove()`

`int radProcessEventsRemove (UINT removeEvents);`

#### Description

Remove events from the receive mask.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
UINT | removeEvents | events to remove from the receive mask

### `radProcessEventsGetEnabled()`

`UINT radProcessEventsGetEnabled (void);`

#### Description

Retrieve current receive mask.

#### Return Value

Receive mask

### `radProcessEventsSend()`

`int radProcessEventsSend (char *destName, UINT eventsToSend, UINT data);`

#### Description

Send event(s) to the destination process with queue name destName.

#### Return Value

OK or ERROR

#### Notes

If radProcessInit was initialized and destName == NULL, sends the events to the calling process.

#### Parameters

Type | Name | Description
char * | destName | destination queue name
UINT | eventsToSend | events to send
UINT | data | event data to send

### `radPlistCreate()`

`PROC_LIST_ID radPlistCreate (char *parentName);`

#### Description

Create a new, empty process list.

#### Return Value

PROC_LIST_ID or NULL

#### Parameters

Type | Name | Description
char * | parentName | Name of the parent process

### `radPlistDestroy()`

`int radPlistDestroy (PROC_LIST_ID plistId);`

#### Description

Destroy an existing process list (will clean up nodes).

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
PROC_LIST_ID | plistId | Process list ID to destroy

### `radPlistAdd()`

`int radPlistAdd
(
PROC_LIST_ID plistId,
int (*entry) (void *pargs),
void *args,
int priority
);`

#### Description

Add a new "entry" into an existing process list.

#### Return Value

OK or ERROR

#### Notes

When spawned, "entry" must call radProcessInit and then must give the synchronization semaphore by calling radPlistProcessReady or the parent process will hang forever waiting on it to do so. This semaphore is used to synchronize the launching of multiple processes.

#### Parameters

Type | Name | Description
PROC_LIST_ID | plistId | Process list ID
int (*) | entry | Entry point of process to launch
void * | args | Argument pointer passed to "entry" when launched
int | priority | Value of 1 - 100 indicating desired start position (1 is first, 100 is last)

### `radPlistStart()`

`int radPlistStart (PROC_LIST_ID plistId);`

#### Description

Start all process entries in an existing process list, ordered by priority (1 -> 100).

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
PROC_LIST_ID | plistId | process list to start

### `radPlistGetNumberRunning()`

`int radPlistGetNumberRunning (PROC_LIST_ID plistId);`

#### Description

Retrieve the number of running processes (after radPlistStart is called).

#### Return Value

The number of processes successfully started

#### Parameters

Type | Name | Description
PROC_LIST_ID | plistId | process list

### `radPlistExecByEntryPoint()`

`int radPlistExecByEntryPoint
(
PROC_LIST_ID plistId,
int (*entry) (void *pargs),
void (*execFunction) (pid_t pid, void *data),
void *data
);`

#### Description

Execute a user-supplied function for the process specified by "entry" (after radPlistStart is called).

#### Return Value

OK or ERROR

#### Notes

This allows the parent process to execute a function on the process pid of the process previously started with entry point "entry".

#### Parameters

Type | Name | Description
PROC_LIST_ID | plistId | process list
int (*) | entry | entry point of the process of interest
void (*) | execFunction | Function to execute if process denoted by "entry" is found
void * | data | void pointer to user-supplied data, passed to "execFunction"

### `radPlistExecAll()`

`int radPlistExecAll
(
PROC_LIST_ID plistId,
void (*execFunction) (pid_t pid, void *data),
void *data
);`

#### Description

Execute a user-supplied function for each running process in the process list (after radPlistStart is called).

#### Return Value

Count of affected processes or ERROR

#### Notes

This allows the parent process to execute a function on the process pid of each process in the process list.

#### Parameters

Type | Name | Description
PROC_LIST_ID | plistId | process list
void (*) | execFunction | Function to execute for each process in the list
void * | data | data pointer to pass to "execFunction"

### `radPlistAddPid()`

`int radPlistAddPid (PROC_LIST_ID plistId, pid_t pid);`

#### Description

Add a process entry to the list (not starting it). This may be done when a process is started after radPlistStart has been called to keep the list up to date.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
PROC_LIST_ID | plistId | process list
pid_t | pid | process ID to add

### `radPlistRemovePid()`

`int radPlistRemovePid (PROC_LIST_ID plistId, pid_t pid);`

#### Description

Remove a process entry from the list by pid. This may be done when it exits to keep the list up to date.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
PROC_LIST_ID | plistId | process list
pid_t | pid | process ID to remove

### `radPlistAddandStart()`

`int radPlistAddandStart
(
PROC_LIST_ID plistId,
int (*entry) (void *pargs),
void *args
);`

#### Description

Add a process entry to the list and start it. This may be done when a process is started after radPlistStart has been called to keep the list up to date.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
PROC_LIST_ID | plistId | process list
int (*) | entry | entry point of process to add and start
void * | args | arg pointer to pass to "entry"

### `radPlistProcessReady()`

`int radPlistProcessReady (void);`

#### Description

Signal to the parent process (from the newly started process) that initialization is complete and it is safe to start the next process.

#### Return Value

OK or ERROR

#### Notes

This method cannot be called until radProcessInit has been successfully called by the new process.

### `radPlistFindByEntryPoint()`

`int radPlistFindByEntryPoint
(
PROC_LIST_ID plistId,
int (*entry) (void *pargs)
);`

#### Description

Find an entry's pid based on its entry point.

#### Return Value

The process pid if found or ERROR if not

#### Notes

This cannot be called until radProcessInit has been successfully called by the new process.

#### Parameters

Type | Name | Description
PROC_LIST_ID | plistId | process list
int (*) | entry | entry point of process to find

### `radStartProcess()`

`int radStartProcess
(
int (*entryPoint) (void * pargs),
void *args
);`

#### Description

Start a new process by forking.

#### Return Value

The new child pid or ERROR

#### Notes

Usually only invoked directly by radPlist functions.

#### Parameters

Type | Name | Description
int (*) | entryPoint | entry point of process to start
void * | args | args to pass to the new process

### `radQueueSystemInit()`

`int radQueueSystemInit (int initFlag);`

#### Description

Initialize the process queue global constructs for this process. If initFlag is TRUE, the global table will be initialized too.

#### Return Value

OK or ERROR

#### Notes

Usually only invoked directly by radSystemInit. Must be called prior to radQueueInit.

#### Parameters

Type | Name | Description
int | initFlag | specify if the global table should be initialized

### `radQueueSystemExit()`

`void radQueueSystemExit (int destroy);`

#### Description

Exit the process attachment to the queue global constructs. If destroy is TRUE, the global table will be destroyed.

#### Return Value

None

#### Notes

Usually only invoked directly by radSystemExit.

#### Parameters

Type | Name | Description
int | destroy | specify if the global table should be destroyed

### `radQueueInit()`

`T_QUEUE_ID radQueueInit (char *queueName, int startDummyProc);`

#### Description

Create a message queue for the calling process. List the caller's new queue in the global queue list with the QUEUE_GROUP_ALL group.

#### Return Value

T_QUEUE_ID or NULL

#### Notes

Usually only invoked directly by radProcessInit. radQueueSystemInit must be called before this function.

#### Parameters

Type | Name | Description
char * | queueName | full path name of desired process queue

### `radQueueExit()`

`void radQueueExit (T_QUEUE_ID id);`

#### Description

Exit (detach from) the global queue table.

#### Return Value

None

#### Notes

Usually only invoked directly by radProcessExit.

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID

### `radQueueGetFD()`

`int radQueueGetFD
(
T_QUEUE_ID id
);`

#### Description

Get the queue file descriptor to use in select or poll calls.

#### Return Value

The file descriptor

#### Notes

Usually only invoked directly by radProcessInit.

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID

### `radQueueGetName()`

`char *radQueueGetName (T_QUEUE_ID tqid, char *store);`

#### Description

Return the full path of the calling process's queue.

#### Return Value

A pointer to store, which has been updated with the queue name

#### Notes

store must be large enough to hold a file path.

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID
char * | store | where to copy the result (must point to valid memory)

### `radQueueAttach()`

`int radQueueAttach (T_QUEUE_ID tqid, char *newName, int group);`

#### Description

Attach to an individual queue based on queue name so that messages can be sent to it.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID
char * | newName | full path to the queue to be attached
int | group | group number to attach through

### `radQueueDettach()`

`int radQueueDettach (T_QUEUE_ID tqid, char *oldName, int group);`

#### Description

Detach from an individual queue based on queue name and group number.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID
char * | newName | full path to the queue to be attached
int | group | group number to attach through

### `radQueueJoinGroup()`

`int radQueueJoinGroup (T_QUEUE_ID tqid, int groupNumber);`

#### Description

Add calling process's queue to a group and add the group to calling process's address list.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID
int | groupNumber | group number to join

### `radQueueQuitGroup()`

`int radQueueQuitGroup (T_QUEUE_ID tqid, int groupNumber);`

#### Description

Remove calling process's queue from a group and remove a group from calling process's address list.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID
int | groupNumber | group number to quit

### `radQueueRecv()`

`int radQueueRecv
(
T_QUEUE_ID tqid,
char *srcQueueName,
UINT *msgType,
void **msg,
UINT *length
);`

#### Description

Read from message queue - populates srcQueueName, msg, length, and msgType.

#### Return Value

TRUE if msg received, FALSE if queue is empty, ERROR if error

#### Notes

msg will point to a system buffer when this call returns TRUE. User MUST call radBufferRls when done with buffer! This is usually only invoked directly by radProcessWait, which will take care of buffer releases.

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID
char * | srcQueueName | A pointer to valid memory which will receive the name of the sending queue if a message is present
UINT * | msgType | A pointer to valid memory (UINT) which will receive the message type if a message is present
void ** | msg | The address of a void pointer which will receive the pointer to the system buffer if a message is present
UINT * | length | A pointer to valid memory (UINT) which will receive the length of the message if a message is present

### `radQueueSend()`

`int radQueueSend
(
T_QUEUE_ID tqid,
char *destQueueName,
UINT msgType,
void *sysBuffer,
UINT length
);`

#### Description

Write a message to a queue.

#### Return Value

OK, ERROR, or ERROR_ABORT if the destination queue is gone

#### Notes

Assumes sysBuffer is a valid pointer to a system buffer. System buffer ownership is transferred to the receiving queue. User should detach from a destination queue if ERROR_ABORT is returned.

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID
char * | destQueueName | Name of destination queue
UINT | msgType | Message type of message to send
void * | sysBuffer | System buffer containing message to send
UINT | length | Length of the message to send

### `radQueueSendGroup()`

`int radQueueSendGroup
(
T_QUEUE_ID tqid,
int destGroup,
UINT msgType,
void *sysBuffer,
UINT length
);`

#### Description

Send to all queues in a group - checks to make sure the group hasn't changed - if it has it refreshes the address list before sending.

#### Return Value

OK or ERROR

#### Notes

Assumes sysBuffer is a valid pointer to a system buffer. sysBuffer is released if this call returns OK, otherwise, the calling process must release the sysBuffer on ERROR.

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID
int | destGroup | Group number to send to
UINT | msgType | Message type of message to send
void * | sysBuffer | System buffer containing message to send
UINT | length | Length of the message to send

### `radQueueIsAttached()`

`int radQueueIsAttached (T_QUEUE_ID tqid, char *queueName);`

#### Description

Determine if calling process is attached to the given queue name.

#### Return Value

TRUE or FALSE

#### Parameters

Type | Name | Description
T_QUEUE_ID | id | queue ID
char * | queueName | queue name to check status of

### `radSemProcessInit()`

`int radSemProcessInit (void);`

#### Description

Called once during process initialization (usually from radSystemInit). Creates or attaches to an existing semaphore set.

#### Return Value

OK or ERROR

#### Notes

Usually only invoked directly by radSystemInit.

### `radSemSetDestroy()`

`void radSemSetDestroy (void);`

#### Description

Called globally once to destroy a semaphore set (usually from radSystemExit).

#### Return Value

None

#### Notes

Usually only invoked directly by radSystemExit.

### `radSemCreate()`

`SEM_ID radSemCreate (int semIndex, int count);`

#### Description

Create (or attach to) a specific indexed semaphore.

#### Return Value

SEM_ID or NULL

#### Parameters

Type | Name | Description
int | semIndex | semaphore index within the global semaphore set (1 - MAX_SEMAPHORES)
int | count | Indicates the initial value of the sem (0 or 1 for mutex). count less than 0 will leave the semaphore's count value undisturbed - (i.e. when it already exists)

### `radSemTake()`

`void radSemTake (SEM_ID id);`

#### Description

Take (decrement) a semaphore. If the semaphore count is 0 when this function is called, the calling process will block until the semaphore count is incremented (via radSemGive).

#### Return Value

None

#### Parameters

Type | Name | Description
SEM_ID | id | semaphore ID

### `radSemGive()`

`void radSemGive (SEM_ID id);`

#### Description

Give (increment) a semaphore's count. If other processes are blocked on the semaphore, this will cause one of them to unblock and run.

#### Return Value

None

#### Parameters

Type | Name | Description
SEM_ID | id | semaphore ID

### `radSemGiveMultiple()`

`void radSemGiveMultiple (SEM_ID id, int numToGive);`

#### Description

Give multiple (increment by numToGive) a semaphore's count. One or more blocked processes will be unblocked.

#### Return Value

None

#### Parameters

Type | Name | Description
SEM_ID | id | semaphore ID
int | numToGive | value to increment the semaphore count by

### `radSemTest()`

`int radSemTest (SEM_ID id);`

#### Description

Test a semaphore to see if it is free (unlocked), if so, take (decrement) the semaphore. If it is locked (count = 0), just return FALSE.

#### Return Value

TRUE if the semaphore was taken by this call (decremented), FALSE if the semaphore count is 0

#### Parameters

Type | Name | Description
SEM_ID | id | semaphore ID

### `radSemDelete()`

`int radSemDelete (SEM_ID id);`

#### Description

Release a semaphore allocation.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
SEM_ID | id | semaphore ID

### `radSemDebug()`

`void radSemDebug (void);`

#### Description

Dump semaphore set information to stdout.

#### Return Value

None

#### Notes

For debug use only.

### `radSHA1ComputeBlock()`

`int radSHA1ComputeBlock
(
void *block,
int byteLength,
char digestStore[RADSHA1_DIGEST_STR_LENGTH]
);`

#### Description

Compute the SHA-1 digest for the memory block 'block' of byte length 'byteLength' and store the result in 'digestStore'.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
void * | block | pointer to memory block to compute the SHA-1 digest over
int | byteLength | byte length of the block
char * | digestStore | character array of size >= RADSHA1_DIGEST_STR_LENGTH where the resulting digest is returned

### `radSHA1ComputeFile()`

`int radSHA1ComputeFile
(
char *filename,
char digestStore[RADSHA1_DIGEST_STR_LENGTH]
);`

#### Description

Compute the SHA-1 digest for the file given by full path and filename 'filename' and store the result in 'digestStore'.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
char * | filename | full path and name of file to compute the SHA-1 digest over
char * | digestStore | character array of size >= RADSHA1_DIGEST_STR_LENGTH where the resulting digest is returned

### `radSHA256ComputeBlock()`

`int radSHA256ComputeBlock
(
void *block,
int byteLength,
char digestStore[RADSHA256_DIGEST_STR_LENGTH]
);`

#### Description

Compute the SHA-256 digest for the memory block 'block' of byte length 'byteLength' and store the result in 'digestStore'.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
void * | block | pointer to memory block to compute the SHA-256 digest over
int | byteLength | byte length of the block
char * | digestStore | character array of size >= RADSHA256_DIGEST_STR_LENGTH where the resulting digest is returned

### `radSHA256ComputeFile()`

`int radSHA256ComputeFile
(
char *filename,
char digestStore[RADSHA256_DIGEST_STR_LENGTH]
);`

#### Description

Compute the SHA-256 digest for the file given by full path and filename 'filename' and store the result in 'digestStore'.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
char * | filename | full path and name of file to compute the SHA-256 digest over
char * | digestStore | character array of size >= RADSHA256_DIGEST_STR_LENGTH where the resulting digest is returned

### `radShmemIfExist()`

`int radShmemIfExist (int key);`

#### Description

Called from a process to test a shared memory block for existence.

#### Return Value

TRUE if it exists or FALSE if it doesn't

#### Parameters

Type | Name | Description
int | key | Unique 32-bit key value which identifies a shared memory block across process boundaries

### `radShmemInit()`

`SHMEM_ID radShmemInit (int key, int semIndex, int size);`

#### Description

Allocate or attach to existing shared memory block.

#### Return Value

SHMEM_ID or NULL

#### Parameters

Type | Name | Description
int | key | Unique 32-bit key value which identifies a shared memory block across process boundaries
int | semIndex | Unique semaphore index used globally to provide mutual exclusion for the shared memory block
int | size | size in bytes of the shared memory block

### `radShmemGet()`

`void *radShmemGet (SHMEM_ID id);`

#### Description

Get the pointer to the beginning of the shared block as it is represented in the calling process's virtual memory map.

#### Return Value

the pointer or NULL

#### Parameters

Type | Name | Description
SHMEM_ID | id | shared memory ID

### `radShmemLock()`

`void radShmemLock (SHMEM_ID id);`

#### Description

Lock the shared memory block for exclusive access. Can block execution if another process has the block locked.

#### Return Value

None

#### Parameters

Type | Name | Description
SHMEM_ID | id | shared memory ID

### `radShmemUnlock()`

`void radShmemUnlock (SHMEM_ID id);`

#### Description

Unlock a shared memory block.

#### Return Value

None

#### Parameters

Type | Name | Description
SHMEM_ID | id | shared memory ID

### `radShmemExit()`

`void radShmemExit (SHMEM_ID id);`

#### Description

Detach from a shared memory block. Does not destroy it.

#### Return Value

None

#### Parameters

Type | Name | Description
SHMEM_ID | id | shared memory ID

### `radShmemExitAndDestroy()`

`void radShmemExitAndDestroy (SHMEM_ID id);`

#### Description

Detach from and destroy the shared memory block.

#### Return Value

None

#### Notes

This marks the shared memory for destruction once the last process has detached from it. No new processes will be able to attach it once this call is made.

#### Parameters

Type | Name | Description
SHMEM_ID | id | shared memory ID

### `radSocketServerCreate()`

`RADSOCK_ID radSocketServerCreate (int port);`

#### Description

Create a socket server to listen on port "port".

#### Return Value

RADSOCK_ID or NULL if there is an error

#### Notes

This provides the "Server" side of the Client-Server paradigm. Once created, the user will need to add the listen socket file descriptor (obtained via radSocketGetDescriptor) to your FD_SET to wait for connect notifications on the listen socket. New connections are completed by use of radSocketServerAcceptConnection, which accepts the connection and prepares the new socket for read/write activity.

#### Parameters

Type | Name | Description
int | port | TCP port number to listen for connections on

### `radSocketServerAcceptConnection()`

`RADSOCK_ID radSocketServerAcceptConnection (RADSOCK_ID listenServerID);`

#### Description

Create a new socket instance for the incoming connection and prepare it for read/write activity.

#### Return Value

The new RADSOCK_ID for the client connection or NULL if there is an error

#### Notes

Should be called when there is a "wake up" on the listen socket indicating an incoming connection attempt.

#### Parameters

Type | Name | Description
RADSOCK_ID | listenServerID | Valid listen socket ID obtained from a successful call to radSocketServerCreate

### `radSocketClientCreate()`

`RADSOCK_ID radSocketClientCreate (char *hostNameOrIP, int port);`

#### Description

Create a socket client that connects to "hostNameOrIP" on port "port". Once connected, prepares the socket for read/write activity.

#### Return Value

The new RADSOCK_ID or NULL if there is an error

#### Notes

This provides the "Client" side of the Client-Server paradigm.

#### Parameters

Type | Name | Description
char * | hostNameOrIP | Host name or IP address of the socket server to be connected
int | port | Port the socket server is listening on

### `radSocketClientCreateAny()`

`RADSOCK_ID radSocketClientCreateAny (char *hostNameOrIP, int port);`

#### Description

Create a socket client that connects to "hostNameOrIP" on port "port". if "hostNameOrIP" resolves to multiple IP addresses (via getaddrinfo), each IP address will be tried until a connection is achieved in the order received from getaddrinfo; Once connected, prepares the socket for read/write activity.

#### Return Value

The new RADSOCK_ID or NULL if there is an error

#### Notes

This provides the "Client" side of the Client-Server paradigm.

#### Parameters

Type | Name | Description
char * | hostNameOrIP | Host name or IP address of the socket server to be connected
int | port | Port the socket server is listening on

### `radSocketDestroy()`

`int radSocketDestroy (RADSOCK_ID id);`

#### Description

Close connection and cleanup resources.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
RADSOCK_ID | id | Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate

### `radSocketGetDescriptor()`

`int radSocketGetDescriptor (RADSOCK_ID id);`

#### Description

Get the socket descriptor (for select calls, etc.).

#### Return Value

The socket descriptor associated with "id".

#### Parameters

Type | Name | Description
RADSOCK_ID | id | Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate

### `radSocketGetHost()`

`char *radSocketGetHost (RADSOCK_ID id);`

#### Description

Get the socket hostname or IP.

#### Return Value

The hostname or IP address associated with "id".

#### Parameters

Type | Name | Description
RADSOCK_ID | id | Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate

### `radSocketGetPort()`

`int radSocketGetPort (RADSOCK_ID id);`

#### Description

Get the socket hostname or IP.

#### Return Value

The socket port number associated with "id".

#### Notes

For listen sockets this is the listen port. For accepted client connections on a server this is the local port of the client connection. For pure client connections this is the local port of the connection.

#### Parameters

Type | Name | Description
RADSOCK_ID | id | Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate

### `radSocketReadExact()`

`int radSocketReadExact
(
RADSOCK_ID id,
void *buffer,
int lengthToRead
);`

#### Description

Read an exact size (will block if a blocking socket).

#### Return Value

Bytes read or ERROR if an error occurs.

#### Notes

Will return less than requested amount if a non-blocking socket and the read would block or it is interrupted by a received signal.

#### Parameters

Type | Name | Description
RADSOCK_ID | id | Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate
void * | buffer | User buffer pointing to valid memory of size >= "lengthToRead" bytes where data is written
int | lengthToRead | Bytes to read

### `radSocketWriteExact()`

`int radSocketWriteExact
(
RADSOCK_ID id,
void *buffer,
int lengthToWrite
);`

#### Description

Write an exact size (will block if a blocking socket).

#### Return Value

Bytes written or ERROR if an error occurs.

#### Notes

Will return less than requested amount if a non-blocking socket and the write would block or it is interrupted by a received signal.

#### Parameters

Type | Name | Description
RADSOCK_ID | id | Valid socket ID obtained from a successful call to radSocketServerCreate, radSocketServerAcceptConnection or radSocketClientCreate
void * | buffer | User buffer pointing to the data to be written
int | lengthToWrite | Bytes to write

### `radSocketSetBlocking()`

`int radSocketSetBlocking
(
RADSOCK_ID id,
int isBlocking
);`

#### Description

Set the socket for blocking or non-blocking IO.

#### Return Value

OK or ERROR

#### Notes

By default, all socket types are created in blocking IO mode. It is the user's responsibility to handle blocking/non-blocking IO properly (EAGAIN and EINTR errno's). Non-blocking should NOT be set for server (listen) sockets.

#### Parameters

Type | Name | Description
RADSOCK_ID | id | Valid socket ID obtained from a successful call to radSocketServerAcceptConnection or radSocketClientCreate
int | isBlocking | Boolean indicating if the socket should be set to non-blocking (non-zero value) or blocking IO (0 value, default)

### `radSocketSetDebug()`

`void radSocketSetDebug
(
RADUDPSOCK_ID id,
int enable
);`

#### Description

Turn on or off data debug which dumps all read/write data to radMsgLog.

#### Return Value

N/A

#### Notes

If enabled, debug will radMsgLog the contents of all RX/TX data.

#### Parameters

Type | Name | Description
RADSOCK_ID | id | Valid socket ID obtained from a successful call to radSocketCreate
int | enable | Boolean indicating if the debug dumping of RX/TX datagrams should be enabled or disabled

### `radSortListInit()`

`SORTLIST_ID radSortListInit (int (*getKey)(void *data));`

#### Description

Create a sorted list. The getKey function should return an "ordinal" value given a pointer to the list node - this is used to sort the list. If getKey is NULL, this will use the address of the NODE_PTR (not very useful!) This allows the calling process to specify "how" to sort the elements of the list through the getKey function.

#### Return Value

SORTLIST_ID or NULL

#### Parameters

Type | Name | Description
int (*) | getKey | application-supplied sorting function

### `radSortListExit()`

`void radSortListExit (SORTLIST_ID id);`

#### Description

This WILL free all nodes on the sorted list before destroying the list.

#### Return Value

None

#### Parameters

Type | Name | Description
SORTLIST_ID | id | sorted list ID

### `radSortListInsert()`

`int radSortListInsert (SORTLIST_ID id, NODE_PTR node);`

#### Description

Insert node into the list (see radList for details on NODE_PTR type).

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
SORTLIST_ID | id | sorted list ID
NODE_PTR | node | object to be inserted (in order) into the list

### `radSortListRemove()`

`int radSortListRemove (SORTLIST_ID id, NODE_PTR node);`

#### Description

Find and remove the node given the NODE_PTR.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
SORTLIST_ID | id | sorted list ID
NODE_PTR | node | object pointer to remove

### `radSortListFind()`

`NODE_PTR radSortListFind (SORTLIST_ID id, int key);`

#### Description

Find a NODE_PTR given the "ordinal" or "key" of the node.

#### Return Value

The NODE_PTR or NULL

#### Parameters

Type | Name | Description
SORTLIST_ID | id | sorted list ID
int | key | the ordinal value (as determined by getKey) of the object to find

### `radsqliteOpen()`

`DATABASE_ID radsqliteOpen
(
const char *dbFilePath
);`

#### Description

Connect to a database server.

#### Return Value

Returns the DATABASE_ID or NULL

#### Parameters

Type | Name | Description
const char * | dbFilePath | Full path and name of the SQLite database file

### `radsqliteClose()`

`void radsqliteClose
(
DATABASE_ID dbId
);`

#### Description

Close the connection to a database file.

#### Return Value

None

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call

### `radsqliteQuery()`

`int radsqliteQuery
(
DATABASE_ID dbId,
const char *query,
int createResults
);`

#### Description

Issue an SQL query against the database.

#### Return Value

Returns OK or ERROR if there is a db error, query error, or 'createResults' is set to TRUE and no result set is generated by the 'query'.

#### Notes

If results are generated it can be VERY slow and eat up a lot of heap space; the good news is that once the RESULT_SET_ID is retrieved using radsqliteTableGetResults, it can persist as long as the user needs to keep it without adverse effects on the database server or the radlib host system.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
const char * | query | Well-formed SQL query statement
int | createResults | flag indicating if a result set should be generated

### `radsqliteGetResults()`

`RESULT_SET_ID radsqliteGetResults
(
DATABASE_ID dbId
);`

#### Description

Retrieve the result set (if there is one) - should be called immediately after radsqliteTableQuery if the query was intended to generate a result set (SELECT, SHOW, etc.).

#### Return Value

Returns RESULT_SET_ID or NULL

#### Notes

RESULT_SET_ID should be released via radsqliteTableResultsRelease once the user is finished with it.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call

### `radsqliteRefreshResults()`

`RESULT_SET_ID radsqliteRefreshResults
(
DATABASE_ID dbId,
RESULT_SET_ID origResultSet
);`

#### Description

Refresh a result set based on the original query.

#### Return Value

Returns RESULT_SET_ID or NULL

#### Notes

RESULT_SET_ID should be released via radsqliteTableResultsRelease once the user is finished with it.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
RESULT_SET_ID | origResultSet | original result set returned by radsqliteGetResults

### `radsqliteReleaseResults()`

`void radsqliteReleaseResults
(
DATABASE_ID dbId,
RESULT_SET_ID resultSet
);`

#### Description

Release a result set.

#### Return Value

None

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
RESULT_SET_ID | resultSet | result set returned by radsqliteGetResults

### `radsqliteTableIfExists()`

`int radsqliteTableIfExists
(
DATABASE_ID dbId,
const char tableName );`

#### Description

Does 'tableName' table exist?

#### Return Value

Returns TRUE or FALSE

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
const char * | tableName | name of table to check for existence

### `radsqliteTableCreate()`

`int radsqliteTableCreate
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowDescription /* see radsqliteRowDescriptionCreate */
);`

#### Description

Create a table named 'tableName'.

#### Return Value

Returns OK or ERROR

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
const char * | tableName | name of table to be created
ROW_ID | rowDescription | describes the row structure for the new table (see radsqliteRowDescriptionCreate)

### `radsqliteTableDelete()`

`int radsqliteTableDelete
(
DATABASE_ID dbId,
const char *tableName
);`

#### Description

Drop the table named 'tableName'.

#### Return Value

Returns OK or ERROR

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
const char * | tableName | name of table to be deleted

### `radsqliteTableTruncate()`

`int radsqliteTableTruncate
(
DATABASE_ID dbId,
const char *tableName
);`

#### Description

Truncate (empty) the table named 'tableName'.

#### Return Value

Returns OK or ERROR

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
const char * | tableName | name of table to be truncated

### `radsqliteTableDescriptionGet()`

`ROW_ID radsqliteTableDescriptionGet
(
DATABASE_ID dbId,
const char *tableName`

#### Description

Create a row description to use for row insertion/retrieval.

#### Return Value

Returns ROW_ID or NULL

#### Notes

The ROW_ID must be deleted with radsqliteRowDescriptionDelete after the user is finished with it. Sets the FIELD_VALUE_IS_NULL bit in field->type for all fields - this means the user must clear this bit for field values to be used in queries/insertions/deletions (see the radsqliteFieldSetXXXValue functions, which clear the FIELD_VALUE_IS_NULL bit for you).

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
const char * | tableName | retrieve the row description for this table

### `radsqliteTableQueryRow()`

`RESULT_SET_ID radsqliteTableQueryRow
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowDescription
);`

#### Description

Query a table to create a result set given a row description.

#### Return Value

Returns RESULT_SET_ID or NULL

#### Notes

Columns to be included in the result set should have FIELD_DISPLAY set in the appropriate FIELD_ID.type within 'rowDescription'; columns NOT to be included in the WHERE clause should have FIELD_VALUE_IS_NULL set in FIELD_ID.type; fields in the where clause are 'ANDed' together. Can be slow and eat up a lot of heap space - the good news is that once the RESULT_SET_ID is retrieved, it can persist as long as the user needs to keep it without adverse effects on the db server or the radlib host. RESULT_SET_ID should be released via radsqliteTableResultsRelease once the user is finished with it. Only the populated fields in 'rowDescription' will be used to match records in the table (i.e., multiple rows can be matched).

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
const char * | tableName | table to query
ROW_ID | rowDescription | description with fields of interest populated

### `radsqliteTableInsertRow()`

`int radsqliteTableInsertRow
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID rowId
);`

#### Description

Insert a row into a table.

#### Return Value

Returns OK or ERROR

#### Notes

'rowId' is created with radsqliteTableDescriptionGet then field values were populated with radsqliteFieldGet, radsqliteFieldSetXXXValue, etc. prior to this call. If a 'NOT NULL' field in the table has a NULL value in rowId, it's an error.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
const char * | tableName | table to insert the row into
ROW_ID | rowId | row description with fields of interest populated

### `radsqliteTableModifyRows()`

`int radsqliteTableModifyRows
(
DATABASE_ID dbId,
const char *tableName,
ROW_ID matchId,
ROW_ID newData
);`

#### Description

Modify rows in 'tableName' matching 'matchId' with the field values defined in 'newData'.

#### Return Value

Returns OK or ERROR

#### Notes

Only the non-NULL fields in 'matchId' will be used to match records in the table (i.e., multiple rows can be matched). All fields in 'newData' will be updated in the rows which match 'matchId'- if a NULL value is given for a NOT NULL field in the table it is an error. Thus if you don't want to modify a column value, remove it from the 'newData' row desription with radsqliteRowDescriptionRemoveField.

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
const char * | tableName | table to modify
ROW_ID | matchId | row description with fields to match populated
ROW_ID | newData | row description with ONLY fields to be modified present

### `radsqliteTableDeleteRows()`

`int radsqliteTableDeleteRows
(
DATABASE_ID id
);`

#### Description

Delete rows in 'tableName' matching 'matchId'.

#### Return Value

Returns OK or ERROR

#### Notes

Only the non-NULL fields will be used to match records in the table (i.e., multiple rows can be matched).

#### Parameters

Type | Name | Description
DATABASE_ID | dbId | Value returned from successful radsqliteOpen call
ROW_ID | matchId | row description with fields to match populated

### `radsqliteResultsGetFirst()`

`ROW_ID radsqliteResultsGetFirst
(
RESULT_SET_ID id
);`

#### Description

Retrieve the first row of a result set.

#### Return Value

Returns ROW_ID or NULL if the result set is empty

#### Notes

Allows traversal of the rows in a result set.

#### Parameters

Type | Name | Description
RESULT_SET_ID | id | result set obtained from radsqliteGetResults or radsqliteTableQueryRow

### `radsqliteResultsGetNext()`

`ROW_ID radsqliteResultsGetNext
(
RESULT_SET_ID id
);`

#### Description

Retrieve the next row of a result set.

#### Return Value

Returns ROW_ID or NULL if there is no next row

#### Notes

Allows traversal of the rows in a result set.

#### Parameters

Type | Name | Description
RESULT_SET_ID | id | result set obtained from radsqliteGetResults or radsqliteTableQueryRow

### `radsqliteResultsGetPrev()`

`ROW_ID radsqliteResultsGetPrev
(
RESULT_SET_ID id
);`

#### Description

Retrieve the previous row of a result set.

#### Return Value

Returns ROW_ID or NULL if there is no previous row

#### Notes

Allows traversal of the rows in a result set.

#### Parameters

Type | Name | Description
RESULT_SET_ID | id | result set obtained from radsqliteGetResults or radsqliteTableQueryRow

### `radsqliteResultsGetLast()`

`ROW_ID radsqliteResultsGetLast
(
RESULT_SET_ID id
);`

#### Description

Retrieve the last row of a result set.

#### Return Value

Returns ROW_ID or NULL if the result set is empty

#### Notes

Allows traversal of the rows in a result set.

#### Parameters

Type | Name | Description
RESULT_SET_ID | id | result set obtained from radsqliteGetResults or radsqliteTableQueryRow

### `radsqliteRowDescriptionCreate()`

`ROW_ID radsqliteRowDescriptionCreate
(
void
);`

#### Description

Create an empty row description to use when describing a new table.

#### Return Value

Returns ROW_ID or NULL

#### Notes

ROW_ID should be released via radsqliteRowDescriptionDelete once the user is finished with it.

### `radsqliteRowDescriptionAddField()`

`int radsqliteRowDescriptionAddField
(
ROW_ID id,
const char *name,
UINT type,
int maxLength
);`

#### Description

Add a new field to a row description.

#### Return Value

Returns OK or ERROR

#### Parameters

Type | Name | Description
ROW_ID | id | Value returned from successful radsqliteRowDescriptionCreate call
const char * | name | name of the field to add
UINT | type | type of field to add (see radatabase.h)
int | maxLength | maximum length of field to add if it is a string

### `radsqliteRowDescriptionRemoveField()`

`int radsqliteRowDescriptionRemoveField
(
ROW_ID id,
const char *name
);`

#### Description

Remove a field identified by 'name' from the row description.

#### Return Value

Returns OK or ERROR

#### Parameters

Type | Name | Description
ROW_ID | id | Value returned from successful radsqliteRowDescriptionCreate call
const char * | name | name of field to be removed

### `radsqliteRowDescriptionDelete()`

`void radsqliteRowDescriptionDelete
(
ROW_ID id
);`

#### Description

Release a row description and the corresponding fields.

#### Return Value

None

#### Parameters

Type | Name | Description
ROW_ID | id | Value returned from successful radsqliteRowDescriptionCreate call

### `radsqliteFieldGet()`

`FIELD_ID radsqliteFieldGet
(
ROW_ID id,
const char *fieldName
);`

#### Description

Get the field identified by 'fieldName'.

#### Return Value

Returns FIELD_ID or NULL

#### Parameters

Type | Name | Description
ROW_ID | id | valid row description ID
const char * | fieldName | name of field to retrieve

### `radsqliteFieldGetType()`

`UINT radsqliteFieldGetType
(
DATABASE_ID id
);`

#### Description

Retrieve the field type bitmask (see radsqlite.h).

#### Return Value

Returns the field type bitmask

#### Notes

enum DbFieldTypes { FIELD_STRING = 0x00000001, FIELD_BIGINT = 0x00000002, FIELD_DOUBLE = 0x00000004, FIELD_TYPE_CLEAR = 0xFF000000, /* used to clear field type only */ FIELD_VALUE_IS_NULL = 0x80000000, /* for queries & results only */ FIELD_DISPLAY = 0x40000000 /* for queries only */ };

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID to retrieve type from

### `radsqliteFieldGetBigIntValue()`

`long long radsqliteFieldGetBigIntValue
(
FIELD_ID id
);`

#### Description

Retrieve the big integer value of the field (must be of type FIELD_BIGINT).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `radsqliteFieldGetDoubleValue()`

`double radsqliteFieldGetDoubleValue
(
DATABASE_ID id
);`

#### Description

Retrieve the double value of the field (must be of type FIELD_DOUBLE).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `radsqliteFieldGetCharValue()`

`char *radsqliteFieldGetCharValue
(
FIELD_ID id
);`

#### Description

Retrieve the string value of the field (must be of type FIELD_STRING).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `radsqliteFieldGetCharLength()`

`int radsqliteFieldGetCharLength
(
FIELD_ID id
);`

#### Description

Retrieve the string length of the field (must be of type FIELD_STRING).

#### Return Value

Returns the value

#### Parameters

Type | Name | Description
FIELD_ID | id | field to extract value from

### `radsqliteFieldSetTypeBigInt()`

`int radsqliteFieldSetTypeBigInt
(
FIELD_ID id
);`

#### Description

Set the field type to FIELD_BIGINT.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `radsqliteFieldSetTypeDouble()`

`int radsqliteFieldSetTypeDouble
(
FIELD_ID id
);`

#### Description

Set the field type to FIELD_DOUBLE.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `radsqliteFieldSetTypeChar()`

`int radsqliteFieldSetTypeChar
(
FIELD_ID id
);`

#### Description

Set the field type to FIELD_STRING.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `radsqliteFieldSetToNull()`

`int radsqliteFieldSetToNull
(
FIELD_ID id
);`

#### Description

Set the field flag to NULL (empty).

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `radsqliteFieldSetToNotNull()`

`int radsqliteFieldSetToNotNull
(
FIELD_ID id
);`

#### Description

Set the field flag to NOT NULL (not empty).

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID

### `radsqliteFieldSetBigIntValue()`

`int radsqliteFieldSetBigIntValue
(
FIELD_ID id,
long long value
);`

#### Description

Set the big integer field value.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID
long long | value | value to set

### `radsqliteFieldSetDoubleValue()`

`int radsqliteFieldSetDoubleValue
(
FIELD_ID id,
double value
);`

#### Description

Set the double field value.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID
double | value | value to set

### `radsqliteFieldSetCharValue()`

`int radsqliteFieldSetCharValue
(
FIELD_ID id,
const char *value,
int valueLength
);`

#### Description

Set the string field value.

#### Return Value

Returns OK

#### Parameters

Type | Name | Description
FIELD_ID | id | valid field ID
const char * | value | value to set
int | valueLength | string length of value to set

### `radStackInit()`

`STACK_ID radStackInit (void);`

#### Description

Create a an empty stack.

#### Return Value

STACK_ID or NULL

### `radStackExit()`

`void radStackExit (STACK_ID id);`

#### Description

Delete a stack, freeing all the nodes as well.

#### Return Value

None

#### Parameters

Type | Name | Description
STACK_ID | id | stack ID

### `radStackPush()`

`int radStackPush (STACK_ID id, STACK_NODE *newNode);`

#### Description

Push an object onto the stack.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
STACK_ID | id | stack ID
STACK_NODE | newNode | New object to push onto the stack

### `radStackPop()`

`STACK_NODE *radStackPop (STACK_ID id);`

#### Description

Pop an object off the stack.

#### Return Value

STACK_NODE or NULL if the stack is empty

#### Parameters

Type | Name | Description
STACK_ID | id | stack ID

### `radStackCount()`

`int radStackCount (STACK_ID id);`

#### Description

Get the count of objects on the stack.

#### Return Value

Stack count

#### Parameters

Type | Name | Description
STACK_ID | id | stack ID

### `radStatesInit()`

`STATES_ID radStatesInit (void *saveData);`

#### Description

Create and initialize a state machine.

#### Return Value

STATES_ID or NULL

#### Notes

State values MUST be 0-based and contiguous.

#### Parameters

Type | Name | Description
void * | saveData | application-specific data pointer that will be passed into all state handlers by radStatesProcess

### `radStatesExit()`

`void radStatesExit (STATES_ID id);`

#### Description

Destroy a state machine.

#### Return Value

None

#### Parameters

Type | Name | Description
STATES_ID | id | state machine ID

### `radStatesAddHandler()`

`int radStatesAddHandler
(
STATES_ID id,
int state,
int (*handler) (int state, void *stimulus, void *userData)
);`

#### Description

Add a state processor to the state machine. state MUST be < STATE_MAX_STATES defined in radstates.h.

#### Return Value

OK or ERROR

#### Notes

handler must ALWAYS return the next state of the machine.

#### Parameters

Type | Name | Description
STATES_ID | id | state machine ID
int | state | the specific state to which "handler" is assigned
int (*) | handler | state machine handler for the state "state"

### `radStatesRemHandler()`

`int radStatesRemHandler (STATES_ID id, int state);`

#### Description

Remove a processor (resets the handler to the stub handler).

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
STATES_ID | id | state machine ID
int | state | the state to remove the assigned handler for

### `radStatesProcess()`

`void radStatesProcess (STATES_ID id, void *stimulus);`

#### Description

Process an application-defined stimulus. Stimuli can be messages, timers, events, file descriptors, etc.

#### Return Value

None

#### Parameters

Type | Name | Description
STATES_ID | id | state machine ID
void * | stimulus | application-defined stimulus pointer which is passed into the active state's handler

### `radStatesSetState()`

`int radStatesSetState (STATES_ID id, int state);`

#### Description

Change the state of the machine

#### Return Value

OK or ERROR

#### Notes

Usually only invoked during state machine initialization. When called from within a state machine handler, bad side-effects can occur.

#### Parameters

Type | Name | Description
STATES_ID | id | state machine ID
int | state | new state for the state machine

### `radStatesGetState()`

`int radStatesGetState (STATES_ID id);`

#### Description

Get the currently active state of the machine.

#### Return Value

current state of the state machine

#### Parameters

Type | Name | Description
STATES_ID | id | state machine ID

### `radStatesReset()`

`void radStatesReset (STATES_ID id, void *saveData);`

#### Description

Reset all handlers to the stub handler and set the new user data to saveData.

#### Return Value

None

#### Parameters

Type | Name | Description
STATES_ID | id | state machine ID
void * | saveData | new user data for the state machine

### `radSystemInit()`

`int radSystemInit (UCHAR systemID);`

#### Description

Initialize a unique radlib system and/or register the calling process within an existing radlib system.

#### Return Value

OK or ERROR

#### Notes

All processes within a radlib system must call this method before calling radProcessInit. If this is the first process in the system to call this, system facilities will be created and initialized, otherwise this will just register the process with existing system facilities. Care must be taken that all processes within a given radlib system use the same unique systemID. Thus unrelated radlib systems can run concurrently by using different system IDs for initialization. This function must be called before calling radProcessInit.

#### Parameters

Type | Name | Description
UCHAR | systemID | the unique system ID for the calling process (or processes) - system IDs are limited to the range 0-255

### `radSystemExit()`

`int radSystemExit (UCHAR systemID);`

#### Description

Deregister the calling process from a unique radlib system and destroy all facilities if it is the last process left in the radlib system.

#### Return Value

OK or ERROR

#### Notes

Care must be taken that all processes within a given radlib system use the same unique systemID. This function must be called after calling radProcessExit.

#### Parameters

Type | Name | Description
UCHAR | systemID | the unique system ID for the calling process (or processes) - system IDs are limited to the range 0-255

### `radSystemGetUpTimeMS()`

`ULONG radSystemGetUpTimeMS (UCHAR systemID);`

#### Description

Returns the number of milliseconds since radSystemInit was first called with this "systemID".

#### Return Value

Number of milliseconds since radSystemInit was first called with this "systemID"

#### Notes

Care must be taken that all processes within a given radlib system use the same unique systemID. This function may be called after calling radSystemInit.

#### Parameters

Type | Name | Description
UCHAR | systemID | the unique system ID for the calling process (or processes) - system IDs are limited to the range 0-255

### `radSystemGetUpTimeSEC()`

`ULONG radSystemGetUpTimeSEC (UCHAR systemID);`

#### Description

Returns the number of seconds since radSystemInit was first called with this "systemID".

#### Return Value

Number of seconds since radSystemInit was first called with this "systemID"

#### Notes

Care must be taken that all processes within a given radlib system use the same unique systemID. This function may be called after calling radSystemInit.

#### Parameters

Type | Name | Description
UCHAR | systemID | the unique system ID for the calling process (or processes) - system IDs are limited to the range 0-255

### `radSystemGetUpTimeSTR()`

`char *radSystemGetUpTimeSTR (UCHAR systemID);`

#### Description

Returns a string of the form: "Y years, M months, D days, H hours, m minutes, S seconds" which represents the time since radSystemInit was first called with this "systemID".

#### Return Value

The up time string

#### Notes

Care must be taken that all processes within a given radlib system use the same unique systemID. This function may be called after calling radSystemInit. This call is not reentrant and successive calls will overwrite the static buffer contents.

#### Parameters

Type | Name | Description
UCHAR | systemID | the unique system ID for the calling process (or processes) - system IDs are limited to the range 0-255

### `radthreadCreate()`

`RAD_THREAD_ID radthreadCreate ( void (*ThreadEntry)(RAD_THREAD_ID threadId, void* threadData), void* threadData );`

#### Description

Create and start a thread.

#### Return Value

the new RAD_THREAD_ID or NULL if not successful

#### Notes

See the header file radthread.h for more details.

#### Parameters

Type | Name | Description
void (*)(RAD_THREAD_ID threadId, void* threadData) | ThreadEntry | Thread entry function
void* | threadData | User-defined data passed to the thread entry function

### `radthreadWaitExit()`

`void radthreadWaitExit(RAD_THREAD_ID threadId);`

#### Description

Set the exit flag and wait for the thread described by threadId to exit.

#### Return Value

N/A

#### Notes

Will block until the thread terminates.

#### Parameters

Type | Name | Description
RAD_THREAD_ID | threadId | unique thread ID

### `radthreadSendToThread()`

`int radthreadSendToThread ( RAD_THREAD_ID threadId, int type, void* data, int length );`

#### Description

Send data (thread safe) to the thread described by threadId.

#### Return Value

OK or ERROR

#### Notes

Uses internal mutex and condition variable to provide thread safe delivery and notification.

#### Parameters

Type | Name | Description
RAD_THREAD_ID | threadId | unique thread ID
int | type | user-defined value (typically a message ID)
void* | data | pointer to the data to be sent; data is copied, ownership not transferred
int | length | length of "data"

### `radthreadReceiveFromThread()`

`int radthreadReceiveFromThread ( RAD_THREAD_ID threadId, void** data, int* length, int blocking );`

#### Description

Receive data (thread safe) from the thread described by threadId.

#### Return Value

User-defined msg type or ERROR_ABORT if non-blocking and no msg available.

#### Notes

Uses internal mutex and condition variable to provide thread safe delivery and notification. "*data" will point to a radsysBuffer which must be freed via radBufferRls when the receiver is done with it.

#### Parameters

Type | Name | Description
RAD_THREAD_ID | threadId | unique thread ID
void** | data | address of a pointer that is modified to point to the received buffer
int* | length | pointer to an integer which is modified to contain the length of the received buffer
int | blocking | if non-zero, this function will block until a message is available

### `radthreadSendToParent()`

`int radthreadSendToParent ( RAD_THREAD_ID threadId, int type, void* data, int length );`

#### Description

Send data (thread safe) to the parent of the thread described by threadId.

#### Return Value

OK or ERROR

#### Notes

Uses internal mutex and condition variable to provide thread safe delivery and notification.

#### Parameters

Type | Name | Description
RAD_THREAD_ID | threadId | unique thread ID
int | type | user-defined value (typically a message ID)
void* | data | pointer to the data to be sent; data is copied, ownership not transferred
int | length | length of "data"

### `radthreadReceiveFromParent()`

`int radthreadReceiveFromParent ( RAD_THREAD_ID threadId, void** data, int* length, int blocking );`

#### Description

Receive data (thread safe) from the parent of the thread described by threadId.

#### Return Value

User-defined msg type or ERROR_ABORT if non-blocking and no msg available.

#### Notes

Uses internal mutex and condition variable to provide thread safe delivery and notification. "*data" will point to a radsysBuffer which must be freed via radBufferRls when the receiver is done with it.

#### Parameters

Type | Name | Description
RAD_THREAD_ID | threadId | unique thread ID
void** | data | address of a pointer that is modified to point to the received buffer
int* | length | pointer to an integer which is modified to contain the length of the received buffer
int | blocking | if non-zero, this function will block until a message is available

### `radthreadShouldExit()`

`int radthreadShouldExit(RAD_THREAD_ID threadId);`

#### Description

Thread described by threadId test for exit command from parent.

#### Return Value

TRUE (non-zero) if the thread should exit, FALSE (0) otherwise.

#### Notes

Thread should call this function periodically and exit if it returns TRUE.

#### Parameters

Type | Name | Description
RAD_THREAD_ID | threadId | unique thread ID

### `radthreadLock()`

`int radthreadLock(void);`

#### Description

Lock the general thread mutex for this process.

#### Return Value

N/A

#### Notes

This mutex should not be held when calling radMsgRouterMessageSend.

### `radthreadUnlock()`

`int radthreadUnlock(void);`

#### Description

Release the general thread mutex for this process.

#### Return Value

N/A

#### Notes

This mutex should not be held when calling radMsgRouterMessageSend.

### `radUtilsSetIntervalTimer()`

`int radUtilsSetIntervalTimer (int msecs);`

#### Description

Start the system interval timer to deliver SIGALRM after msecs milliseconds.

#### Return Value

OK or ERROR

#### Notes

Usually only invoked directly by radTimer functions. If radTimers are running, manual manipulation of the system timer will corrupt the timer subsystem.

#### Parameters

Type | Name | Description
int | msecs | number of milliseconds for the timer expiry

### `radUtilsSetIntervalTimer()`

`int radUtilsSetIntervalTimer (int msecs);`

#### Description

Start the system interval timer to deliver SIGALRM after msecs milliseconds.

#### Return Value

OK or ERROR

#### Notes

Usually only invoked directly by radTimer functions. If radTimers are running, manual manipulation of the system timer will corrupt the timer subsystem.

#### Parameters

Type | Name | Description
int | msecs | number of milliseconds for the timer expiry

### `radUtilsGetIntervalTimer()`

`int radUtilsGetIntervalTimer (void);`

#### Description

Get the value of the real interval timer in milliseconds.

#### Return Value

milliseconds before the next system timer delivers SIGALRM

#### Notes

Usually only invoked directly by radTimer functions.

### `radUtilsEnableSignal()`

`int radUtilsEnableSignal (int signum);`

#### Description

Allow a signal to be received (see signal.h).

#### Return Value

OK or ERROR

#### Notes

Usually only invoked directly by radlib functions.

#### Parameters

Type | Name | Description
int | signum | signal to enable

### `radUtilsDisableSignal()`

`int radUtilsDisableSignal (int signum);`

#### Description

Disallow a signal from being received (see signal.h).

#### Return Value

OK or ERROR

#### Notes

Usually only invoked directly by radlib functions.

#### Parameters

Type | Name | Description
int | signum | signal to disable

### `radUtilsBecomeDaemon()`

`int radUtilsBecomeDaemon (const char *workingDirectory);`

#### Description

Make calling process a daemon. The calling process forks a new daemon child then exits - new process does a "chdir" to 'workingDirectory' if not NULL. The resulting process has no controlling terminal.

#### Return Value

the new process pid or ERROR

#### Notes

Usually only invoked directly by radProcessInit.

#### Parameters

Type | Name | Description
char * | workingDirectory | working directory of new daemon process (if not NULL)

### `radUtilsSleep()`

`void radUtilsSleep (int msDuration);`

#### Description

Provide a sleep function with ms resolution.

#### Return Value

None

#### Parameters

Type | Name | Description
int | msDuration | milliseconds to sleep

### `radtextsearchInit()`

`TEXT_SEARCH_ID radtextsearchInit (void);`

#### Description

Create a text search object.

#### Return Value

New search ID or ERROR if the ID cannot be allocated

### `radtextsearchExit()`

`void radtextsearchExit (TEXT_SEARCH_ID id);`

#### Description

Cleanup and delete a search object.

#### Return Value

N/A

#### Parameters

Type | Name | Description
TEXT_SEARCH_ID | id | text search ID returned from radtextsearchInit

### `radtextsearchInsert()`

`int radtextsearchInsert (TEXT_SEARCH_ID id, const char* text, int ordinal);`

#### Description

Insert a member of the text string universe.

#### Return Value

OK or ERROR if a new node cannot be allocated.

#### Parameters

Type | Name | Description
TEXT_SEARCH_ID | id | text search ID returned from radtextsearchInit
const char* | text | text to be inserted in binary search tree
int | ordinal | ordinal value corresponding to text string

### `radtextsearchRemove()`

`int radtextsearchRemove (TEXT_SEARCH_ID id, const char* text);`

#### Description

Delete a member of the universe.

#### Return Value

OK if found/removed, ERROR otherwise.

#### Parameters

Type | Name | Description
TEXT_SEARCH_ID | id | text search ID returned from radtextsearchInit
const char* | text | text to be removed from binary search tree

### `radtextsearchFind()`

`int radtextsearchFind (TEXT_SEARCH_ID id, const char* text, int* ordinalStore);`

#### Description

Find a member of the universe and return the corresponding ordinal in ordinalStore.

#### Return Value

OK if found (and ordinalStore populated) or ERROR if not found.

#### Parameters

Type | Name | Description
TEXT_SEARCH_ID | id | text search ID returned from radtextsearchInit
const char* | text | text to be found in binary search tree
int* | ordinalStore | where to store ordinal value corresponding to text string (if found)

### `radTimerListCreate()`

`int radTimerListCreate (int noTimers, int notifyDescriptor);`

#### Description

Create a timer list for the calling process. Timer expiries are notified through the notifyDescriptor.

#### Return Value

OK or ERROR

#### Notes

Usually only invoked directly by radProcessInit.

#### Parameters

Type | Name | Description
int | noTimers | number of timers for the timer list
int | notifyDescriptor | file descriptor to notify timer events through

### `radTimerListDelete()`

`void radTimerListDelete (void);`

#### Description

Delete the calling process's timer list.

#### Return Value

None

#### Notes

Usually only invoked directly by radProcessExit.

### `radTimerCreate()`

`TIMER_ID radTimerCreate (TIMER_ID timer, void (*routine) (void *parm), void *parm);`

#### Description

Create a timer object from the timer list free pool.

#### Return Value

TIMER_ID or NULL

#### Parameters

Type | Name | Description
TIMER_ID | timer | if not NULL, timer will be re-initialized instead of a new one being allocated
void (*) | routine | timer expiry callback routine
void * | parm | application data passed to the callback routine

### `radTimerDelete()`

`void radTimerDelete (TIMER_ID timer);`

#### Description

Release a timer instance to the timer list free pool.

#### Return Value

None

#### Parameters

Type | Name | Description
TIMER_ID | timer | timer to release

### `radTimerStart()`

`void radTimerStart (TIMER_ID timer, int time);`

#### Description

Start the timer for time milliseconds.

#### Return Value

None

#### Parameters

Type | Name | Description
TIMER_ID | timer | timer ID
int | time | milliseconds for timer duration

### `radTimerStop()`

`void radTimerStop (TIMER_ID timer);`

#### Description

Stop a running timer.

#### Return Value

None

#### Parameters

Type | Name | Description
TIMER_ID | timer | timer ID to stop

### `radTimerStatus()`

`int radTimerStatus (TIMER_ID timer);`

#### Description

Determine if the timer is running.

#### Return Value

TRUE or FALSE

#### Parameters

Type | Name | Description
TIMER_ID | timer | timer ID to status

### `radTimerSetUserParm()`

`void radTimerSetUserParm (TIMER_ID timer, void *newParm);`

#### Description

Reset the user pointer passed to the callback routine.

#### Return Value

None

#### Parameters

Type | Name | Description
TIMER_ID | timer | timer ID
void * | newParm | new user pointer for callback

### `radTimeGetMSSinceEpoch()`

`ULONGLONG radTimeGetMSSinceEpoch (void);`

#### Description

Returns the time in milliseconds since midnight, January 1, 1970

#### Return Value

milliseconds since the EPOCH

### `radTimeGetSECSinceEpoch()`

`ULONG radTimeGetSECSinceEpoch (void);`

#### Description

Returns the time in seconds since midnight, January 1, 1970

#### Return Value

seconds since the EPOCH

### `radUDPSocketCreate()`

`RADUDPSOCK_ID radUDPSocketCreate (void);`

#### Description

Create a datagram socket.

#### Return Value

RADUDPSOCK_ID or NULL if there is an error

#### Notes

This creates a UDP datagram socket. It can be used to send on immediately with the radUDPSocketSendTo function and/or it can be bound to a specific local IP address and port to receive datagrams with the radUDPSocketBind function.

### `radUDPSocketDestroy()`

`int radUDPSocketDestroy (RADUDPSOCK_ID id);`

#### Description

Close connection and cleanup resources.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate

### `radSocketGetDescriptor()`

`int radSocketGetDescriptor (RADUDPSOCK_ID id);`

#### Description

Get the socket descriptor (for select calls, etc.).

#### Return Value

The socket descriptor associated with "id".

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate

### `radUDPSocketBind()`

`int radUDPSocketBind (RADUDPSOCK_ID id, USHORT port);`

#### Description

Bind the UDP socket to a local port so you can add the socket descriptor to your select list and receive data.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
USHORT | port | Port number to be bound

### `radUDPSocketSetBroadcast()`

`int radUDPSocketSetBroadcast (RADUDPSOCK_ID id, int enable);`

#### Description

Enable/Disable sending broadcast packets.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
int | enable | FALSE disables, TRUE enables

### `radUDPSocketSetMulticastTXInterface()`

`int radUDPSocketSetMulticastTXInterface
(
RADUDPSOCK_ID id,
char *interfaceIP
);`

#### Description

Set multicast interface for outgoing datagrams.

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
char * | interfaceIP | interface IP address to send on

### `radUDPSocketSetMulticastTTL()`

`int radUDPSocketSetMulticastTTL (RADUDPSOCK_ID id, int ttl);`

#### Description

Set multicast TTL for outgoing datagrams (1 by default).

#### Return Value

OK or ERROR

#### Notes

The TTL value for multicast packets has a special meaning: it specifies the number of "hops" the packet shall be allowed to traverse. In other words, the number of router traversals. A value of "1" will keep the multicast packet on the local segment.

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
int | ttl | number of router "hops" allowed

### `radUDPSocketSetMulticastLoopback()`

`int radUDPSocketSetMulticastLoopback (RADUDPSOCK_ID id, int enable);`

#### Description

Enable/Disable multicast loopback (disabled by default).

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
int | enable | FALSE disables, TRUE enables

### `radUDPSocketAddMulticastMembership()`

`int radUDPSocketAddMulticastMembership
(
RADUDPSOCK_ID id,
char *multicastGroupIP,
char *interfaceIP
);`

#### Description

"Turn on" RX multicast datagrams on the "multicastGroupIP" group and "interfaceIP" interface.

#### Return Value

OK or ERROR

#### Notes

Enables multicast packet reception for the given multicast group (IP address) on the given local interface (IP address).

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
char * | multicastGroupIP | multicast group IP address
char * | interfaceIP | interface IP address

### `radUDPSocketDropMulticastMembership()`

`int radUDPSocketDropMulticastMembership
(
RADUDPSOCK_ID id,
char *multicastGroupIP,
char *interfaceIP
);`

#### Description

"Turn off" RX multicast datagrams on the "multicastGroupIP" group and "interfaceIP" interface.

#### Return Value

OK or ERROR

#### Notes

Disables multicast packet reception for the given multicast group (IP address) on the given local interface (IP address).

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
char * | multicastGroupIP | multicast group IP address
char * | interfaceIP | interface IP address

### `radUDPSocketRecvFrom()`

`int radUDPSocketRecvFrom
(
RADUDPSOCK_ID id,
void *buffer,
int maxToRead
);`

#### Description

Receive a datagram from a UDP socket.

#### Return Value

Bytes read or ERROR if an error occurs.

#### Notes

Will return less than requested amount based on the size of the datagram or if it is interrupted by a received signal.

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
void * | buffer | User buffer pointing to valid memory of size >= "lengthToRead" bytes where data is written
int | maxToRead | Maximum bytes to read

### `radUDPSocketSendTo()`

`int radUDPSocketSendTo
(
RADUDPSOCK_ID id,
char *hostOrIPAdrs,
USHORT port,
void *data,
int length
);`

#### Description

Send a datagram to a host name or IP adrs and port (connectionless).

#### Return Value

OK or ERROR

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
char * | hostOrIPAdrs | host name or IP address string of the destination
USHORT | port | destination port number
void * | data | User buffer pointing to the data to be written
int | length | Bytes to write

### `radUDPSocketSetBlocking()`

`int radUDPSocketSetBlocking
(
RADUDPSOCK_ID id,
int isBlocking
);`

#### Description

Set the socket for blocking or non-blocking IO.

#### Return Value

OK or ERROR

#### Notes

By default, all socket types are created in blocking IO mode. It is the user's responsibility to handle blocking/non-blocking IO properly (EAGAIN and EINTR errno's). Non-blocking should NOT be set for server (listen) sockets.

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
int | isBlocking | Boolean indicating if the socket should be set to non-blocking (non-zero value) or blocking IO (0 value, default)

### `radUDPSocketSetDebug()`

`void radUDPSocketSetDebug
(
RADUDPSOCK_ID id,
int enable
);`

#### Description

Turn on or off data debug which dumps all read/write datagrams to msgLog.

#### Return Value

N/A

#### Notes

If enabled, debug will radMsgLog the contents of all RX/TX datagrams.

#### Parameters

Type | Name | Description
RADUDPSOCK_ID | id | Valid socket ID obtained from a successful call to radUDPSocketCreate
int | enable | Boolean indicating if the debug dumping of RX/TX datagrams should be enabled or disabled