Documentation is incomplete on how to build with zoslib

[MikeFultonDev]

I wasn't able to compile using the options specified for C. I haven't whittled it to the minimum but found that:

-fzos-le-char-mode=ascii -D_XOPEN_SOURCE=600 -D_ALL_SOURCE -D_OPEN_SYS_FILE_EXT=1 -D_AE_BIMODAL=1 -D_ENHANCED_ASCII_EXT=0xFFFFFFFF  -DZOSLIB_OVERRIDE_CLIB=1 -DZOSLIB_OVERRIDE_CLIB_GETENV=1

worked.
Without at least some of those additional options, the header files spit out numerous errors.

@IgorTodorovskiIBM fyi

[MikeFultonDev]

It also isn't clear how to link... I tried:

clang -L "${ZOSLIB_ROOT}/lib" -lzoslib $TC.o -o $TC

as well as the same with clang++ and both result in a bunch of unresolved refs to C++ functions. Presumably this is because my 'main' is C but it's pulling in C++ code from the archive but I'm not sure how to tell clang/clang++ what to do

@IgorTodorovskiIBM fyi

[MikeFultonDev]

First unresolved ref:

./build
 IEW2456E 9207 SYMBOL
          _ZNSt3__16_ASCII15basic_streambufIcNS0_11char_traitsIcEEE6xsputnEPKcl
          UNRESOLVED.  MEMBER COULD NOT BE INCLUDED FROM THE DESIGNATED CALL
          LIBRARY.
 IEW2456E 9207 SYMBOL
          _ZNSt3__16_ASCII15basic_streambufIcNS0_11char_traitsIcEEE5uflowEv
          UNRESOLVED.  MEMBER COULD NOT BE INCLUDED FROM THE DESIGNATED CALL
          LIBRARY.

[MikeFultonDev]

Found a solution after digging through z/os open tools. It appears I also need -lzoslib-supp (not sure if the celquopt.s.o is required).

clang++ -fzos-le-char-mode=ascii -L "${ZOSLIB_ROOT}/lib" "${ZOSLIB_ROOT}/lib/celquopt.s.o" -lzoslib-supp -lzoslib driver.o $TC.o -o $TC

[MikeFultonDev]

@IgorTodorovskiIBM and @perry-ca : Please confirm/deny the following:

• the zoslib code is a C++ object (either .so or .a).
  • as such, the current clang++ 'bind' step doesn't pull in the required C++ code ,and so zoslib-supp is required.
• the celquopt.so provides the necessary 'initialization code' for a C application to work correctly
• The example should be changed to include the celquopt.s.o and the zoslib-supp archive if doing a static bind

If that's correct, I can take a crack at fixing the C part of the documentation in the readme.

[IgorTodorovskiIBM]

@IgorTodorovskiIBM and @perry-ca : Please confirm/deny the following:

• the zoslib code is a C++ object (either .so or .a).

  • as such, the current clang++ 'bind' step doesn't pull in the required C++ code ,and so zoslib-supp is required.

• the celquopt.so provides the necessary 'initialization code' for a C application to work correctly

• The example should be changed to include the celquopt.s.o and the zoslib-supp archive if doing a static bind

If that's correct, I can take a crack at fixing the C part of the documentation in the readme.

• the zoslib code is a C++ object (either .so or .a). *Correct, we provide a static archive and a shared object)
• as such, the current clang++ 'bind' step doesn't pull in the required C++ code ,and so zoslib-supp is required. Correct, we will update the documentation.
• the celquopt.so provides the necessary 'initialization code' for a C application to work correctly - correct
• The example should be changed to include the celquopt.s.o and the zoslib-supp archive if doing a static bind - **Thanks, we will update this. **

[perry-ca]

the celquopt.so provides the necessary 'initialization code' for a C application to work correctly - correct

Can you double check this. The way the runopts work is LE(?) looks for the CEELQUOPT symbol in the main program. It then reads the option setting from that symbol. I don't think it will find the symbol when it's in a shared lib. The user needs to link in celquopt.s.o into their main program (not any shared libs).

The other caution for the user is that an application can only have one CEELQUOPT. If the user has their own and and zoslib has one then you have a conflict. We should document what options are specified in the zoslib celquopt.s.o and tell the user if they use #pragma runopts that they need to ensure they specify the options needed by zoslib as well. I'd provide a header file with just a #pragma runopts and suggest the user add that to source file that has runopts. I source file can have more than one pragma runopts.

The "C application" should be "C/C++ application".

I suggest saying:

• When linking with zoslib static library, C & C++ applications/shared libs need to link using clang++
• The main program needs to set _CEE_RUNOPTS for zoslib. This is done by one of the following:
  • if your main program has #pragma runopts (i.e. defines CEELQUOPT) to set the _CEE_RUNOPTS options, include the zoslib runopts header
  • otherwise include celquopt.s.o when linking the main program
  • if neither of these are possible, ensure the _CEE_RUNOPTS env var is defined to set the options (provide the list) and is exported