Working with Parameter Blocks

A parameter block stores parameters and values as name/value pairs. There are many pre-defined functions you can use to work with parameter blocks, to extract parameter values, to change parameter values, and so on. For example, libcs_pblock_findval(paramname, returnPblock) uses the given return pblock to return the value of the named parameter in the RAF’s input pblock. For an example, see RAF Definition Example.

When adding, removing, editing, and creating name-value pairs for parameters, your robot application functions can use the functions in the pblock.h header file (in PortalServer-base/sdk/robot/include/libcs directory).

The names of these functions are all prefixed by libcs_.

The following table contains the parameter manipulation functions and a description of the corresponding function. See the PortalServer-base/sdk/robot/include/libcs/pblock.h header file for full function signatures with return type and arguments.

libcs_param_create

Creates a parameter with the given name and value. If the name and value are not null, they are copied and placed into a new pb_param structure.

libcs_param_free

Frees a given parameter if it is non-NULL. It returns 1 if the parameter was non-NULL and 0 if it was NULL. This function is useful for error checking before using the libcs_pblock_remove function.

libcs_pblock_create

Creates a new parameter block with a hash table of a chosen size. Returns the newly allocated parameter block

libcs_pblock_free

Frees a given parameter block and any entries inside it.

libcs_pblock_find

Finds the entry with the given name in a pblock and returns its value, otherwise returns NULL.

libcs_pblock_findval

Finds the entry with the given name in a pblock, and returns its value, otherwise returns NULL.

libcs_pblock_remove

Behaves like the libcs_pblock_find function, but in addition, it removes the entry from the pblock.

libcs_pblock_nninsert and libcs_pblock_nvinsert

These parameters create a new parameter with a given name and value and insert it into a given parameter block. The libcs_pblock_nninsert function requires that the value be an integer, but the libcs_pblock_nvinsert function accepts a string.

libcs_pblock_pinsert

Inserts a parameter into a parameter block.

libcs_pblock_str2pblock

Scans the given string for parameter pairs in the format name=value or name="value", adds them to a pblock, and returns the number of parameters added.

libcs_pblock_pblock2str

Places all of the parameters in the given parameter block into the given string. Each parameter is of the form name="value" and is separated by a space from any adjacent parameter.