Requesting transport affinity

When you set transport affinity, sockets are restricted to just one transport. A program can associate a socket with a specifically named transport in one of these ways:

With setibmopt(IBMTCP_IMAGE), all future socket() calls for AF_INET or AF_INET6 create sockets that are associated with only one specified transport. To invoke them from non-C programs, use BPX1PCT(PC#SetIbmOptCmd). This specification of a specific transport is inherited over fork() and propagated over exec().
SetIbmOpt can be issued more than once to change the chosen transport and affect future sockets that are created. If a blank transport name is used, the process is reset so that no transports are chosen.

When CINET is not configured, there is only one AF_INET or dual AF_INET/AF_INET6 transport, and all socket() calls for AF_INET or AF_INET6 create sockets with that transport. In this case, setibmopt() has no effect and is ignored.

If the specific transport is not found, setibmopt() fails with EIBMBADTCPNAME if CINET is installed, and with ENXIO if it isn't.

For more details, see setibmopt() in z/OS XL C/C++ Language Reference or pfsctl (BPX1PCT) in z/OS UNIX System Services Programming: Assembler Callable Services Reference.
Call ioctl(SIOCSETRTTD) associates an existing socket with the one specified transport, removing the others, if any, from the socket.
The _BPXK_SETIBMOPT_TRANSPORT environment variable can be set to the name of the desired transport before starting the program. This variable can also be set in the PARM= parameter of a started procedure to have the Language Environment® runtime initialization issue a setibmopt() call on behalf of the program being started. This variable can also be included in the _CEE_ENV file.
Include a job step that invokes BPXTCAFF. BPXTCAFF is invoked as a job step in front of an existing program in a started procedure or submitted job stream. For example:
```
//STEP0 EXEC PGM=BPXTCAFF,PARM=TPNAME
//REALSTEP EXEC PGM=MYPGM,PARM='MyParms'  
```
The desired transport is specified with the PARM= keyword and must be 1 to 8 uppercase characters. This is the same value that would be specified for _BPXK_SETIBMOPT_TRANSPORT. If PARM= is not supplied, or is blank, then the address space's transport affinity will be reset to no transport selected. This can also be specified as PARM=&VAR, where VAR is a PROC keyword that is passed in from the Start command or is a static system symbol.
BPXTCAFF sets transport affinity for an address space for the duration of that address space or job. This affinity persists over job steps within the job, persists over UNIX process termination and redubbing, and applies to all UNIX processes running within that address space. BPXTCAFF is intended for use with non-C or POSIX(OFF) programs where the _BPXK_SETIBMOPT_TRANSPORT environment variable is not effective. It is also intended for programs that do not make their own calls to setibmopt() or BPX1PCT or that cannot be modified to do so. BPXTCAFF exits with one of the following return codes in register 15.

0

Successful. TPNAME matched an AF_INET socket transport.

2

Minor failure. TPNAME did not match any transport but CINET is not configured so transport affinity is moot.

8

Failure. CINET is configured and TPNAME did not match any transport running under CINET.

12

Failure. The interface to the routine was not valid.

To set transport affinity for a TSO address space, you can also invoke BPXTCAFF from TSO/E by issuing:
```
 TSO CALL 'SYS1.LINKLIB(BPXTCAFF)' 'TPNAME'
```
To set transport affinity for an address space using a REXX procedure, you can invoke BPXTCAFF from REXX by issuing:
```
/*  REXX  */
Address Linkmvs BPXTCAFF 'TPNAME'
Exit rc
```
BPXTCAFF makes a call to BPX1PCT(PC#SetIbmOptCmd) with an Arg value of 1 specified to achieve transport affinity for a persistent address space. For more details, see BPX1PCT in z/OS UNIX System Services Programming: Assembler Callable Services Reference.

Restriction: A BPXTCAFF job step must not be used with z/OS UNIX address spaces that are set up for the NFS or DFS clients. The z/OS UNIX services that are needed by BPXTCAFF are not available when the colony is started from the BPXPRMxx member. However, z/OS UNIX cannot finish initialization until the colonies are initialized, so the system will hang. The technique that is described in Step 5 sets up affinity for NFS or DFS clients.
Use the PARM= parameter of the z/OS UNIX colony address space. To set transport affinity for the NFS Client or DFS Client, use the PARM= keyword of the EXEC statement that starts BPXVCLNY in the colony address space procedure as follows:
```
//MVSCLNT EXEC PGM=BPXVCLNY,TIME=1440,PARM=TP(TPNAME)
```
where the PARM=value is the following:
- All in uppercase
- Starts with "TP("
- TPNAME is the left-aligned, 1-to-8-character name of the desired transport
If PARM= is specified and does not conform to these rules, the colony is terminated by an EC6 abend with a reason code of 11BE8039. When CINET is configured on the system and the specified transport is not configured under CINET, the colony is terminated by an EC6 abend with a reason code of 11BE803A. In either case, the colony can be restarted after the procedure is corrected by replying to the operator prompt that is issued.

The _BPXK_SETIBMOPT_TRANSPORT environment variable does not work in a z/OS UNIX colony address space because it does not start under Language Environment.
Specify a transport name when a socket is created.
Individual sockets can be created with transport affinity by passing the transport name directly to the BPX1SOC callable service. This specific socket affinity overrides any process-level affinity that has been established. This feature is not available to C programs through the standard socket() function, but C programs can call BPX1SOC directly. For more information, see BPX1SOC in z/OS UNIX System Services Programming: Assembler Callable Services Reference.
Specify a transport name for GETHOSTID() or GETHOSTNAME().
A BPX1HST request for GETHOSTID or GETHOSTNAME can be directed to a specific transport by using the BPX1PCT(PC#DIRGETHOST) function. This overrides any process-level affinity that has been established. For more information, see BPX1PCT in z/OS UNIX System Services Programming: Assembler Callable Services Reference.