Compiling and linking a program with MASS

This section deals with the specifics of compiling and linking your application with the MASS libraries.

Required compiler options

To compile a program that utilizes any MASS functions, the following compiler options must be used:

FLOAT(IEEE)
ARCHITECTURE(10) - the minimum required ARCH level
ARCHITECTURE(11) - required if you use any MASS SIMD functions
VECTOR - required if you use any MASS SIMD functions
NOEXH - required for C++ applications only

While you might still be able to compile your MASS application without satisfying the above requirements, the program will likely not give correct results.

Compilation step - MASS headers

To use MASS functions in your application, you need to include the appropriate MASS header(s) for the type of MASS function being used (for a complete list of MASS functions available, see Using the MASS scalar library, Using the MASS vector library, and Using the MASS SIMD library).

The default installation of MASS places the MASS headers in your default header search path. If you cannot find the MASS headers in your default search path, contact your system programmer.

The following examples demonstrate the relationship among MASS functions, headers, and libraries, and show how to use MASS in your source program.

Sample 1:

/* Using the MASS-only scalar function 'rsqrt'
   Compile command: xlc -qARCH=10 -qFLOAT=IEEE -c sample1.c
 */
#include <math.h>
#include <mass.h> /* The 'rsqrt' function is declared in <mass.h>, not <math.h> */

int main(void) {
  double input = 16;
  double output;

  output = rsqrt(input);

  /* ... Code to utilize the results in "output" goes here */
}

Sample 2:

/* Using the MASS scalar function 'pow'
   Compile command: xlc -qARCH=10 -qFLOAT=IEEE -c sample2.c
 */

#include <math.h> /* The 'pow' function is declared in <math.h>, not <mass.h> */
#include <mass.h>

int main(void) {

  double base = 3;
  double exponent = 2;
  double output;

  output = pow(base, exponent);

  /* ... Code to utilize the results in "output" goes here */
}

Sample 3:

/* Call the MASS vector function 'vlog2'
   Compile command: xlc -qARCH=11 -qFLOAT=IEEE -c sample3.c
 */

#include <massv.h>

int main(void) {

  int size = 1000;
  double input[size];
  double output[size];

  input[0] = 8;
  input[1] = 16;
  ...
  input[999] = 42;

  vlog2(output, input, &size);

  /* ... Code to utilize the results in "output[]" goes here */
}

Sample 4:

/* Call the MASS SIMD function 'powd2'
   Compile command: xlc -qARCH=11 -qFLOAT=IEEE -qVECTOR -c sample4.c
 */

#include <mass_simd.h>

int main(void) {

   vector double bases = {0, 1};
   vector double exponents = {2, 2};
   vector double output;

   output = powd2(bases, exponents);

  /* ... Code to utilize the results in "output" goes here */
}

Sample 5:

/* Call the MASS scalar functions 'pow' and 'rsqrt', and 
   the vector function 'vlog10'
   Compile command: xlc -qARCH=10 -qFLOAT=IEEE -c sample5.c
 */

#include <math.h>    /* This includes the prototype for 'pow'   */
#include <mass.h>    /* This includes the prototype for 'rsqrt' */
#include <massv.h>   /* This includes the prototype for 'vlog10' */

int main(void) {

   int size = 1000;
   double input[size];
   double result[size];
   int i;

   for (i = 0; i < size; i++) {
      input[i] = i;    /* Trivially initialize the input vector */
   }

   vlog10(result, input, &size);
   double output = pow(result[27], result[525]);

   output = rsqrt(output);

  /* ... Code to utilize the results in "output" goes here */
}

Link step - MASS libraries

IBM provides the MASS library in both USS and MVS. There is no performance difference based on where the library resides. This is simply to allow USS users to link with MASS in USS, and MVS users to link with MASS in MVS.

Although USS users can link with the copy of the MASS libraries which resides in PDS's (and vice-versa), IBM does not recommend this because it does not provide a performance gain, and it adds unnecessary complexity to your build process.

Linking in USS

To link your program with the MASS library, include the appropriate library name(s) with the -l linker option, depending on which type of MASS functions are used, as well as which ARCHITECTURE suboption is used, ARCH(10) or ARCH(11).

-lmass.arch10 or -lmass.arch11 For MASS scalar functions
-lmassv.arch10 or -lmassv.arch11 For MASS vector functions
-lmass_simd.arch11 For MASS SIMD functions

Sample 1

# Link the MASS-only scalar function 'rsqrt'.
# Assume 'sample1.o' was compiled with ARCHITECTURE(10).
xlc sample1.o -lmass.arch10

Sample 2

# Link the MASS scalar function 'pow'.
# Assume 'sample2.o' was compiled with ARCHITECTURE(10).
xlc sample2.o -lmass.arch10

Sample 3

# Link the MASS vector function 'vlog2'.
# Assume 'sample3.o' was compiled with ARCHITECTURE(11).
xlc sample3.o -lmassv.arch11

Sample 4

# Link the MASS SIMD function 'powd2'. 
# Assume 'sample4.o' was compiled with ARCHITECTURE(11).
xlc sample4.o -lmass_simd.arch11

Sample 5

# Link the MASS scalar functions 'pow' and 'rsqrt', and 
# the vector function 'vlog10'. 
# Assume 'sample5.o' was compiled with ARCHITECTURE(10).
xlc sample5.o -lmass.arch10 -lmassv.arch10

Linking in MVS

To link your program with the MASS library under MVS in batch mode, you must prepend the MASS library you want to use to your SYSLIB concatenation.

CBC.SCCNM10 if you are using MASS scalar functions which are also available through <math.h>
CBC.SCCNN10 for all other MASS functions

Note that this only applies to applications that are compiled with ARCHITECTURE(10) (for IBM® zEC12/zBC12 and newer hardware).

The MVS library names for applications that are compiled with ARCHITECTURE(11) (for IBM z13 and newer hardware) are:

CBC.SCCNM11 if you are using MASS scalar functions which are also available through <math.h>
CBC.SCCNN11 for all other MASS functions

For example, if your current SYSLIB concatenation is:

   //SYSLIB   DD DSN=CEE.SCEELKEX,DISP=SHR
   //         DD DSN=CEE.SCEELKED,DISP=SHR
   //         DD DSN=CBC.SCCNOBJ,DISP=SHR

and you want to link each of the sample programs presented above (using NOXPLINK), here are the SYSLIB concatenations you would use:

Sample 1

   //SYSLIB   DD DSN=CBC.SCCNN10,DISP=SHR
   //         DD DSN=CEE.SCEELKEX,DISP=SHR
   //         DD DSN=CEE.SCEELKED,DISP=SHR
   //         DD DSN=CBC.SCCNOBJ,DISP=SHR

Sample 2

   //SYSLIB   DD DSN=CBC.SCCNM10,DISP=SHR
   //         DD DSN=CEE.SCEELKEX,DISP=SHR
   //         DD DSN=CEE.SCEELKED,DISP=SHR
   //         DD DSN=CBC.SCCNOBJ,DISP=SHR

Sample 3

   //SYSLIB   DD DSN=CBC.SCCNN11,DISP=SHR
   //         DD DSN=CEE.SCEELKEX,DISP=SHR
   //         DD DSN=CEE.SCEELKED,DISP=SHR
   //         DD DSN=CBC.SCCNOBJ,DISP=SHR

Sample 4

   //SYSLIB   DD DSN=CBC.SCCNN11,DISP=SHR
   //         DD DSN=CEE.SCEELKEX,DISP=SHR
   //         DD DSN=CEE.SCEELKED,DISP=SHR
   //         DD DSN=CBC.SCCNOBJ,DISP=SHR

Sample 5

   //SYSLIB   DD DSN=CBC.SCCNM10,DISP=SHR
   //         DD DSN=CBC.SCCNN10,DISP=SHR
   //         DD DSN=CEE.SCEELKEX,DISP=SHR
   //         DD DSN=CEE.SCEELKED,DISP=SHR
   //         DD DSN=CBC.SCCNOBJ,DISP=SHR

If you wanted to link the above examples with XPLINK and/or LP64, you would include the exact same data sets for MASS, except your initial SYSLIB would have CEE.SCEEBND2 instead of CEE.SCEELKEX and CEE.SCEELKED.

   //SYSLIB   DD DSN=CEE.SCEEBND2,DISP=SHR
   //         DD DSN=CBC.SCCNOBJ