libzmq-4.2.0

# ZeroMQ on z/OS UNIX System Services ZeroMQ has been successfully built on z/OS, using [z/OS UNIX System Services](http://www-03.ibm.com/systems/z/os/zos/features/unix/), a certified UNIX environment for the [IBM z-series](http://www-03.ibm.com/systems/z/). The build is possible with the shell scripts in this directory, as described below. Tested build combinations: * ZeroMQ 4.0.4, using IBM XL C/C++ compiler, as XPLINK in ILP32 mode * ZeroMQ 4.0.4, using IBM XL C/C++ compiler, as XPLINK in LP64 mode * ZeroMQ 4.1-git, using IBM XL C/C++ compiler, as XPLINK in ILP32 mode Other combinations are likely to work, possibly with minor changes, but have not been tested. Both static library and DLL modes have been tested. There are some minor limitations (detailed below), but all core functionality tests run successfully. ## Quickstart: building ZeroMQ on z/OS UNIX System Services Assuming [z/OS UNIX System Services](http://www-03.ibm.com/systems/z/os/zos/features/unix/) is installed, and the [z/OS XL C/C++ compiler suite](http://www-03.ibm.com/software/products/en/czos) is installed, ZeroMQ can be built as follows: * Download and extract ZeroMQ tar file * Ensure contents of this directory are present at `builds/zos` within that extracted diretory (eg, `zeromq-VERSION/builds/zos/`; copy these files in, if not already present, and make sure the shell scripts are executable) * (Optional) set ZCXXFLAGS for additional compile flags (see below) * Build `libzmq.a` static library and `libzmq.so` dynamic library, with: cd zeromq-VERSION builds/zos/makelibzmq or to skip the `libzmq.so` dynamic library (only building `libzmq.a`): cd zeromq-VERSION BUILD_DLL=false export BUILD_DLL builds/zos/makelibzmq * (Optional, but recommended) build and run the core tests with: cd zeromq-VERSION builds/zos/maketests builds/zos/runtests * To remove built files, to start again (eg, rebuild with different compile/link flags): cd zeromq-VERSION builds/zos/makeclean There are details on specifying alternative compilation flags below. ## Quickstart: using ZeroMQ on z/OS UNIX System Services ### Static linking Install `include/*.h` somewhere on your compiler include path. Install `src/libzmq.a` somewhere on your library search path. Compile and link application with: c++ -Wc,xplink -Wl,xplink ... -+ -o myprog myprog.cpp -lzmq Run with: ./myprog ### Dynamic linking Install `include/*.h` somewhere on your compiler include path. Install `src/libzmq.so` somewhere on your LIBPATH. Install `src/libzmq.x` somewhere you can reference for import linking. Compile and link application: c++ -Wc,xplink -Wc,dll ... -+ -c -o myprog.o myprog.cpp c++ -Wl,xplink -o myprog myprog.o /PATH/TO/libzmq.x Run with: LIBPATH=/DIR/OF/LIBZMQ.SO:/lib:/usr/lib:... # if not in default path export LIBPATH ./myprog ## ZeroMQ on z/OS UNIX System Services: Application considerations z/0S UNIX System Services does not provide a way to block the [`SIGPIPE` signal being generated when a thread writes to a closed socket](http://pic.dhe.ibm.com/infocenter/zvm/v6r2/index.jsp?topic=%2Fcom.ibm.zos.r12.cbcpx01%2Fcbcpg1b0287.htm) (compare with other platforms that support the `SO_NOSIGPIPE` socket option, and/or the `MSG_NOSIGNAL` flag on `send()`; z/OS UNIX System Services supports neither). As a result, applications using ZeroMQ on z/OS UNIX System Services have to expect to encounter `SIGPIPE` at various times during the use of the library, if sockets are unexpectedly disconnected. Normally `SIGPIPE` will terminate the application. A simple solution, if `SIGPIPE` is not required for normal operation of the application (eg, it is not part of a unix pipeline, the traditional use of `SIGPIPE`), is to set `SIGPIPE` to be ignored with code like: #include <signal.h> ... signal(SIGPIPE, SIG_IGN); near the start of the application (eg, before initialising the ZeroMQ library). If `SIGPIPE` is required for normal operation it is recommended that the application install a signal handler that flags the signal was received, and allows the application main loop to determine if it was received for one of its own file descriptors -- and ignores it if it none of the applications own file descriptors seems to have changed. Linking to the `libzmq.a` static library will pull in substantially all of the library code, which will add about 4MB to the application size (per executable statically linked with ZeroMQ). If this is a significant consideration, use of the DLL version is recommended. See also ZeroMQ test status on z/OS UNIX System Services below for other caveats. ## Setting other compilation flags ### Optimisation To build with optimisation: * set `ZCXXFLAGS` to "`-O2`" before starting build process above ### Full debugging symbols To build with debugging symbols: * set `ZCXXFLAGS` to "`-g`" before starting build process above ### 64-bit mode (LP64/amode=64) To build in 64-bit mode: The default build is [ILP32](http://publib.boulder.ibm.com/infocenter/zvm/v6r1/index.jsp?topic=/com.ibm.zos.r9.cbcux01/lp64cop.htm), the default for the IBM XL C/C++ compiler. To build in LP64 mode (64-bit): * set `ZCXXFLAGS` to "`-Wc,lp64 -Wl,lp64`" before starting build (64-bit mode can be combined with optimisation or debug symbols.) ### Combining compilation flags Other build flags can be used in `ZXCCFLAGS` if desired. Beware that they are passed through (Bourne) shell expansion, and passed to both the compile and link stages; some experimentation of argument quoting may be required (and arguments requiring parenthesis are particularly complicated). ## ZeroMQ test status on z/OS UNIX System Services As of 2014-07-22, 41 of the 43 tests in the core ZeroMQ test suite pass. There are two tests that are expected to fail: 0. `test_abstract_ipc`: tests Linux-specific IPC functions, and is expected to fail on non-Linux platforms. 0. `test_fork`: tests ability to use ZeroMQ both before *and* after fork (and before exec()); this relies on the ability to use pthreads both before *and* after fork. On z/OS (and some other UNIX compliant platforms) functions like `pthreads_create` (used by ZeroMQ) cannot be used after fork and before exec; on z/OS the call after fork fails with `ELEMULTITHREADFORK` (errno=257) if ZeroMQ was also used before fork. (On z/OS it appears possible to use z/OS *after* fork, *providing* it has not been used before fork -- the problem is the two separate initialisations of the threading library, before and after fork, attempting to mix together.) In practice this is unlikely to affect many real-world programs -- most programs use threads or fork without exec, but not both. 0. `test_diffserv`: tests ability to set IP_TOS ([IP Type of Service](http://en.wikipedia.org/wiki/Type_of_service), or [DiffServ](http://en.wikipedia.org/wiki/Differentiated_Services_Code_Point)) values on sockets. While z/OS UNIX System Services has the preprocessor defines required, it appears not to support the required functionality (call fails with "EDC8109I Protocol not available.") These three "expected to fail" tests are listed as XFAIL_TESTS, and `runtests` will still consider the test run successful when they fail as expected. (`builds/zos/runtests` will automatically skip these "expected to fail" tests if running "all" tests.) In addition `test_security_curve` does not do any meaningful testing, as a result of the CURVE support not being compiled in; it requires [`libsodium`](http://doc.libsodium.org/), which has not been ported to z/OS UNIX System Services yet. Multicast (via `libpgm`) is also not ported or compiled in. [TIPC](http://hintjens.com/blog:70), a cluster IPC protocol, is only supported on Linux, so it is not compiled