Reference Manual: DSL header

From DSL
Jump to: navigation, search

This class provides a placeholder for the user to store some information. Each node contains one of this objects that provides them with an identifier, a name, and a comment. The identifier must follow SMILE rules for identifiers and is usually a "short" name for a node (Ex: "Forecast"). The name can be any unrestricted string and it is intended to provide a longer and more explanatory description of the node (Ex: "Forecast from the expert"). The comment can also contain an unrestricted string containing whatever you want (Ex: "This forecast is provided by company such and such. They have proven to be reliable in the past".).

Smile does not really use any of these fields except on one occasion: node identifiers cannot be duplicated within a network. A try to Add a node with a duplicated identifier will result in a DSL_OUT_OF_RANGE return value. Note that this is the only place in which this is checked. Nothing prevents you from changing the node identifier after it has been added to the network. In such a case, when using methods like FindNode only the first node with the given identifier will be found. It is not a good idea in general to have nodes with the same identifier in the same network and SMILE may not support them in future releases.


Methods

  • int SetId(char *theID)

Sets the identifier of the node to theID. The rules for SMILE identifiers should be followed: It cannot be NULL, it can only contain alphanumeric characters and '_', it must have at least one character (length > 0), and it must start with a letter. The previous identifier, if any, is deallocated and a private local copy of theID is kept.

Error return values: DSL_OUT_OF_MEMORY, DSL_INVALID_ID (theID is not valid).


  • int SetName(char *theName)

Sets the name of the node to theName. The name can be any unrestricted string (including NULL). The previous name, if any, is deallocated and a private local copy of theName is kept.

Error return values: DSL_OUT_OF_MEMORY.


  • int SetComment(char *theComment)

Sets the comment of the node to theComment. The comment can be any unrestricted string (including NULL). The previous comment, if any, is deallocated and a private local copy of theComment is kept.

Error return values: DSL_OUT_OF_MEMORY.


  • int IsThisIdValid(char *theID)

Returns DSL_TRUE if theID is a valid SMILE identifier. Returns DSL_FALSE otherwise.


  • int MakeValidId(char *theID)

Tries to validate theID using the following procedure: if theID does not start with a letter, the first character is substituted by 'x'. Every character of theId that is not either alphanumeric or '_' will be substituted by '_'. If theID is NULL or has 0 length, the validation will not be possible and an error code will be returned.

Error return values: DSL_OUT_OF_RANGE (theID is NULL or its length is 0).

Personal tools