Steps for changing the protocol for a connection

About this task

Before you begin:

Ensure that you have done all setup that is required for the new protocol that the connection will use.
- For the setup required for TCP/IP and AT-TLS, see Setting up your system to use TCP/IP.
- For the setup required for APPC/MVS and VTAM®, see Setting up your system to use APPC/MVS and VTAM.
Ensure that you have sufficient DASD space available for the two sets of workspace data sets that exist temporarily during the conversion process.
If you are changing the protocol in a network that has multisystem nodes with a shared parameter library, review Sharing a RACF parameter library on a multisystem node.

Guideline: Perform the conversion when the workspace data sets are as close to empty as possible, and are not receiving large amounts of updates. Doing this allows a quicker conversion. The procedure handles many queued requests in the old workspace data sets, but many queued requests lengthens the conversion process and increases the risk of a disruption.

Perform the following steps to convert the protocol for a connection from APPC to TCP/IP or from TCP/IP to APPC.

Procedure

On the local node, create a new RACF® parameter library member to contain the TARGET command for the remote node using the new protocol.
______________________________________________________________
At the end of your current parameter library member, add a SET INCLUDE(xx) command where xx is the suffix of the new member.
For a multisystem node that shares a parameter library, the new parameter library member are shared by all systems in the multisystem node.

______________________________________________________________
On the local node, issue a TARGET command from the console to make the local node dormant because you can only change protocol information about a node that is dormant. Then issue a TARGET command for the local node specifying the new protocol, and making it operative. This command causes a listener process for the new protocol to be established on the local node. For example, if the local node is named NODE1 and you are converting the protocol from APPC to TCP/IP:
```
TARGET NODE(NODE1) DORMANT
TARGET NODE(NODE1) PROTOCOL(TCP) OPERATIVE
```
You should see the following message on the console:
```
IRRC054I RACF REMOTE SHARING TCP LISTENER HAS BEEN SUCCESSFULLY ESTABLISHED.
```
Inspect the messages that are issued and debug any problems that occur.
For a multisystem node whose member systems share a parameter library, perform this step on each system in the multisystem node.

______________________________________________________________
On the local node, update the existing parameter library member:
1. Add the TARGET command specifying the new protocol that you issued in step 3 immediately after the existing TARGET command for the local node.
2. Remove the OPERATIVE keyword from the existing TARGET command for the local node. Only the final TARGET command for the local node should specify OPERATIVE.
Repeat steps 1 to 4 on the remote system.
______________________________________________________________
On both systems, copy the existing TARGET command for the remote node into the new parameter library member. Edit the TARGET command:
- Replace the old protocol information with the new protocol information.
- Adjust the workspace data set names if you want to. It is a good idea to keep the same PREFIX value. If the new workspace data sets are not protected by the RACF DATASET profiles protecting the existing workspace data sets, make sure that the new workspace data sets are protected.
For a multisystem node whose systems share a parameter library, if any systems on the multisystem node are not running z/OS® V1R13 or later, commands that specify TCP/IP fail. That is expected and is not a problem. The systems continue communicating using APPC.

______________________________________________________________
On both systems, issue the new TARGET command from the console, and debug any problems that occur. These TARGET commands cause RACF to begin the conversion process. If you make any changes to a TARGET command while debugging, make the same changes to the TARGET command in the parameter library. Expect the first TARGET command to fail because a protocol mismatch is in effect until the new TARGET commands are issued on both systems. For example, you might receive this message:
```
IRRI016I ERROR: LOCAL NODE NODE1 AND PARTNER NODE NODE2 HAVE CONFLICTING TARGET
STATEMENTS WITH LOCAL SYSTEM. REASON CODE 5.
```
After you issue the new TARGET command on the second system, the protocol mismatch is resolved, and the conversion process continue. For example, you might receive this message:
```
IRRC057I RRSF PROTOCOL CONVERSION FROM APPC TO TCP FOR NODE NODE2 HAS BEEN INITIATED.
```
RACF establishes a connection using the new protocol. There might be a message on the console indicating that the connection has been established, similar to:
```
IRRI027I RACF COMMUNICATION WITH TCP NODE NODE2 HAS BEEN SUCCESSFULLY
ESTABLISHED USING CIPHER ALGORITHM 35 TLS_RSA_WITH_AES_256_CBC_SHA.
```
Tip: If the console command line is not long enough to specify the complete TARGET command, use keyword abbreviations, or break the TARGET command into multiple commands.

During the conversion, there are two sets of workspace data sets for the connection, one for the old protocol and one for the new protocol. Both sets are shown if you issue a TARGET LIST command during the conversion. The set for the old protocol is displayed under the heading "CONVERSION FILE". For an example see Figure 1.
Figure 1. TARGET LIST output showing workspace data sets for both the old and new protocols during a protocol conversion
```
IRRM010I (<) RSWJ SUBSYSTEM PROPERTIES OF REMOTE RRSF NODE NODE2:
   STATE - OPERATIVE ACTIVE 
   ⋮
   WORKSPACE FILE SPECIFICATION
         PREFIX                    - "SYS1.RRSF"
         WDSQUAL                   - <NOT SPECIFIED>
         FILESIZE                  - 500
         VOLUME                    - TEMP01
         FILE USAGE
                 "SYS1.RRSF.NODE1.NODE2.INMSG"
                                   - CONTAINS 0 RECORD(S)
                                   - OCCUPIES 1 EXTENT(S)
                 "SYS1.RRSF.NODE1.NODE2.OUTMSG"
                                   - CONTAINS 0 RECORD(S)
                                   - OCCUPIES 1 EXTENT(S)
         CONVERSION FILE
                 INMSG WORKSPACE FILE NOT ALLOCATED
                 "SYS1.RRSF.MF1AP001.MF2AP001.OUTMSG"
                                  - CONTAINS 5 RECORD(S)
                                  - OCCUPIES 1 EXTENT(S) 
```
______________________________________________________________
Wait for the conversion to complete successfully. When the conversion is complete, all requests that were queued in the old workspace data sets are complete, and you receive message IRRC058I on the consoles of both systems. It is similar to:
```
IRRC058I RRSF PROTOCOL CONVERSION FROM APPC TO TCP FOR NODE NODE2 IS COMPLETE.
```
Be sure that you wait until you have seen message IRRC058I on both systems. Then delete the TARGET command for the old protocol from the original parameter library member on each system.
Note:
1. Leaving the TARGET commands for the old protocol in the parameter library members until the conversion completes ensures that if the subsystem is stopped before the conversion completes, it can resume on the next IPL without losing any of the queued requests in the old workspace data sets.
2. For a multisystem node whose member systems share a parameter library, do not delete the TARGET command for the old protocol if any member system still needs to use the old protocol. On subsequent IPLs, this command continues to be issued for the systems that use the new protocol. The old protocol is temporarily defined, and then an automatic conversion to the new protocol occurs, and you receive messages indicating that the conversion is starting and that the conversion is complete. Be sure that you have enough DASD space for the workspace files for the old protocol, which is briefly allocated and deleted. If you want to avoid this behavior, split your shared parameter library into two members: one for the systems that use the old protocol, containing only TARGET commands for the old protocol, and a corresponding member for use by systems that use the new protocol.
______________________________________________________________

Results

When you are done, you have changed the protocol used for a connection. All requests that were queued in the workspace data sets for the original protocol have completed.

If you want to change the protocol for connections to other remote nodes, repeat steps 6 to 8 for each of those connections. If you change the protocol for all the remote nodes, and you no longer intend to use the old protocol, when the protocol conversions are complete you can remove the old protocol information from the TARGET command for the local node in the parameter library member. If the old protocol was APPC/MVS, after you remove the old APPC protocol information from the TARGET command for the local node, the APPC server will no longer be registered when the address space restarts. If you do not want to wait for the next IPL to shut down the APPC server, you can shut it down immediately by following these steps:

Make the local node dormant:
```
TARGET NODE(local_node) DORMANT
```
Delete the APPC protocol instance from the local node:
```
TARGET NODE(local_node) PROTOCOL(APPC) DELETE
```
Make the local node operative:
```
TARGET NODE(local_node) OPERATIVE
```

When you have converted the protocol for all intended nodes, you can optionally combine the two parameter library members (the original one and the one that you created in step 1) into one by moving the statements for the new protocol into the original member and deleting the SET INCLUDE command you added to the original member in step 1.