Cisco Access Registrar Dictionaries

Table Of Contents

Cisco Access Registrar Tcl and REX Dictionaries

Tcl Attribute Dictionaries

Attribute Dictionary Methods

Tcl Environment Dictionary

REX Attribute Dictionary

Attribute Dictionary Methods

REX Environment Dictionary

REX Environment Dictionary Methods

Cisco Access Registrar Tcl and REX Dictionaries

---

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.
clear	void pDict->clear(rex_AttributeDictionary_t* pDict)	Removes all entries from the dictionary.
containsKey	abool_t pDict->containsKey(rex_AttributeDictionary_t* pDict, const char* <pszAttribute>)	Returns TRUE when the dictionary contains <pszAttribute>, otherwise returns FALSE.
containsKeyByType	abool_t pDict->containsKeyByType(rex_AttributeDictionary_t* pDict, const abytes_t* <pAttribute>)	Returns TRUE when the dictionary contains <pAttribute>, otherwise returns FALSE.
firstKey	const char* pDict->firstKey(rex_AttributeDictionary_t* pDict)	Returns the name of the first attribute in the dictionary. Note, the attributes are not stored sorted by name.
firstKeyByType	const abytes_t* pDict->firstKeyByType (rex_AttributeDictionary_t* pDict)	Returns a pointer to the byte sequence defining the first attribute in the dictionary. Note, attributes are not stored sorted by name.
get	const char* pDict->get(rex_AttributeDictionary_t* pDict, const char* pszAttribute, int <iIndex>, abool_t* <pbMore>)	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.
getBytes	const abytes_t* pDict->getBytes(rex_AttributeDictionary_t* pDict, const char* pszAttribute, int <iIndex>, abool_t* <pbMore>)	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.
getBytesByType	const abytes_t* pDict->getBytesByType (rex_AttributeDictionary_t* pDict, const abytes_t* pAttribute, int <iIndex>, abool_t* <pbMore>)	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.
getByType	const char* pDict->get(rex_AttributeDictionary_t* pDict, const abytes_t* <pszAttribute>, int <iIndex>, abool_t* <pbMore>)	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.
getType	const char* pDict->getByType(rex_AttributeDictionary_t* pDict, const abytes_t* <pAttribute>)	Returns a pointer to the byte sequence defining the attribute, when the attribute name matches a configured attribute, zero otherwise.
isEmpty	abool_t pDict->isEmpty(rex_AttributeDictionary_t* pDict)	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.
nextKey	const char* pDict->nextKey(rex_AttributeDictionary_t* pDict)	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.
put	abool_t pDict->put(rex_AttributeDictionary_t* pDict, const char* <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 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.
putBytes	abool_t pDict->putBytes(rex_AttributeDictionary_t* pDict, const char* <pszAttribute>, const abytes_t* <pValue>, int <iIndex>)	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.
putBytesByType	abool_t pDict->putBytesByType(rex_AttributeDictionary_t* pDict, const abytes_t* <pAttribute>, const abytes_t* <pValue>, int <iIndex>)	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>.
reschedule	abool_t pDict->reschedule(rex_AttributeDictionary_t* pDict)	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.
clear	void pDict->clear(rex_EnvironmentDictionary_t* pDict)	Removes all entries from the dictionary.
containsKey	abool_t pDict->containsKey(rex_EnvironmentDictionary_t* pDict, const char* <pszKey>)	Returns TRUE when the dictionary contains <pszKey>, otherwise returns FALSE.
firstKey	const char* pDict->firstKey(rex_EnvironmentDictionary_t* pDict)	Returns the name of the first key in the dictionary. Note, the keys are not stored sorted by name.
get	const char* pDict->get(rex_EnvironmentDictionary_t* pDict, const char* <pszKey>)	Returns the value associated with <pszKey> from the dictionary. When the dictionary does not contain <pszKey>, an empty string is returned.
isEmpty	abool_t pDict->isEmpty(rex_EnvironmentDictionary_t* pDict)	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.
nextKey	const char* pDict->nextKey(rex_EnvironmentDictionary_t* pDict)	Returns the name of the next key in the dictionary that follows the key returned in the last call to firstKey or nextKey.
put	abool_t pDict->put(rex_EnvironmentDictionary_t* pDict, const char* <pszValue>, const char* <pszKey>)	Associates the value with <pszKey> in the dictionary, replacing any existing instance of <pszKey> with the new <pszValue>.
remove	abool_t pDict->remove(rex_EnvironmentDictionary_t* pDict, const char* <pszKey>)	Removes <pszKey> and the associated value from the dictionary. Always returns TRUE, even when the dictionary did not contain <pszKey>
reschedule	abool_t pDict->reschedule(rex_AttributeDictionary_t* pDict)	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.