The binder C/C++ API provides a header file (__iew_api.h), which allows C/C++ programs to interface with binder API and fast data access services more naturally in a C/C++ environment. The header file includes the following:

• API macros
  The following macros are used to control the behavior of C/C++ APIs:

  _IEW_TARGET_RELEASE

  This feature test macro is used to control the expansion of the header file (__iew_api.h). To use the macro, define it to the desired value before you define the #include <__iew_api.h>. Declarations made by __iew_api.h correspond to the function available with the specified release. The following macros are valid values for _IEW_TARGET_RELEASE:

  • _IEW_ZOSV1R9_
  • _IEW_ZOSV1R10_
  • _IEW_ZOSV1R11_
  • _IEW_ZOSV1R12_
  • _IEW_ZOSV1R13_
  • _IEW_ZOSV2R1_
  • _IEW_CURRENT_

  The default value is defined to the _IEW_ZOSV1R9_ macro.

  It is suggested that you use the _IEW_TARGET_RELEASE macro as the __release value with both the __iew_openW() and the __iew_fd_open() functions. This feature test macro is always a valid value for _IEWTargetRelease. Using the feature test macro with these APIs ensures that values returned by all the APIs are consistent with the declarations made by the __iew_api.h header.

  Note:

  1. If you do not define the feature test macro to _IEW_ZOSV1R9_, _IEW_ZOSV1R10_, _IEW_ZOSV1R11_, _IEW_ZOSV1R12_, _IEW_ZOSV1R13_or _IEW_ZOSV2R1_, a compile-time error occurs.
  2. If you do not use the same value of the feature test macro when defining applications, parts of the application might incorrectly interpret the results of some API calls.

  _IEW_ZOSV1R9_

  This macro is used to identify the release z/OS® V1.9. Use the macro with the feature test macro _IEW_TARGET_RELEASE.

  _IEW_ZOSV1R10_

  This macro is used to identify the release z/OS V1.10. Use the macro with the feature test macro _IEW_TARGET_RELEASE.

  _IEW_ZOSV1R11_

  This macro is used to identify the release z/OS V1.11. Use the macro with the feature test macro _IEW_TARGET_RELEASE.

  _IEW_ZOSV1R12_

  This macro is used to identify the release z/OS V1.12. Use the macro with the feature test macro _IEW_TARGET_RELEASE.

  _IEW_ZOSV1R13_

  This macro is used to identify the release z/OS V1.13. Use the macro with the feature test macro _IEW_TARGET_RELEASE.

  _IEW_ZOSV2R1_

  This macro is used to identify the release z/OS V2.1. Use the macro with the feature test macro _IEW_TARGET_RELEASE.

  _IEW_CURRENT_

  This macro is used to identify the current z/OS release. Use the macro with the feature test macro _IEW_TARGET_RELEASE. By using this value, you can always use the most current binder capabilities.

  Note: All the parts that comprise an application must have the same value for _IEW_TARGET_RELEASE. If you define _IEW_TARGET_RELEASE to _IEW_CURRENT_, and subsequently the system is upgraded to a new z/OS release, the value of _IEW_CURRENT_ might different than it was in the prior z/OS release. It is not necessary to recompile the application, the application continues to operate using the _IEW_TARGET_RELEASE at which it was compiled. However, if you want to recompile any parts of the application, you must recompile all parts of the application to ensure that all the parts in the application use the same _IEW_TARGET_RELEASE.

• API data types

  The API data types are used by API access and utilities functions. They allow for data encapsulation and as a convenient way for parameters passing.

• Buffer header and entry definition for each buffer type

  The buffer header and buffer entry definition for each buffer type are based on the version 6 and later API buffer formats as described in Binder API buffer formats.

• Binder API access functions

  __iew_addA()         __iew_alignT()          __iew_alignT2() 
  __iew_alterW()       __iew_autoC()           __iew_bindW()           
  __iew_closeW()       __iew_getC()            __iew_getD()            
  __iew_getE()	         __iew_getN()            __iew_import()          
  __iew_includeName()  __iew_includePtr()      __iew_includeSmde()     
  __iew_includeToken() __iew_insertS()         __iew_loadW()           
  __iew_openW()        __iew_orderS()          __iew_putD()           
  __iew_rename()       __iew_resetW()          __iew_saveW()           
  __iew_setL()         __iew_setO()            __iew_startS()

• Binder API utilities functions

  __iew_api_name_to_str()  __iew_create_list()      __iew_eod()
  __iew_get_reason_code()  __iew_get_return_code()  __iew_get_cursor()
  __iew_set_cursor()

• Fast data access functions

  __iew_fd_end()        __iew_fd_getC()          	__iew_fd_getD()
  __iew_fd_getE()       __iew_fd_getN()          __iew_fd_open()
  __iew_fd_startDcb()   __iew_fd_startDcbS()     	__iew_fd_startName()
  __iew_fd_startToken()

• Fast data utilities functions

  __iew_fd_eod()                	__iew_fd_get_reason_code()
  __iew_fd_get_return_code()    __iew_fd_get_cursor()
  __iew_fd_set_cursor()	

C/C++ header file __iew_modmap.h declares the structures which are used in the binder module map IEWBMMP. IEWBMMP is usually produced by using the binder MODMAP option, and it is described inModule Map. This header allows a C/C++ program to more easily reference the module map (whether reading it directly or by using the binder APIs).

These side-deck and DLL pairs must be used together. For example, since SYS1.SIEASID(IEWBNDDX) corresponds to DLL name IEWBNDDX, if your application is bound with this side-deck it will use the DLL named IEWBNDDX, which is installed into both /usr/lib and SYS1.SIEAMIGE. There are no functional differences between same-named DLLs which are just installed into different locations (UNIX filesystem and MVS data set).

Refer to z/OS Language Environment Programming Guide for rules on how DLLs are located and loaded from these different locations. Also note that since SYS1.SIEAMIGE is automatically part of the MVS LNKLST, there is normally no need to explicitly set the search order. On the other hand, while IBM® recommends that /usr/lib be on the LIBPATH environment variable via /etc/profile, it is not required. Nor is LIBPATH set by default for programs executed where the login shell has not been run (such as from batch).