MODIFY TOPO command

Abbreviations

When using an abbreviation in place of an operand, code the abbreviation exactly as shown in the table. For example, when coding the abbreviation for TYPE=FORCE, code only F or FORCE. Do not code TYPE=F.

Purpose

Operands

procname

The procedure name for the command. If procname in the START command was specified as startname.ident, where startname is the VTAM® start procedure and ident is the optional identifier, either startname.ident or ident can be specified for procname.

If procname in the START command was startname, startname must be specified for procname.

DEST=cp_name

Specifies the destination node (a control point) for a transmission group or, when used with the FUNCTION=CLRUNRCH operand, the name of an unreachable partner (destination) on an unreachable partner path through an Enterprise Extender connection network. The cp_name value can be network qualified (netid.cpname) or a CP name without a network ID. If just the CP name is entered without a network ID, the network ID of the node on which the command is entered will be used.

FUNCTION

Specifies the function to be performed.

FUNCTION=CLRTREES

Deletes all existing routing trees that are used to determine optimal session routes. After these routing trees are deleted, new routing trees are created as session routes are requested.

Restriction: Typically, you do not need to clear the APPN routing tree information. Do not use this function unless you are advised by IBM® service to do so.

Result: Clearing the APPN routing trees can temporarily affect VTAM performance because new routing trees are created for session route requests.

Rule: The MODIFY procname,TOPO,FUNCTION=CLRTREES command is valid only when you enter it on a network node.

FUNCTION=CLRUNRCH

Specifies that a set of unreachable partner paths for Enterprise Extender connection networks is to be cleared; if these paths were previously unavailable for route calculation as a result of the unreachable partner information, the paths will be made available for route calculation.

Rule: The MODIFY procname,TOPO,FUNCTION=CLRUNRCH command is valid only when you enter it on a network node.

FUNCTION=DELETE

Specifies that an entry is to be deleted from the topology database.

Guideline: Typically, you do not need to delete entries from the database; however, if for some reason you need to do so, you can use this command. For example, if another node (over which you have no control) has broadcast erroneous or unnecessary topology data into the network, the topology database at this node might choose incorrect or inefficient routes.

Result: Existing sessions are not affected when you delete an entry from the topology database or change the status of an entry in the topology database for a node or TG that is currently in use. However, new session requests might fail if no other route is available.

Rules:

• You cannot delete the node entry for your own host node.
• You cannot delete an active local transmission group.
• You cannot delete an adjacent node (unless the link to the adjacent node is inactive).
• You cannot delete or change the status of a node at an end node or migration data host.

FUNCTION=NORMAL

Specifies that an entry for a resource is to be returned to a normal state (after being quiesced) in the topology database and available for route calculation.

FUNCTION=QUIESCE

Specifies that an entry for a resource is to be marked as quiesced in the topology database and not used for route calculation.

Result: If you have specified the PSRETRY start option, changing a TG from QUIESCE to NORMAL or from NORMAL to QUIESCE triggers path switches for all RTP pipes, regardless of the PSWEIGHT start option value. This means that the RTP pipes might be switched to the same path even if PSWEIGHT is set to LESSTHAN. See z/OS Communications Server: SNA Resource Definition Reference for additional information about the PSRETRY and PSWEIGHT start options.

ID=cp_name

Specifies the name of a node (control point). The cp_name value can be network qualified (netid.cpname) or a CP name without a network ID. If just the CP name is entered without a network ID, the network ID of the node on which the command is entered will be used.

Rules:

• You cannot delete the entry for your own host node.
• This operand is valid only when used in a command entered on a network node.

ORIG=cp_name

Specifies the origin node (a control point) for a transmission group or, when used with the FUNCTION=CLRUNRCH operand, the name of an origin end node or network node on an unreachable partner path through an Enterprise Extender connection network. The cp_name value can be network qualified (netid.cpname) or a CP name without a network ID. If just the CP name is entered without a network ID, the network ID of the node on which the command is entered will be used.

TGN=tg_number

Specifies the transmission group number. The valid range for TG numbers is 1–255.

For FUNCTION=DELETE, the transmission group is deleted in both directions between the origin and destination nodes.

SCOPE

Specifies whether the request affects the local topology database only or is propagated to all topology databases in the network.

SCOPE=LOCAL

Specifies that the request affects the local topology database only.

For FUNCTION=DELETE, the resource is deleted immediately from the local topology database.

Results:

• When SCOPE=LOCAL is specified or is the default value on the MODIFY TOPO command entered at an end node, the information is always propagated to the end node's network node server (NNS), which performs all route calculation for an end node.
• When FUNCTION=DELETE is specified and SCOPE=LOCAL is also specified or is the default value on an end node to delete a TG, the TG is deleted immediately in the end node. However, the TG can still be displayed on the NNS with a DISPLAY TOPO command as it is with SCOPE=NETWORK. The TG will have an odd resource sequence number (RSN) value and will not be usable for route calculation. The NNS deletes the TG during its next garbage collection cycle.

SCOPE=NETWORK

Specifies that the request is propagated to all topology databases in the network.

For FUNCTION=DELETE, the resource is marked as unusable for route calculation in all topology databases in the network. Each network node supporting enhanced topology database garbage collection deletes the resource during its next garbage collection cycle. Garbage collection occurs once every 24 hours. Network nodes that do not support enhanced topology database garbage collection reset the time left value to 15 days.

Rules:

• If SCOPE=NETWORK is specified on the command entered at a network node for an end node resource, the request is not propagated to other network nodes. Topology information for end node resources is kept only in the topology databases of the end node and the network node server of the end node.
• If SCOPE=NETWORK is specified with FUNCTION=QUIESCE on the command entered at a network node for another network node or for a TG owned by another network node, a correction to the status of the resource might be broadcast by the owning node.

TYPE=FORCE

Required to delete an adjacent node. The link to the adjacent node must be inactive. If you are deleting a node that is not adjacent, this operand is not required.

TYPE=FORCE is also required to delete a local transmission group. A TG is considered to be local if the origin or destination is the host from which you are entering this command. The TG must be inactive. If the TG is not local, this operand is not required.

VRN=cp_name

Specifies the name of a virtual node on an unreachable partner path through an Enterprise Extender connection network. The cp_name value can be network qualified (netid.cpname) or a CP name without a network ID. If just the CP name is entered without a network ID, the network ID of the node on which the command is entered will be used.