This member contains corrections and additions to the OS/390 2.6.0 C/C++ documentation: ======================================================================== 1. The OS/390 V2R4.0 C/C++ SOM-Enabled Class Library User's Guide and Reference (SC09-2366-02) has been reshipped for V2R6.0. Please observe the following when using this manual: a. Section "Using the Cross-language SOM Collection Class Library" (topic 1.1.5). The Interface Repository (IR) for the cross-language SOM collection classes is provided in the CBC.SCLBXL.IR data set. The copy job CBC.SCLBJCL(CLB3JXIR) will copy the Interface Repository file from the data set CBC.SCLBXSM(CLB3XR00) to the sequential file CBC.SCLBXL.IR. Please talk to your system programmer if this sequential file CBC.SCLBXL.IR has not been generated. b. In this release of OS/390, "OpenEdition" has been renamed to "OS/390 UNIX System Services" or "OS/390 UNIX" (the short form). Interpret any reference to "OpenEdition" in this book as "OS/390 UNIX". c. Sections "About this Book" (topic FRONT_2) and "About IBM OS/390 C/C++" (topic FRONT_3) Please refer to these sections in any of the other V2R6.0 books in this library, as these sections have been updated for V2R6.0. ======================================================================== 2. OS/390 C/C++ Users Guide (Doc No SC09-2361-03) Chapter "Compiler Options" page 151 (topic 2.3.16.65). The compiler option "Target" should be replaced with the following: This information is to assist you when using APAR PQ20789 (PTFs UQ90002 and UQ90003). TARGET _____________________________________________________________ | | | ACCEPTED BY | SPECIAL IPA PROCESSING | | C | C++ | IPA LINK |___________________________| | | | | IPA COMPILE | IPA LINK | |______|_________|_______________|_____________|_____________| | YES | YES | YES | YES | YES | |______|_________|_______________|_____________|_____________| DEFAULT: TARGET(LE, CURRENT) CATEGORY: Program Execution and Object Code Control .-,-----------------. V | >>-TARG----(-----+-------------+--+---)---------------------->< +-+-LE--+-----+ | '-IMS-' | '-+-CURRENT-+-' '-OSV1R2--' The TARGET option specifies the Runtime Environment and OS/390 Release for which the object module is to be generated. To use this option, select a Run-Time Environment of either LE or IMS. Then select the OS/390 Release, CURRENT or OSV1R2. If you do not select a Run-Time Environment or OS/390 Release the default is TARGET(LE,CURRENT). TARGET() Generates object code to run under OS/390 Language Environment. It is the same as TARGET (LE,CURRENT). The following suboptions target the Run-Time Environment: TARGET(LE) Generates object code to run under OS/390 Language Environment. This is the default. TARGET(IMS) Generates object code to run under the Information Management System (IMS). If you are compiling the main program, you must also specify the PLIST(OS) option. For more information about these suboptions refer to the topic TARGET Run-Time Environment Suboptions (LE,IMS) below. The following suboptions target the OS/390 Release at program run time: TARGET(CURRENT) Generates object code to run under the current version (OSV2R6) of OS/390. This is the default. TARGET(OSV1R2) Generates object code to run under OS/390 Version 1 Release 2 and subsequent releases. For more information about these suboptions refer to the section Target OS/390 Release Suboptions (CURRENT,OSV1R2) below. The compiler generates a comment that indicates the value of TARGET in your object module to aid you in diagnosing problems in your program. If you specify the TARGET compile option more than once, the compiler uses the last set of specified suboptions. TARGET OS/390 Release Suboptions (CURRENT,OSV1R2) The Target(OSV1R2) compiler option will allow you to generate code that can be executed on an OS/390 Version 1 Release 2 system and subsequent releases. In order to use this compiler option, you must utilize data sets for the Language Environment and Class Libraries from the appropriate level of OS/390. To generate code that can be executed on a OS/390 Version 1 Release 1 system refer to Informational APAR II11575, which is available on the World Wide Web at: http://www.software.ibm.com/ad/c390/service/ii11575.html. For example, to generate code to execute on an OS/390 V1R3 system, use OS/390 V1R3 Language Environment and Class Library data sets during the assembly, compilation and link-edit phases of application development on the OS/390 V2R6 system. This compiler option will not allow you to exploit new functions provided on the higher level OS/390 system, but rather allow you to build an application on a higher level OS/390 system and execute that application on a lower level OS/390 system. Restrictions for C/C++ All INPUT LIBRARIES used during the application build process must be the appropriate level for the target OS/390 system. * For the compile step: STEPLIB - use the OS/390 V2R6 C/C++ Compiler and Language Environment (SCBCCMP and SCEERUN) Header Files - use the Language Environment and Class Library header files from the target OS/390 system (SCEEH.+ and SCLBH.+) * For the prelink step: STEPLIB - use the OS/390 V2R6 Language Environment (SCEERUN) SYSLIB - use the Language Environment and Class Library object data sets from the target OS/390 system (SCEECPP, SCEEOBJ, SCLBCPP, SCLBOBC and SCLBOXL) Definition Sidedecks - use the Class Library definition sidedecks from the target OS/390 system (SCLBSID) Note: If you are targetting OS/390 V1R2 and using the Application Support or Collection Class Libraries then ensure you reference the definition sidedecks/DLLs APPSUPP and COLLECT instead of ASCCOLL, and APPSUBC and COLLRRBC instead of ASCOLSOM. With the merging of the Application Support and Collection Class Library DLLs in OS/390 V1R3 your development environment may reference the merged DLLs. * For the link step: SYSLIB - use the Language Environment link-edit stubs from the target OS/390 system (SCEELKED) * For the bind step: SYSLIB - use the Language Environment link-edit stubs from the target OS/390 system (SCEELKED and SCEELKEX) - use the Language Environment and Class Library object data sets from the target OS/390 system (SCEECPP, SCEEOBJ, SCLBCPP, SCLBOBC and SCLBOXL) Definition Sidedecks - use the Class Library definition sidedecks from the target OS/390 system (SCLBSID) Note: If you are targetting OS/390 V1R2 and using the Application Support or Collection Class Libraries then ensure you reference the definition sidedecks/DLLs APPSUPP and COLLECT instead of ASCCOLL, and APPSUBC and COLLRRBC instead of ASCOLSOM. With the merging of the Application Support and Collection Class Library DLLs in OS/390 V1R3 your development environment may reference the merged DLLs. * Ensure that any other libraries incorporated in the application, are compatible with the target OS/390 system. For information on the appropriate level of Language Environment data sets to be used with these suboptions, refer to the Informational APAR II11316, which describes the contents of the data sets for the OS/390 releases and how to move them to a higher level of OS/390. This Informational APAR is available on the World Wide Web at: http://www.s390.ibm.com/le/assist/support/ii11316.html. For information on the appropriate level of Class Library data sets to be used with these suboptions, refer to the Informational APAR II11316, which describes the contents of the data sets for the OS/390 releases and how to move them to a higher level of OS/390. This Informational APAR is available on the World Wide Web at: http://www.software.ibm.com/ad/c390/service/ii11576.html. While there are no restrictions on the use of ARCH and TUNE with TARGET, ensure that the level specified is consistent with the target hardware. TARGET Suboption Restrictions CURRENT: * None. OSV1R2: * The MACRO_TARGET_LIB_ will be set to X'21020000'. The _BFP_ macro will not be defined. * The compiler disables the language feature long long and issues error messages if encountered in the source code. * The compiler ignores the following options and issues a warning message: FLOAT() Default behaviour is FLOAT(HEX). ROUND() Default behaviour is ROUND(N). DLL(CBA) Default behaviour is DLL(NOCBA). Restrictions for C TARGET(OSV1R2) is not permitted in a #pragma options directive. If you specify TARGET(OSV1R2) on the command line, and one or more of the disallowed options appears in a #pragma options directive, the compiler issues a warning message and disables the option. Effect on IPA Compile Step If you specify the TARGET option for any compilation unit in the IPA compile step, the compiler generates information for the IPA link step. This option also affects the regular object module if you request one by specifying the IPA(OBJECT) option. The user is responsible for ensuring that all IPA Object files are compiled with the appropriate header library files. Effect on IPA Link Step If you specify TARGET on the IPA Link step, it overrides the TARGET value that you specified for the IPA Compile step. The IPA Link step accepts the CURRENT and OSV1R2 suboptions. However, when using TARGET suboptions ensure that: * All IPA Object files are compiled with the appropriate TARGET suboption and header files. * All non IPA Object files are compiled with the appropriste TARGET suboption and header files. * All other input libraries are compatible with the specified OS/390 run-time release. TARGET Run-Time Environment Suboptions (LE,IMS) The TARGET Run-Time Enivronment Suboption allows you to select a Run-Time Environment of either LE or IMS. Effect on IPA Compile Step If you specify the TARGET option for any compilation unit in the IPA Compile step, the compiler generates information for the IPA Link step. This option also affects the regular object module if you request one by specifying the IPA(OBJECT) option. Effect on IPA Link Step If you specify TARGET on the IPA Link step, it has the following effects: * It overrides the TARGET value that you specified for the IPA Compile step. * It overrides the value that you specified for #pragma runopts(ENV). If you specify TARGET(LE) or (TARGET(), the IPA Link step sets the value of #pragma runopts(ENV) to OS/390. If you specify TARGET(IMS), the IPA Link step sets the value of #pragma runopts(ENV) to IMS. * It may override the value that you specified for #pragma runopts(PLIST) or the PLIST compiler option. If you specify TARGET(LE) or TARGET(), and you set the value set for the PLIST option to something other than HOST, the IPA Link step sets the values of #pragma runopts(PLIST) and the PLIST compiler option to IMS. If you specify TARGET(IMS), the IPA Link step TARGET(IMS), the IPA Link step unconditionally sets the values of the PLIST compiler option and #pragma runopts(PLIST) to IMS. ======================================================================== 3. OS/390 C/C++ Programming Guide (Doc No SC09-2362-03) a. Chapter 'Combining C or C++ and Assembler". Example "CBC3GA6" page 254-256, (Topic 3.2.6.2.1). Example CBC3GA6 should be replaced with the following: CBC3GCA6 TITLE 'TESTING PREINITIALIZED C PROGRAMS' ***------------------------------------------------------------- *** this example shows how to preinitialize a C program *** part 1 of 3 (other files are CBC3GCA7 and CBC3GCA8) *** Function: Demonstrate the use of Preinitialized C programs *** Requests used: INIT, CALL, TERM *** Parameters to C program: FILE_NAME, RUN_INDEX *** Return from C Program: RUN_INDEX ***------------------------------------------------------------- CBC3GCA6 CSECT CBC3GCA6 RMODE ANY CBC3GCA6 AMODE ANY EXTRN CEESTART C Program Entry STM R14,R12,12(R13) Save registers BALR R3,0 Set base register USING *,R3 Establish addressability ST R13,SVAR+4 Set back chain LA R13,SVAR Set this module's save area ***------------------------------------------------------------- *** Initialize ***------------------------------------------------------------- P_INIT DS 0H MVC P_RQ,INIT Set INIT as the request LA R1,PALIPT Load Parameter pointer L R15,CEP Load C Entry Point BALR R14,R15 Invoke C Program ***------------------------------------------------------------- *** The C environment has been established. *** Parameters include RUN_INDEX which will be counted down *** by the C program. When the RUN_INDEX is zero, termination *** will be requested. *** The following code will set up C program parameters and *** CALL request, invoke the C program and test for termination. ***------------------------------------------------------------- LA R1,PGPAPT Pointer to C program parameters ST R1,EP_PGPA ... to extended parameter list DO_CALL DS 0H MVC P_RQ,CALL set up CALL request LA R1,PALIPT set parameter pointer L R15,CEP set entry point BALR R14,R15 invoke C program L R0,RUN_INDEX Test Return Code LTR R0,R0 BNZ DO_CALL Repeat CALL ***------------------------------------------------------------- *** C requested termination. *** Set up TERM request and terminate the environment ***------------------------------------------------------------- DO_TERM DS 0H MVC P_RQ,TERM set up TERM request SR R1,R1 mark no parameters ST R1,EP_PGPA LA R1,PALIPT set parameter pointer L R15,CEP set entry point BALR R14,R15 invoke termination ***------------------------------------------------------------- *** Return to system ***------------------------------------------------------------- XIT DS 0H L R13,4(13) LM R14,R12,12(13) BR R14 ***------------------------------------------------------------- *** Constants and work areas ***------------------------------------------------------------- VARCON DS 0D PALIPT DC A(X'80000000'+PALI) Address of Parameter list CEP DC A(CEESTART) Entry point address ***------------------------------------------------------------- PALI DS 0F Parameter list P_LG DC H'16' Length of the list DC H'0' Must be zero P_RQ DC CL8' ' Request - INIT,CALL,TERM,EXECUTE P_EP_PT DC A(EPALI) Address of extended plist ***------------------------------------------------------------- EPALI DS 0F Extended Parameter list DC A(EP_LG) Length of this list EP_TCA DC A(0) First token EP_PRV DC A(0) Second token EP_PGPA DC A(PGPAPT) Address of C program plist EP_XOPT DC A(XOPTPT) Address of run-time options EP_LG EQU *-EPALI Length of this list ***------------------------------------------------------------- *** C program plist in argc, argv format ***------------------------------------------------------------- PGPAPT DC F'3' Number of parameters (argc) DC A(PGVTPT) parameter vector pter (argv) PGVTPT DS 0A Parameter Vector DC A(PGNM) Program name pointer (argv1) DC A(FILE_NAME) File name pointer (argv2) DC A(RUN_INDEX) Run index pointer (argv3) DC XL4'00000000' NULL pointer ***------------------------------------------------------------- *** Run-Time options ***------------------------------------------------------------- XOPTPT DC A(X'80000000'+XOPTLG) Run-Time options pter XOPTLG DC AL2(XOPTSQ) Run-Time option list length XOPTS DC C'STACK(4K) RPTSTG(ON)' Run-Time options list XOPTSQ EQU *-XOPTS Run-Time options length ***------------------------------------------------------------- PGNM DC C'CBC3GCA7',X'00' C program name FILE_NAME DC C'PREINIT.DATA',X'00' File name for C program RUN_INDEX DC F'5',X'00' changed by C Program ***------------------------------------------------------------- *** Request strings for preinitialization ***------------------------------------------------------------- INIT DC CL8'INIT' CALL DC CL8'CALL' TERM DC CL8'TERM' EXEC DC CL8'EXECUTE' ***------------------------------------------------------------- *** Assembler program's register save area ***------------------------------------------------------------- SVAR DC 18F'0' LTORG ***------------------------------------------------------------- *** Register definitions ***------------------------------------------------------------- R0 EQU 0 R1 EQU 1 R2 EQU 2 R3 EQU 3 R4 EQU 4 R5 EQU 5 R6 EQU 6 R7 EQU 7 R8 EQU 8 R9 EQU 9 R10 EQU 10 R11 EQU 11 R12 EQU 12 R13 EQU 13 R14 EQU 14 R15 EQU 15 END b. Chapter 'Combining C/C++ and Assembler". Example CBC3GA7", page 257 (Topic 3.2.6.2.2). Example CBC3GA7 should be replaced with the following: /* this example shows how to use a preinitializable program */ /* part 2 of 3 (other files are CBC3GCA6 and CBC3GCA8) */ #pragma runopts(PLIST(MVS)) #include #include #define MAX_MSG 50 #define MAX_FNAME 8 typedef int (*f_ptr)(int, char*); /* pointer to function returning int */ int main(int argc, char **argv) { FILE *fp; /* File to be written to */ int *ptr_run; /* Pointer to the "run index" */ char *ffmsg; /* a pointer to the "fetched function msg" */ char fname??(MAX_FNAME+1??); /* name of the function to be fetched */ int fetch_rc; /* Return value of function invocation */ f_ptr fetch_ptr; /* Function pointer to fetched function */ /* Get the pointer to the "run index" */ ptr_run = (int *)argv??(2??); if ((fp = fopen(argv??(1??),"a")) == NULL) { printf("Cannot open file %s\n",argv??(1??)); *ptr_run = 0; /* Set to zero so it won't be called again */ return(0); /* Return to Assembler program */ } /* Write the record to the file */ fprintf(fp,"Run index was %d.\n",*ptr_run); /* Allocate the message returned from the fetched function */ if (( ffmsg=(char *)malloc(MAX_MSG + 1)) == NULL ) printf("ERROR -- malloc returned NULL\n"); /* fetch the function */ fetch_ptr = (f_ptr) fetch("MYFUNC"); if (fetch_ptr == NULL) printf("ERROR - Fetch returned a null pointer\n"); /* execute the function */ fetch_rc = fetch_ptr(*ptr_run, ffmsg); /* Write the function msg to file */ fprintf(fp,"%s\n",ffmsg); /* Tell the user the value of the "run index" */ printf("Run index was %d.\n",*ptr_run); /* Decrement the "run index" */ (*ptr_run)--; /* Remember to close all opened files */ fclose(fp); /* Remember to free all allocated storage */ free( fname ); /* Remember to release all fetched modules */ release((void(*)())fetch_ptr); /* Return to Assembler program */ return(0); } c. Chapter 'Combining C or C++ and Assembler". Example "CBC3GA8" page 258, (Topic 3.2.6.2.3). Example CBC3GA8 should be replaced with the following: /* this example shows how to use a preinitializable program */ /* part 3 of 3 (other files are CBC3GCA6 & CBC3GCA7) */ #include #pragma linkage(fetched, fetchable) int fetched(int run_index, char *ffmsg) { sprintf(ffmsg,"Welcome to myfunc: Run index was %d.",run_index); return(0); } d. Chapter "Combining C or C++ and Assembler", "Calling a Preinitializable Program", page 259, (Topic 3.2.6.2.7). The sample JCL used to run a Preinitializable Program in an OS/390 envirnonment should be replaced with the following: //youridA JOB //* // SET LIB='CEE' // SET CMP='CBC' //* //PROCLIB JCLLIB ORDER=(&CMP..SCBCPRC) //*================================================================= //*---------------------------------------------------------- //* ASSEMBLE THE DRIVING ASSEMBLER PROGRAM //*---------------------------------------------------------- //HLASM EXEC PGM=ASMA90, // PARM='NODECK,OBJECT,LIST,ALIGN' //SYSPRINT DD SYSOUT=* //SYSLIB DD DSN=SYS1.MACLIB,DISP=SHR //SYSUT1 DD UNIT=VIO,DISP=(NEW,DELETE),SPACE=(32000,(30,30)) //SYSUT2 DD UNIT=VIO,DISP=(NEW,DELETE),SPACE=(32000,(30,30)) //SYSUT3 DD UNIT=VIO,DISP=(NEW,DELETE),SPACE=(32000,(30,30)) //SYSPUNCH DD DUMMY //SYSLIN DD DSN=&&OBJECT(ASSEM),SPACE=(80,(400,400,5)), // DISP=(,PASS),UNIT=VIO,DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) //SYSIN DD DSN=yourid.CBC3GCA6.ASM,DISP=SHR //*================================================================= //*--------------------------------------------- //* COMPILE THE MAIN C PROGRAM //*---------------------------------------------- //COMP EXEC EDCC,INFILE='yourid.CBC3GCA7.C', // OUTFILE='&&OBJECT(CMAIN),DISP=(OLD,PASS)', // CPARM='NOOPT,NOSEQ,NOMAR', // LIBPRFX=&LIB.,LNGPRFX=&CMP. //*================================================================= //*--------------------------------------------- //* COMPILE AND LINK THE FETCHED C PROGRAM //*---------------------------------------------- //CMPLK EXEC EDCCL,INFILE='yourid.CBC3GCA8.C', // CPARM='NOOPT,NOSEQ,NOMAR', // LIBPRFX=&LIB.,LNGPRFX=&CMP. //LKED.SYSLMOD DD DSN=&&LOAD(MYFUNC),DISP=(,PASS), // UNIT=VIO,SPACE=(TRK,(1,1,5)) //*================================================================= //*-------------------------------------------------- //* LINK THE ASSEMBLER DRIVER AND MAIN C PROGRAM //*-------------------------------------------------- //LKED EXEC PGM=IEWL,PARM='MAP,XREF,LIST', // COND=((4,LT,HLASM),(4,LT,COMP.COMPILE),(4,LT,CMPLK.LKED)) //OBJECT DD DSN=&&OBJECT,DISP=(OLD,PASS) //SYSLIN DD * INCLUDE OBJECT(ASSEM) INCLUDE OBJECT(CMAIN) ENTRY CBC3GCA6 /* //SYSLIB DD DISP=SHR,DSN=&LIB..SCEELKED //SYSPRINT DD SYSOUT=* //SYSUT1 DD DSN=&&SYSUT1,UNIT=VIO,SPACE=(CYL,(1,1)) //SYSLMOD DD DSN=&&LOAD(PREINIT),DISP=(OLD,PASS) //*================================================================= //*-------------------------------------------------- //* RUN //*-------------------------------------------------- //GO EXEC PGM=*.LKED.SYSLMOD, // COND=(4,LT,LKED) //STEPLIB DD DISP=OLD,DSN=&&LOAD // DD DISP=SHR,DSN=&LIB..SCEERUN //STDIN DD SYSOUT=* //STDOUT DD SYSOUT=* //STDERR DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* ======================================================================== 4. OS/390 C/C++ IBM Open Class Users Guide (Doc No SC09-2363-03) Chapter "Element Functions and Key-Type Functions ". Section "Element Pointers" page 114 (topic 4.3.6.2). Replace the example that begins: "The following example shows the main file", with the following: //main.cpp - main file #include "person.h" //person.h from the previous example #include #include typedef IMngPointer ManagedPersonPtr; typedef ISet AddressList; ostream& operator<<(ostream& os,Person A) { return (os << endl << A.GetPersonName() <<" "<>-+-PHASEID---+----------------------------------------------->< '-NOPHASEID-' If you specify the PHASEID option, it causes each compiler module (phase) to issue an informational message as the phase begins execution. This message identifies the compiler phase module name, product id, and build level. The compiler issues a separate CBC0000(I) message each time compiler execution causes a given compiler module(phase) to be entered. This may be many times for a given compilation. Use the PHASEID option to assist you with determining the maintenance level of each compiler component(phase). The FLAG option has no effect on the PHASEID informational message. Effect on IPA Compile Step The PHASEID option has the same effect on the IPA Compile Step as it does on a regular compilation. Effect on IPA Link Step The IPA Link step uses the PHASEID option that you specify for that step. ======================================================================== 6. OS/390 C/C++ User's Guide (Doc No SC09-2361-03) Chapter 12 "Binding OS/390 C/C++ Programs" Section "When You Cannot Use the Binder" (Pg 283, topic 3.4.2) The statement: "The following are the restrictions to using the binder." should be replaced with: "The following are the restrictions to using the binder to produce a program object." The section on "CICS" (topic 3.4.2.2) should be replaced with: "You cannot target PM3 type program objects (which must be installed in in a PDSE) for execution under CICS using the binder." ======================================================================== 7. OS/390 C/C++ User's Guide (Doc No SC09-2361-03) The descriptions for the ARCHITECTURE (topic 2.3.16.4) and TUNE (topic 2.3.16.69) compiler options should be replaced with the following: ARCHITECTURE _____________________________________________________________ | | | ACCEPTED BY | SPECIAL IPA PROCESSING | | C | C++ | IPA LINK |___________________________| | | | | IPA COMPILE | IPA LINK | |______|_________|_______________|_____________|_____________| | YES | YES | YES | YES | YES | |______|_________|_______________|_____________|_____________| DEFAULT: ARCHITECTURE(0) CATEGORY: Object Code Control >>-ARCH--(--n--)----------------------------------------------->< The ARCH option selects the instruction set available during the code generation of your program based on the specified machine architecture. Specifying a higher ARCH level generates code that uses newer and faster instructions instead of the sequences of common instructions. A subparameter specifies the group to which a model number belongs. Note that your application will not run on a lower architecture processor than what you specified using the ARCH option. Use the ARCH level that matches the lowest machine architecture where your program will run. Use the ARCH option in cooperation with the TUNE option. For more information on the interaction between ARCH and TUNE, see TUNE. If you specify a group which does not exist or is not supported, the compiler uses the default, and issues a warning message. Current groups of models that are supported include the following: 0 Is the default value. It produces code that is executable on all models. 1 Produces code that uses instructions available on the following models: 9021-520, 9021-640, 9021-660, 9021-740, 9021-820, 9021-860, and 9021-900 9021-xx1 and 9021-xx2 9672-Rx1, 9672-Rx2 (G1), 9672-Exx, and 9672-Pxx Specifically, these ARCH(1) machines and their follow ons add the C Logical String Assist hardware instructions. These instructions are exploited by the compiler, when practical, for a faster and more compact implementation of some functions, for example, memcmp(). 2 Produces code that uses instructions available on the following models: 9672-Rx3 (G2), 9672-Rx4 (G3), 9672-Rx5 (G4), and 2003 Specifically, these ARCH(2) machines and their follow ons add the Branch Relative instruction (Branch Relative and Save - BRASH), and the Immediate instruction set (for example, Add Halfword Immediate - AHI) which may be exploited by the compiler for faster processing. 3 Produces code that uses instructions available on the 9672-Rx6 (G5), 9672-Rx7 (G6), and follow on models. Specifically, these ARCH(3) machines and their follow ons add a set of facilities for IEEE floating-point representation, as well as 12 additional floating-point registers and some new floating-point support instructions may be exploited by the compiler. Note that ARCH(3) is required for execution of a program that specifies the FLOAT(IEEE) compiler option. However, if the program is executed on a physical processor that does not actually provide these ARCH(3) facilities, the resultant program-check (operation exception) will be intercepted by the underlying OS/390 V2R6 or higher operating system, and transparently simulated by software. There will be a significant performance degradation for the simulation. Notes: 1. Code that is compiled at ARCH(1) runs on machines in the ARCH(1) group and later machines, including those in the ARCH(2) group. It may not run on earlier machines. Code that is compiled at ARCH(2) may not run on ARCH(1) or earlier machines. 2. For the above system machine models, x indicates any value. For example, 9672-Rx4 means 9672-RA4 through to 9672-RX4, not just 9672-RX4. You can specify this option using the #pragma option directive for C. Effect on IPA Compile Step If you specify the ARCHITECTURE option for any compilation unit in the IPA Compile step, the compiler generates information for the IPA Link step. This option also affects the regular object module if you request one by specifying the IPA(OBJECT) option. Effect on IPA Link Step The IPA Link step merges and optimizes the application's code, and then divides it into sections for code generation. Each of these sections is a partition. If you specify the ARCH option on the IPA Link step, it uses the value of that option for all partitions. The IPA Link step Prolog and all Partition Map sections of the IPA Link step listing display that value. If you do not specify the option on the IPA Link step, the value used for a partition depends upon the value that you specified for the IPA Compile step for each compilation unit that provided code for that partition. If you specified the same value for each compilation unit, the IPA Link step uses that value. If you specified different values, the IPA Link step uses the lowest level of ARCH. The level of ARCH for a partition determines the level of TUNE for the parition. For more information on the interaction between ARCH and TUNE, see information on TUNE below. The Partition Map section of the IPA Link step listing, and the object module display the final option value for each partition. If you override this option on the IPA Link step, the Prolog section of the IPA Link step listing displays the value of the option. The Compiler Options Map section of the IPA Link step listing displays the option value that you specified for each IPA object file during the IPA Compile step. ------------------------------------------------------------------------ TUNE _____________________________________________________________ | | | ACCEPTED BY | SPECIAL IPA PROCESSING | | C | C++ | IPA LINK |___________________________| | | | | IPA COMPILE | IPA LINK | |______|_________|_______________|_____________|_____________| | YES | YES | YES | YES | YES | |______|_________|_______________|_____________|_____________| DEFAULT: TUNE(3). If the TUNE level is lower than the specifed ARCH level, the compiler forces TUNE to match the ARCH level. CATEGORY: Object Code Control >>---TUN(n)---------------------------------------------------->< The TUNE option specifies the architecture for which the executable program will be optimized. The TUNE level controls how the compiler selects and orders the available machine instructions, while staying within the restrictions of the ARCH level in effect. It does so in order to provide the highest performance possible on the given TUNE architecture from those that are allowed in the generated code. It also controls instruction scheduling (the order in which instructions are generated to perform a particular operation). Note that TUNE impacts performance only; it does not impact the model on which you will be able to run your application. Select TUNE to match the architecture of the machine where your application will run most often. Use TUNE in cooperation with ARCH. For many models, the best TUNE level is not the best ARCH level. For example, the correct choices for model 9672-Rx5 (G4) are ARCH(2) and TUNE(3). For more information on the interaction betweeen TUNE and ARCH see ARCHITECTURE described above. Specify the group to which a model number belongs as a sub-parameter. If you specify a model which does not exist or is not supported, a warning message is issued stating that the suboption is invalid and that the default will be used. Current models that are supported: 0 This option generates code that is executable on all models, but it will not be able to take advantage of architectural differences on the models specified below. 1 This option generates code that is executable on all models but is optimized for the following models: 9021-520, 9021-640, 9021-660, 9021-740, 9021-820, 9021-860, and 9021-900 9021-xx1, 9021-xx2, and 9672-Rx2 (G1) 2 This option generates code that is executable on all models but that is optimized for the following and follow on models: 9672-Rx3 (G2), 9672-Rx4 (G3), and 2003 9672-Rx1, 9672-Exx, and 9672-Pxx 3 This option is the default. Produces code that is optimized for the 9672-Rx5 (G4), 9672-Rx6 (G5), and 9672-Rx7 (G6) models. Note: For the above system machine models, x indicates any value. For example, 9672-Rx4 means 9672-RA4 through to 9672-RX4, not just 9672-RX4. A comment that indicates the level of the TUNE option will be generated in your object module to aid you in diagnosing your program. You can specify this option using the #pragma option directive for C. Effect on IPA Compile Step If you specify the TUNE option for any compilation unit in the IPA Compile step, the compiler saves information for the IPA Link step. This option also affects the regular object module if you request one by specifying the IPA(OBJECT) option. Effect on IPA Link Step The IPA Link step merges and optimizes the application's code, and then divides it into sections for code generation. Each of these sections is a partition. If you specify the TUNE option for the IPA Link step, it uses the value of the option you specify. The value you specify appears in the IPA Link step Prolog listing section and all Partition Map listing sections. If you do not specify the option on the IPA Link step, the value it uses for a partition depends upon the TUNE option you specified during the IPA Compile step for any compilation unit that provided code for that partition. If you specified the same TUNE value for all compilation units, the IPA Link step uses that value. If you specified different TUNE values, the IPA Link step uses the highest value of TUNE. If the resulting level of TUNE is lower than the level of ARCH, TUNE is set to the level of ARCH. The Partition Map section of the IPA Link step listing, and the object module display the final option value for each partition. If you override this option on the IPA Link step, the Prolog section of the IPA Link step listing displays the value of the option. The Compiler Options Map section of the IPA Link step listing displays the value of the TUNE option that you specified on the IPA Compile step for each object file. ======================================================================== 8. OS/390 C/C++ User's Guide (Doc No SC09-2361-03) The following enhancements made to the OS/390 V2R6.0 C/C++ compiler have been delivered through recent service PTFs. The following compiler options have been added: o COMPRESS | NOCOMPRESS o CVFT | NOCVFT o IPA(OBJONLY) In addition, the partionlist IPA Link Step Control File directive has been added. ------------------------------------------------------------------------ The following information should be added to "Chapter 6 - Compiler Options" in section "Description of Compiler Options" (topic 2.3.16): COMPRESS | NOCOMPRESS _____________________________________________________________ | | | ACCEPTED BY | SPECIAL IPA PROCESSING | | C | C++ | IPA LINK |___________________________| | | | | IPA COMPILE | IPA LINK | |______|_________|_______________|_____________|_____________| | YES | YES | YES | YES | YES | |______|_________|_______________|_____________|_____________| DEFAULT: NOCOMPRESS CATEGORY: Object Code Control >>-+-COMPRESS---+---------------------------------------------->< '-NOCOMPRESS-' Use the COMPRESS option to suppress the generation of function names in the function control block thereby reducing the size of your application's load module. Note that the function names are used by the dump service to provide you with meaningful diagnostic information when a program encounters a fatal program error. They are also used by tools such as the Debug Tool. Without these function names, the reports generated by these services and tools may not be complete. Note that if COMPRESS and TEST are in effect at the same time, the compiler issues a warning message and ignores the COMPRESS option. Effect on IPA Compile Step The IPA Compile step generates information for the IPA Link step. This option also affects the regular object module if you request one by specifying the IPA(OBJECT) option. Effect on IPA Link Step You can specify the COMPRESS option for an IPA Link step, and it will override the setting in the IPA Compile step. If you do not specify COMPRESS option in the IPA Link step, the setting in the IPA Compile step will be used. The IPA Link step merges and optimizes your application's code, and then divides it into sections for code generation. Each of these sections is a partition. The IPA Link step uses information from the IPA Compile step to determine if a subprogram can be placed in a particular partition. Only compatible subprograms are included in a given partition. Compatible subprograms have the same COMPRESS setting. The COMPRESS setting for a partition is set to the specification of the first subprogram that is placed in the partition. Subprograms that follow are placed in partitions that have the same COMPRESS setting. A NOCOMPRESS mode is placed in a NOCOMPRESS partition, and a COMPRESS is placed in a COMPRESS partition. You can override the COMPRESS setting by specifying this option on the IPA Link step. If you do so, all partitions use that value, and the Prolog section of the IPA Link step listing display the value. The Partition Map sections of the IPA Link step listing and the object module display the value of the COMPRESS option. ------------------------------------------------------------------------ The following information should be added to "Chapter 6 - Compiler Options" in section "Description of Compiler Options" (topic 2.3.16): CVFT | NOCVFT _____________________________________________________________ | | | ACCEPTED BY | SPECIAL IPA PROCESSING | | C | C++ | IPA LINK |___________________________| | | | | IPA COMPILE | IPA LINK | |______|_________|_______________|_____________|_____________| | | YES | | | | |______|_________|_______________|_____________|_____________| DEFAULT: CVFT CATEGORY: Object Code Control >>-+-CVFT---+-------------------------------------------------->< '-NOCVFT-' The NOCVFT option benefits your application's performance by shrinking the size of the writeable static area (WSA). It reduces the size of the construction virtual function tables (CVFT), which in turn reduces the load module size. The NOCVFT option relieves certain constructors from tracking which virtual function to call at different stages of the construction process. This tracking by the constructor would require that it maintain its own CVFT. Only constructors that call virtual functions within a class hierarachy that uses virtual inheritance are affected. Consider the following example: struct A { virtual int f() { return 0; } // line a }; struct B : virtual A { virtual int f() { return 1; } // line b B() { cout << f() << endl; } }; struct C : virtual B { virtual int f() { return 2; } // line c }; ... In the above example, if an instance of C is constructed, the ANSI C++ standard requires that 1 (the number one) be printed. That is, the function B::f() at line b should be called during the contruction of C. After C is constructed, a call to f() should invoke C::f() at line c. To conform to the ANSI behavior and call the right function, the OS/390 C++ compiler needs to keep extra information during object construction. This extra information can require a lot of memory if an application uses a lot of virtual inheritance. The NOCVFT option breaks the above ANSI C++ behavior. With NOCVFT, the virtual function called by your application is always the same one that would be called if the object is fully constructed. In the above example, this is C::f(), and 2 is printed during the construction of an instance of C. That is, the function at line c. The CVFT option preserves the ANSI C++ behavior. The CVFT option is shown on the listing prolog and the text deck end card. ------------------------------------------------------------------------ The following information should be added to "Chapter 6 - Compiler Options" in section "Description of Compiler Options" (topic 2.3.16.27): IPA | NOIPA The syntax has been updated to include the OBJONLY sub-option as follows: >>--+-IPA---+---+---------------------------------------------------------+-> '-NOIPA-' | .-,-------------------------------------------------. | | V | | '----(--+-NOLINK | LINK--------------------------+--)--+--' +-OBJ | NOOBJ | OBJONLY------------------+ +-ATTR | NOATT---------------------------+ +-GONUM | NOGONUM------------------------+ +-LIS | NOLIS----------------------------+ +-OPT | NOPT-----------------------------+ +-XR | NOXR------------------------------+ +-LEVEL--+-(0)-+-------------------------+ | '-(1)-' | +-CONTROL | NOCONTROL--+---------------+-+ | '-(--fileid--)--' | +-DUP | NODUP----------------------------+ +-MAP | NOMAP----------------------------+ +-NCAL | NONCAL--------------------------+ '-UPCASE | NOUPCASE----------------------' The description of this sub-option (and its related ones) is as follows: OBJECT | NOOBJECT | OBJONLY Controls the content of the object file. o OBJECT The options IPA(NOLINK,OBJECT) result in an IPA Compile step. The compiler performs IPA compile-time optimizations and generates IPA object information for the resulting program information. In addition, the compiler generates non-IPA object code and data that is based on the original program information. The object file may be used by an IPA Link step, a prelink/link, or a bind. o NOOBJECT The options IPA(NOLINK,NOOBJECT) result in an IPA Compile step. The compiler performs IPA compile-time optimizations and generates IPA object information for the resulting program information. No non-IPA object code or data is generated. The object file may be used by an IPA Link step only. o OBJONLY The IPA(OBJONLY) compilation is an intermediate level of optimization. This results in a modified regular compile, not an IPA Compile step. Unlike the IPA Compile step, no IPA information is written to the object file. During compilation, this step performs the same IPA-specific compile- time optimizations as the IPA Compile step, performs the requested non-IPA optimizations, and then generates optimized object code and data. The object file may be used by an IPA Link step, a prelink/link, or a bind. If it is used as input to an IPA Link step, no IPA link-time optimizations can be performed for this compilation unit because no IPA information is available. For all options in this mode, the Effect on IPA Compile Step and Effect on IPA Link Step considerations do not apply. The default is IPA(OBJECT). The abbreviations are IPA(OBJ|NOOBJ|OBJO). ------------------------------------------------------------------------ The following directive information should be added to "Chapter 11 - Using the IPA Link Step Control File" under section "The IPA Link Step Control File" (topic: 3.3.3.5) partitionlist=partition_number(,partition_number) Used to reduce the size of an IPA Link listing. If the IPA Link control file contains this directive and the LIST option is active, only a pseudo-assembly listing is generated in these partitions. In the above, partition_number is a decimal number representing an unsigned int. ------------------------------------------------------------------------ APAR PQ55784: TRAP(ON) Requirement The OS/390 Language Environment run-time option TRAP(ON) should be set when using OS/390 C/C++. Refer to the OS/390 Language Environment for OS/390 & VM Programming Reference for details on the OS/390 Language Environment run-time options.