This appendix describes the Tcl and REX dictionaries that are used when writing Incoming or Outgoing scripts.
A dictionary is a data structure that contains key/value pairs. Two types of dictionaries exist: the Attribute dictionaries (used by the Request and Response dictionaries), and the Environment dictionary.
This section contains the dictionaries you reference when writing a Tcl script and the dictionaries you reference when you write a script using the shared libraries (REX—RADIUS EXtension).
Tcl Attribute Dictionaries
An Attribute dictionary is a dictionary in which the keys are constrained to be the names of attributes as defined in the Cisco Access Registrar server configuration, and the values are the string representation of the legal values for that particular attribute. For example, IP addresses are specified by the dotted-decimal string representation of the address, and enumerated values are specified by the name of the enumeration. This means numbers are specified by the string representation of the number.
Attribute dictionaries have the unusual feature that there can be more than one instance of a particular key in the dictionary. These instances are ordered, with the first instance at index zero. Some of the methods of an Attribute dictionary allow an index to be specified to indicate a particular instance or position in the list of instances to be referenced.
Attribute Dictionary Methods
Attribute dictionaries use active commands, called methods, that allow you to change and access the values in the dictionaries. Table A-1 lists of all of the methods you can use with the Request and Response dictionaries.
Table A-1 Tcl Attribute Dictionary Methods
Name
Syntax
Description
addProfile
$dict addProfile<profile> [<mode>]
Copies all of the attributes in the profile <profile> into the dictionary. Note, <profile> must be the name of one of the profiles listed in the server configuration. When <mode> is not provided or when <mode> equals the special value REPLACE, any duplicate instances of the attributes in the dictionary are replaced with the attribute from <profile>. When <mode> is provided and equals the special value APPEND, new instances of the attributes are appended to the attributes already in the dictionary. When <mode> is provided and equals the special value AUGMENT, only add the attribute when it does not already exist.
clear
$dict clear
Removes all entries from the dictionary.
containsKey
$dict containsKey<attribute>
Returns 1 when the dictionary contains the attribute <attribute>, otherwise returns 0.
firstKey
$dict firstKey
Returns the name of the first attribute in the dictionary. Note, the attributes are not stored sorted by name.
get
$dict get<attribute> [<index> [bMore]]
Returns the value of the <attribute> attribute from the dictionary, represented as a string. When the dictionary does not contain the <attribute>, an empty string is returned.
When <index> is provided, return the <index>'th instance of the attribute. Some attributes can appear more than once in the request (or response) packet. The <index> argument is used to select which instance to return.
When bMore is provided, the get method sets bMore to 1 when more attributes exist after the one returned, and to 0 otherwise. You can use this to determine whether another call to get should be made to retrieve other instances of the attribute.
isEmpty
$dict isEmpty
Returns 1 when the dictionary has no entries, otherwise returns 0.
log
$dict log<level><message> ...
Outputs a message into the RADIUS server's logging system. The <level> should be either LOG_ERROR, LOG_WARNING, or LOG_INFO. The remaining arguments are concatenated together and sent to the logging system at the specified level.
nextKey
$dict nextKey
Returns the name of the next attribute in the dictionary that follows the attribute returned in the last call to firstKey or nextKey.
put
$dict put<attribute><value> [<index>]
Associates <value> with the attribute <attribute> in the dictionary. When <index> is not provided or when <index> equals the special value REPLACE, any existing instances of <attribute> are replaced with the single value. When <index> is provided and equals the special value APPEND, a new instance of <attribute> is appended to the end of the list of instances of the <attribute>. When <index> is provided and is a number, a new instance of <attribute> is inserted at the position indicated. When <index> is provided and equals the special value AUGMENT, only put the attribute when it does not already exist.
remove
$dict remove<attribute> [<index>]
Removes the <attribute> attribute from the dictionary. When <index> is not provided or when <index> equals the special value REMOVE_ALL, remove any existing instances of <attribute>. When <index> is provided and is a number, remove the instance of <attribute> at the position indicated.
Always returns 1, even when the dictionary did not contain the <attribute> at that <index>.
size
$dict size
Returns the number of entries in the dictionary.
trace
$dict trace<level><message> ...
Outputs a message into the packet tracing system used by the RADIUS server. At level 0, no tracing occurs. At level 1, only an indication the server received the packet and sent a reply is output. As the number gets higher, the amount of information output increases, until at level 4, where everything is traced as output. The remaining arguments are concatenated and sent to the tracing system at the specified level.
Tcl Environment Dictionary
A dictionary is a data structure that contains key/value pairs. An Environment dictionary is a dictionary in which the keys and values are constrained to be strings. The Tcl Environment dictionary is used to communicate information from the script to the server and from script to script within the processing of a particular request. Note, there can be only one instance of a key in the Environment dictionary.
Table A-2 lists of all the methods you can use with the Request and Response dictionaries.
Table A-2 Tcl Environment Dictionary Methods
Name
Syntax
Description
clear
$dict clear
Removes all entries from the dictionary.
containsKey
$dict containsKey<key>
Returns 1 when the dictionary contains the <key> key, otherwise returns 0.
firstKey
$dict firstKey
Returns the name of the first key in the dictionary. Note, the keys are not stored sorted by name.
get
$dict get<key>
Returns the value of <key> from the dictionary. When the dictionary does not contain the <key>, an empty string is returned.
isEmpty
$dict isEmpty
Returns 1 when the dictionary has no entries, otherwise returns 0.
log
$dict log<level><message> ...
Outputs a message into the logging system used by the RADIUS server. <level> should be one of LOG_ERROR, LOG_WARNING, or LOG_INFO. The remaining arguments are concatenated together and sent to the logging system at the specified level.
nextKey
$dict nextKey
Returns the name of the next key in the dictionary that follows the key returned in the last call to firstKey or nextKey.
put
$dict put<key><value>
Associates <value> with the <key> key in the dictionary, replacing an existing instance of <key> with the new value.
remove
$dict remove<key>
Removes the <key> key from the dictionary. Always returns 1, even when the dictionary did not contain the <key>.
size
$dict size
Returns the number of entries in the dictionary.
trace
$dict trace <level><message> ...
Outputs a message into the packet tracing system used by the RADIUS server. At level 0, no tracing occurs. At level 1, only an indication the server received the packet and sent a reply is output. As the number gets higher, the amount of information output is greater, until at level 4, where everything the server traces is output. The remaining arguments are concatenated together and sent to the tracing system at the specified level.
REX Attribute Dictionary
A dictionary is a data structure that contains key/value pairs. An Attribute dictionary is a dictionary in which the keys are constrained to be the attributes as defined in the RADIUS server configuration and the values are constrained to be legal values for that particular attribute. Attribute dictionaries have the unusual feature that there can be more than one instance of a particular key in the dictionary. These instances are ordered, with the first instance at index 0. Some of the methods of an Attribute dictionary allow an index to be specified to indicate a particular instance or position in the list of instances to be referenced.
When writing REX scripts, you can specify keys as the string representation of the name of the attribute or by type, which is a byte sequence defining the attribute. The values can also be specified as the string representation of the value or as the byte sequence, which is the attribute. These options mean some of these access methods have four different variations that are the combinations of string or type for the key, and string or bytes for the value.
Attribute Dictionary Methods
Attribute dictionaries use active commands, called methods, that allow you to change and access the values in the dictionaries.
Table A-3 lists all of the methods you can use with the Request and Response dictionaries.
Table A-3 REX Attribute Dictionary Methods
Name
Syntax
Description
addProfile
abool_t pDict->addProfile(rex_AttributeDictionary_t* pDict, const char* <pszProfile>, int <iMode>)
Copies all of the attributes in the <pszProfile> profile into the dictionary. Note, <pszProfile> must be the name of one of the profiles listed in the server configuration. When <iMode> equals the special value REX_REPLACE, it replaces any duplicate instances of the attributes in the dictionary with the attribute from the profile. When <iMode> equals the special value REX_APPEND, it appends a new instance of the attributes to any attributes already in the dictionary. When <iMode> equals the special value REX_AUGMENT, it only puts the attribute when does not already exist.
allocateMemory
void* pDict->allocateMemory(rex_AttributeDictionary_t* pDict, unsigned int <iSize>)
Allocates memory for use in scripts that persist only for the lifetime of this request. This memory is released when processing for this request is complete.
Returns the value of the <iIndex>'d instance of the attribute from the dictionary, represented as a string. When the dictionary does not contain the attribute (or that many instances of the attribute), an empty string is returned.
When <pbMore> is non-zero, the get method sets <pbMore> to TRUE when more instances of the attribute exist after the one returned, and to FALSE otherwise. This can be used to determine whether another call to get should be made to retrieve other instances of the attribute.
Returns the value of the <iIndex>'d instance of the attribute from the dictionary, as a sequence of bytes. When the dictionary does not contain the attribute (or that many instances of the attribute), 0 is returned.
When <pbMore> is non-zero, the getBytes method sets <pbMore> to TRUE when more instances of the attribute exist after the one returned, and to FALSE otherwise. This can be used to determine whether another call to getBytes should be made to retrieve other instances of the attribute.
Returns the value of the <iIndex>'d instance of the attribute from the dictionary, as a sequence of bytes. When the dictionary does not contain the attribute (or that many instances of the attribute), 0 is returned instead.
When <pbMore> is non-zero, sets the variable pointed to TRUE when more instances of the attribute exist after the one returned, and to FALSE otherwise. This can be used to determine whether another call to get should be made to retrieve other instances of the attribute.
Returns the value of the <iIndex>'d instance of the attribute from the dictionary, as represented as a string. When the dictionary does not contain the attribute (or that many instances of the attribute), returns an empty string.
When <pbMore> is non-zero, the getByType method sets <pbMore> to TRUE when more instances of the attribute exist after the one returned, and to FALSE otherwise. This can be used to determine whether another call to getByType should be made to retrieve other instances of the attribute.
Returns TRUE when the dictionary has 0 entries, FALSE otherwise.
log
abool_t pDict->log(rex_AttributeDictionary_t* pDict, int <iLevel>, const char* <pszFormat>, ...)
Outputs a message into the logging system used by the RADIUS server. <iLevel> should be one of REX_LOG_ERROR, REX_LOG_WARNING, or REX_LOG_INFO. The pszFormat argument is treated as a printf-style format string, and it, along with the remaining arguments, are formatted and sent to the logging system at the specified level.
Returns the name of the next attribute in the dictionary that follows the attribute returned in the last call to firstKey or nextKey.
nextKeyByType
const abytes_t* pDict->
nextKeyByType(rex_AttributeDictionary_t* pDict)
Returns a pointer to the byte sequence defining the next attribute in the dictionary that follows the attribute returned in the last call to firstKeyByType or nextKeyByType.
Converts <pszValue> to a sequence of bytes, according to the definition of <pszAttribute> in the server configuration. Associates that sequence of bytes with <pszAttribute> in the dictionary. When <iIndex> equals the special value REX_REPLACE, it replaces any existing instances of <pszAttribute> with a single value. When <iIndex> equals the special value REX_APPEND, it appends a new instance of <pszAttribute> to the end of the list of existing instances of <pszAttribute>. Otherwise, a new instance of <pszAttribute> is inserted at the position indicated. This method returns TRUE unless <pszAttribute> does not match any configured attributes or the value could not be converted to a legal value. When <iIndex> equals the special value REX_AUGMENT, only put<pszAttribute> when it does not already exist.
Associates <pValue> with the attribute <pszAttribute> in the dictionary. When <iIndex> equals the special value REX_REPLACE, it replaces any existing instances of the <pszAttribute> with a single new value. When <iIndex> equals the special value REX_APPEND, it appends a new instance of <pszAttribute> to the end of the list of existing instances of <pszAttribute>. When <iIndex> equals the special value REX_AUGMENT, only put the <pszAttribute> when it does not already exist. Otherwise, a new instance of <pszAttribute> is inserted at the position indicated.
This method returns TRUE unless the attribute name does not match any configured attributes.
Associates <pValue> with the attribute <pAttribute> in the dictionary. When <iIndex> equals the special value REX_REPLACE, it replaces any existing instances of <pAttribute> with the new value. When <iIndex> equals the special value REX_APPEND, it appends a new instance of <pAttribute> to the end of the list of existing instances of <pAttribute>. When <iIndex> equals the special value REX_AUGMENT, only put<pAttribute> when it does not already exist. Otherwise, insert a new instance of <pAttribute> at the position indicated.
This method returns TRUE unless the attribute name does not match any configured attributes.
putByType
abool_t pDict->putByType(rex_AttributeDictionary_t* pDict, const abytes_t*<pszAttribute>, const char* <pszValue>, int <iIndex>)
Converts <pszValue> to a sequence of bytes, according to the definition of <pszAttribute> in the server configuration. Associates that sequence of bytes with <pszAttribute> in the dictionary. When <iIndex> equals the special value REX_REPLACE, it replaces any existing instances of <pszAttribute> with a single new value. When <iIndex> equals the special value REX_APPEND, it appends a new instance of <pszAttribute> to the end of the list of existing instances of <pszAttribute>. Otherwise, it inserts a new instance of <pszAttribute> at the position indicated. This method returns TRUE unless <pszAttribute> does not match any configured attributes, or the value could not be converted to a legal value.
remove
abool_t pDict->remove(rex_AttributeDictionary_t* pDict, const char* <pszAttribute>, int <iIndex>)
Removes the <pszAttribute> from the dictionary. When <iIndex> equals the special value REX_REMOVE_ALL, removes any existing instances of <pszAttribute>. Otherwise, it removes the instance of <pszAttribute> at the position indicated. Returns TRUE, even when the dictionary did not contain <pszAttribute> at the <iIndex>, unless <pszAttribute> does not match any configured attribute.
removeByType
abool_t pDict->removeByType(rex_AttributeDictionary_t* pDict, const abytes_t*<pAttribute>, int <iIndex>)
Removes the <pAttribute> from the dictionary. When <iIndex> equals the special value REX_REMOVE_ALL, it removes any existing instances of <pszAttribute>. Otherwise, the instance of <pAttribute> at the position indicated is removed. Always returns TRUE, even when the dictionary did not contain <pAttribute> at the <iIndex>.
Enables control over asynchronous activities. It enables you to collect similar activities and mark them as pending. You can then process them and reschedule them. You can only use this attribute with multithreaded services. Use caution when employing this method.
size
int pDict->size(rex_AttributeDictionary_t* pDict)
Returns the number of entries in the dictionary.
trace
abool_t pDict->trace(rex_AttributeDictionary_t* pDict, int <iLevel>, const char* <pszFormat>, ...)
Outputs a message into the packet tracing system used by the RADIUS server. At level 0, no tracing occurs. At level 1, only an indication the packet was received and a reply was sent is output. As the number gets higher, the amount of information output is greater, until at level 4, where everything traceable is output. The remaining arguments are formatted and sent to the tracing system at the specified level.
REX Environment Dictionary
A dictionary is a data structure that contains key/value pairs. An Environment dictionary is a dictionary in which the keys and values are constrained to be strings. The REX Environment dictionary is used to communicate information from the script to the server and from script to script within the processing of a particular request. Note, there can be only one instance of a key in the Environment dictionary.
REX Environment Dictionary Methods
The Environment dictionary uses active commands, called methods, to allow you to change and access the values in the dictionary. Table A-4 lists all of the methods you can use with the REX Environment dictionary.
Table A-4 REX Environment Dictionary Methods
Name
Syntax
Description
allocateMemory
void* pDict->allocateMemory(rex_EnvironmentDictionary_t* pDict, unsigned int <iSize>)
Allocate memory for use in scripts that persist only for the lifetime of this request. This memory is released when processing for this request is complete.
Returns TRUE when the dictionary has 0 entries, FALSE otherwise.
log
abool_t pDict->log(rex_EnvironmentDictionary_t* pDict, int <iLevel>, const char* <pszFormat>, ...)
Outputs a message into the logging system used by the RADIUS server. <iLevel> should be one of REX_LOG_ERROR, REX_LOG_WARNING, or REX_LOG_INFO. The <pszFormat> argument is treated as a printf-style format string, and it, along with the remaining arguments, are formatted and sent to the logging system at the specified level.
Enables control over asynchronous activities. It enables you to collect similar activities and mark them as pending. You can then process them and reschedule them. You can only use this attribute with multithreaded services. Use caution when employing this method.
size
int pDict->size(rex_EnvironmentDictionary_t* pDict)
Returns the number of entries in the dictionary.
trace
abool_t pDict->trace(rex_EnvironmentDictionary_t* pDict, int <iLevel>, const char* <pszFormat>, ...)
Outputs a message into the packet tracing system used by the RADIUS server. At level 0, no tracing occurs. At level 1, only an indication the packet was received and a reply was sent is output. As the number gets higher, the amount of information output is greater, until at level 4, where everything traceable is output. The remaining arguments are formatted and sent to the tracing system at the specified level.
