{{>toc}}

Read Link_Dynamic_Node_Mapping for background.

Every link has an array called mDefaultNodeMap. This is like the mNodeMap array with these differences:

• You can’t see it or change it in run-time,
• Whereas mNodeMap can be changed at any time, the default node map is set during network initialization and thereafter never changes.
• It is a permanent record of the starting node map of a link, so that a link always remembers how to return to its starting location.

The link returns to its default map during a sim restart, and individual ports can be returned to their default location with the DEFAULT manual user port move command.

Say you have an old network drawing that you don’t want to re-export and rebuild into a new delivery but you need to change the initial location of a link, AND you want that to be the new default location (mDefaultNodeMap above). Here’s what you do.

Every link has an input data array called mInitialNodeMap. It is not visible in GunnsDraw like other input data, and can only be set via the Trick Input Processor. Like mNodeMap, it also has size mNumPorts. You can use the Trick Input File to set this array, and then when the network initializes, those values will be used by the link for its initial location and its default node map.

An example of how to set such an array follows. Suppose I want to override a 2-port link’s node map to 21 and 42. In the Trick Input File, I’ll allocate and initialize a new array of the correct type and size, and then point the link’s input data pointer to the newly allocated Trick array, as follows:

    # Declare and have Trick allocate memory for a new array, in this example an int[2]:
    initialNodeMap = trick.alloc_type(2, "int")

    # Initialize the desired array values:
    initialNodeMap = [21, 42]

    # Assign the link's shape data pointer to the array:
    mySimObject.myNetwork.netInput.myLink.mInitialNodeMap = initialNodeMap

Then, when the load initializes, {21, 42} will become the link’s mDefaultNodeMap and initial mNodeMap. Note that if the link finds these nodes to be an invalid mapping for whatever reason (remember that most links have restrictions on where you can put them), then this acts exactly like a bad mapping in GunnsDraw — the link throws an exception during initialization, causing the network to abort its initialization and rendering the network un-runable. A detailed error message will be output to the Health & Status log.

During run-time, you can disable a link’s ability to change nodes by setting its mNodeMapLocked term to true. When this is set, the link will not move for any reason (user or automatic), except for during network initialization. When attempting a manual command, the mUserPortSetControl term will return to FAILED. No message will be output to Health & Status.

The main reason we have this feature is in case you have specific instances of a link class that you do not want the users move, when that class normally allows movement.

The link also has public setter methods to toggle the mNodeMapLocked flag. Calling the link’s lockNodeMap() method sets it true, and calling unlockNodeMap() sets it false.

Like the mInitialNodeMap, this can be set via the Trick Input File.

Links’ node maps (mNodeMap) and default node maps (mDefaultNodeMap) are NOT checkpointed.

During a Trick sim restart, links initially attempt to move back to their default node map (see above). The only exception is if they’re locked with the mNodeMapLocked flag (see above). If locked, they’ll stay with the same mapping they had prior to restarting the sim. The mNodeMapLocked flag is also not checkpointed.

During restart, after the link’s initial attempt to return to its default node map, some links may attempt to move again to some other location. A particular example is with Jumper links — these do save their socket connections in checkpoints and attempt to restore those connections during restart.

The reason we do not checkpoint the node map directly is for “checkpoint migration”. Some user environments (who will go unnamed¹) require that old checkpoint files can be loaded in new sims that have a different executable build than what the files were cut from. There are many ways this practice can go horribly wrong, and we attempted to avert some of them in GUNNS. For instance, if the node map were checkpointed and links attempted to return to them during restart, and if node maps in an old checkpoint file referenced node numbers that no longer exist in the newer network version, then you’d have many links failing to move, leaving the network in a spaghetti state. By not checkpointing node maps, we ensure that particular issue doesn’t occur.

The drawbacks to this are:

• if you have good reason to move a link during a session, you must keep reapplying that move after every restart.
• if you have good reason to move some links around and would like to keep those mapping during future sessions, you must reapply those moves in each session, or use the mInitialNodeMap capability as a means of repeating them.

The reason we do checkpoint the jumper socket connections is to recover that lost checkpointing capability for links that are designed to routinely be moved by the users (jumpers). Their connections are saved in checkpoints by an enumerated value type (a socket name) rather than a node number index into a dynamic node array, so this is maybe somewhat safer.

The command stays in EXECUTE instead of going to READY or FAILED, etc. Possible causes:

• Some link classes are designed to not allow you to move them around. Links such as these will give no indication that manual commands aren’t allowed other than they simply do nothing.
• Your sim is in freeze. The commands only work when the network is running.
• It’s possible for a network to not be running even when the sim is. Check the Health & Status log for initialization or other errors that indicate an uninitialized or otherwise broken network.

• First of all, make sure your Health & Status is logging in the first place. Networks that have been successfully initialized will always output at least one INFO message to H&S, so you can check for that to see if you’re really logging.
• The link’s node map might be locked. See above.

¹ TS-21