IPV6_JOIN_GROUP and IPV6_LEAVE

IPV6_JOIN_GROUP is used to join a multicast group. This is accomplished by using the SETSOCKOPT API and specifying the address of the IPV6_MREQ structure containing the IPv6 multicast address and the local IPv6 multicast interface index. The stack chooses a default multicast interface if an interface index of 0 is passed. The values specified in the IPV6_MREQ structure used by IPV6_JOIN_GROUP and IPV6_LEAVE_GROUP must be symmetrical. The format of the IPV6_MREQ structure can be found in the BPXYSOCK macro.

The assembler program example in Figure 1 illustrates this socket option in EZASMI Macro form:

***********************************************************************
*                                                                     *
*        Issue INITAPI to connect to interface                        *
*                                                                     *
***********************************************************************
         POST  ECB,1              NEXT IS ALWAYS SYNCH
         EZASMI TYPE=INITAPI,     ISSUE INITAPI MACRO                  X
               SUBTASK=SUBTASK,   SPECIFY SUBTASK IDENTIFIER           X
               MAXSOC=MAXSOC,     SPECIFY MAXIMUM NUMBER OF SOCKETS    X
               MAXSNO=MAXSNO,     (HIGHEST SOCKET NUMBER ASSIGNED)     X
               ERRNO=ERRNO,       (SPECIFY ERRNO FIELD)                X
               RETCODE=RETCODE,   (SPECIFY RETCODE FIELD)              X
               APITYPE=APITYPE,   (SPECIFY APITYPE FIELD)              X
               ERROR=ERROR        ABEND IF ERROR ON MACRO
         BAL   R14,RCCHECK        --> DID IT WORK?
***********************************************************************
*                                                                     *
*        Issue SOCKET Macro to obtain a socket descriptor             *
*                                                                     *
***********************************************************************
         EZASMI TYPE=SOCKET,      ISSUE SOCKET MACRO                   X
               AF='INET6',        INET OR IUCV                         X
               SOCTYPE='DATAGRAM', DATAGRAM(UDP)                       X
               PROTO=ZERO,        PROTOCOL                             X
               ERRNO=ERRNO,       (SPECIFY ERRNO FIELD)                X
               RETCODE=RETCODE,   (SPECIFY RETCODE FIELD)              X
               ERROR=ERROR        ABEND IF MACRO ERROR
         BAL   R14,RCCHECK        CHECK FOR SUCCESSFUL CALL
*---------------------------------------------------------------------*

*        Get socket descriptor number
*---------------------------------------------------------------------*
         STH   R8,S               SAVE RETCODE (=SOCKET DESCRIPTOR)
***********************************************************************
*                                                                     *
*        ISSUE GETHOSTID CALL                                         *
*                                                                     *
***********************************************************************
         EZASMI TYPE=GETHOSTID,   ISSUE GETHOSTID MACRO                X
               RETCODE=RETCODE,   (SPECIFY RETCODE FIELD)              X
               ERROR=ERROR        ABEND IF MACRO ERROR
         BAL   R14,RCCHECK        CHECK FOR SUCCESSFUL CALL
         ST    R8,ADDR            SAVE OUR ID

***********************************************************************
*                                                                     *
*        Issue SETSOCKOPT to allow multiple application on the same   *
*            stack to bind to the same multicast address and port.    *
*                                                                     *
***********************************************************************
         EZASMI TYPE=SETSOCKOPT,  ISSUE SETSOCKOPT                     X
               S=S,               SOCKET DESCRIPTOR                    X
               OPTLEN=OPTLEN4,    OPTION LENGTH                        X
               OPTNAME='SO_REUSEADDR', OPTION NAME                     X
               OPTVAL=OPTVALON,   OPTION VALUE                         X
               RETCODE=RETCODE,   (SPECIFY RETCODE FIELD)              X
               ERROR=ERROR        ABEND IF MACRO ERROR
         BAL   R14,RCCHECK         --> CHECK IT

***********************************************************************
*                                                                     *
*        Issue BIND socket                                            *
*                                                                     *
***********************************************************************
         MVC   PORT(2),PORTS      Load port #
         MVC   ADDRESS(16),ADDR   Load IPv6 internet address
         EZASMI TYPE=BIND,        ISSUE BIND MACRO                     X
               S=S,               DATAGRAM                             X
               NAME=NAME,         SOCKET ADDRESS STRUCTURE             X
               RETCODE=RETCODE,   (SPECIFY RETCODE FIELD)              X
               ERROR=ERROR        ABEND IF MACRO ERROR
         BAL   R14,RCCHECK        CHECK FOR SUCCESSFUL CALL

*
* Here you will add code to set the multicast interface, hops,
* or determine if outgoing datagrams are copied to loopback. See the
* next sections for the details.
*

***********************************************************************
*                                                                     *
*        Issue SETSOCKOPT - IPV6_JOIN_GROUP                           *
*                                                                     *
***********************************************************************

*
* Either hard code a multicast address and index or use the
* SIOCGIFNAMEINDEX IOCTL to obtain the interface index from the stack.
*

         MVC   IV6MR_MULTIADD,MY_MULTICAST_ADDRESS
         MVC   IV6MR_INTERFAC,MY_MULTICAST_INTERFACE
         EZASMI TYPE=SETSOCKOPT,  ISSUE SETSOCKOPT                     X
               S=S,               SOCKET DESCRIPTOR                    X
               OPTLEN=OPTLEN20,   OPTION LENGTH                        X
               OPTNAME='IPV6_JOIN_GROUP', OPTION NAME                  X
               OPTVAL=IPV6_MREQ,  OPTION VALUE                         X
               RETCODE=RETCODE,   (SPECIFY RETCODE FIELD)              X
               ERROR=ERROR        ABEND IF MACRO ERROR
         BAL   R14,RCCHECK         --> CHECK IT

*
* Here your program will perform normal processing such as sending or
* receiving messages.
*

***********************************************************************
*                                                                     *
*        Issue SETSOCKOPT - IPV6_LEAVE_GROUP                          *
*                                                                     *
***********************************************************************

*
* Either hard code a multicast address and index or use the
* SIOCGIFNAMEINDEX IOCTL to obtain the interface index from the stack.
*

         MVC   IV6MR_MULTIADD,MY_MULTICAST_ADDRESS
         MVC   IV6MR_INTERFAC,MY_MULTICAST_INTERFACE
         EZASMI TYPE=SETSOCKOPT,  ISSUE SETSOCKOPT                     X
               S=S,               SOCKET DESCRIPTOR                    X
               OPTLEN=OPTLEN20,   OPTION LENGTH                        X
               OPTNAME='IPV6_LEAVE_GROUP', OPTION NAME                 X
               OPTVAL=IPV6_MREQ,  OPTION VALUE                         X
               RETCODE=RETCODE,   (SPECIFY RETCODE FIELD)              X
               ERROR=ERROR        ABEND IF MACRO ERROR
         BAL   R14,RCCHECK         --> CHECK IT
***********************************************************************
*                                                                     *
*        Terminate Connection to API                                  *
*                                                                     *
***********************************************************************
         POST  ECB,1              FOLLOWING IS ALWAYS SYNCH
         EZASMI TYPE=TERMAPI      ISSUE EZASMI MACRO FOR TERMAPI
*
* GETSOCKOPT and SETSOCKOPT parms
*
OPTLEN1  DC    F'1'
OPTLEN4  DC    F'4'
OPTLEN8  DC    F'8'
OPTLEN20 DC    F'20'
OPTVAL4  DC    CL4' '
SAMEINTERFACE DC F'0'
SAMESUBNET DC  F'1'
SAMESITE DC    F'32'
SAMEREGION DC  F'64'
OPTVALON DC    F'1'               OPTVAL field ON
OPTVALOFF DC   F'0'               OPTVAL field OFF
*
* BIND PARMS
*
NAME     DC    0CL16' '           SOCKET NAME STRUCTURE
         DC    AL2(2)             FAMILY
PORT     DC    H'0'               PORT
FLOWINFO DC    F'0'               FLOWINFO
ADDRESS  DC    F'0'               IP ADDRESS
SCOPEID  DC    F'0'               SCOPEID
ADDR     DC    XL16'FF020101010101010505050505050505' IP ADDR TO BIND
PORTS    DC    H'11007'           PORT TO BIND
*
* My Multicast address and interface
*
MY_MULTICAST_ADDRESS DC XL16'FF020101010101010505050505050505'         X
                                  Multicast Address
MY_MULTICAST_INTERFACE DC XL4'0000000E' Interface Index
*
MULTIFO  DC    CL4' '            SOCKET MULTICAST INTERFACE OUTPUT   *
*
         BPXYSOCK DSECT=NO,LIST=YES
IPV6_MREQ        DS 0F                                         01-BPXYS
IPV6MR_MULTIADDR DS CL16       IPv6 Addr                       01-BPXYS
IPV6MR_INTERFACE DS F          Interface Index                 01-BPXYS

Figure 1. IPV6_JOIN_GROUP and IPV6_LEAVE_GROUP

IPV6_LEAVE_GROUP is used to remove a host from the multicast group. You must issue a SETSOCKOPT API and specify the address of the IPV6_MREQ structure containing the IPv6 multicast address and the local IPv6 multicast interface index. See also Figure 1.

While the application is a member of the multicast host group, datagrams may be sent or received as required. To see the multicast groups that are joined on an interface, use the Netstat DEvlinks/-d command. To see the multicast groups that are joined on a socket, use the Netstat ALL/-A command.