MCAST_JOIN_GROUP and MCAST_LEAVE

Use the MCAST_JOIN_GROUP socket option to join a multicast group and set the IPv4 or IPv6 multicast address and the local interface index. Use the SETSOCKOPT API and specify the address of the GROUP_REQ structure that contains the address and the interface index. The application can join multiple multicast groups on a single socket and can also join the same group on multiple interfaces on the same socket. However, there is a maximum limit of 20 groups per single UDP socket and there is a maximum limit of 256 groups per single RAW socket. The stack chooses a default multicast interface if the interface index 0 is passed. The format of the GROUP_REQ structure is in the BPXYSOCK macro. The assembler program example in Figure 1 shows this socket option using the EZASMI macro:

Figure 1. MCAST_JOIN_GROUP and MCAST_LEAVE_GROUP

    ***********************************************************************
    *                                                                     *
    *        Issue SETSOCKOPT - MCAST_JOIN_GROUP                          *
    *                                                                     *
    ***********************************************************************
              
             EZASMI TYPE=SETSOCKOPT,  ISSUE SETSOCKOPT                     X
                   S=S,               SOCKET DESCRIPTOR                    X
                   OPTLEN=OPTL136,    OPTION LENGTH                        X
                   OPTNAME='MCAST_JOIN_GROUP', OPTION NAME                 X
                   OPTVAL=GROUP_REQ1, OPTION VALUE                         X
                   ERRNO=ERRNO,       (SPECIFY ERRNO FIELD)                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 message.
    *

    ***********************************************************************
    *                                                                     *
    *        Issue SETSOCKOPT - MCAST_LEAVE_GROUP                         *
    *                                                                     *
    ***********************************************************************
              
             EZASMI TYPE=SETSOCKOPT,  ISSUE SETSOCKOPT                     X
                   S=S,               SOCKET DESCRIPTOR                    X
                   OPTLEN=OPTL136,    OPTION LENGTH                        X
                   OPTNAME='MCAST_LEAVE_GROUP', OPTION NAME                X
                   OPTVAL=GROUP_REQ1, OPTION VALUE                         X
                   ERRNO=ERRNO,       (SPECIFY ERRNO FIELD)                X
                   RETCODE=RETCODE,   (SPECIFY RETCODE FIELD)              X
                   ERROR=ERROR        ABEND IF MACRO ERROR
             BAL   R14,RCCHECK         --> CHECK IT 


    *
    * GETSOCKOPT and SETSOCKOPT parms
    *
    OPTLEN1  DC    F'1'
    OPTLEN4  DC    F'4'
    OPTLEN8  DC    F'8' 
    OPTL136  DC    F'136' 
    OPTL264  DC    F'264' 
    *------------------------------------------------------*
    * Group_Req Structure
    *------------------------------------------------------*
    GROUP_REQ1   DS  0CL136
    GR_INTF1     DC  XL4'00010005'         Interface Index  
                 DS  CL4                   Padding 
    GR_GROUP1    DS  0CL128                Group Address
                 DC  XL16'10020000E01111110000000000000000'
                 DC  XL112'00'
    *------------------------------------------------------* 
    * Group_Source_Req Structure
    *------------------------------------------------------*
    GSR_REQ1     DS  0CL264
    GSR_INTF1    DC  XL4'00010005'         Interface Index
                 DS  CL4                   Padding 
    GSR_GROUP1   DS  0CL128                Group Address
                 DC  XL16'10020000E01111110000000000000000'
                 DC  XL112'00'   
    GSR_SRCAD1   DS  0CL128                Source Address
                 DC  XL16'10020000424242420000000000000000'
                 DC  XL112'00'

To remove the host from the multicast host group you must issue a SETSOCKOPT call with the MCAST_LEAVE_GROUP option. Using this call is similar to using the MCAST_JOIN_GROUP option because it also uses the GROUP_REQ structure to declare the multicast address and the local interface index. You can also use MCAST_LEAVE_GROUP option to remove all sources for a given multicast group.

While the application is a member of the multicast host group, datagrams can 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.