Defining runtime options for Language Environment

Language Environment® provides runtime options to control your program's processing. Under CICS®, exactly which options apply to the execution of a particular program depends not only on the program, but also on how it is run. Java™ programs and programs initiated from the Web or through CICS IIOP services use the Language Environment preinitialization module, CEEPIPI. This has its own version of the CEEDOPT CSECT and such programs get their runtime options from this CSECT. For normal CICS tasks, such as those started from a terminal, use any of the methods listed below to set the Language Environment runtime options. The methods are shown in the order in which they are processed. Each setting could be overridden by a following one. This is, in effect, a reverse order of precedence.

  1. In the CEEDOPT CSECT, where the installation default options for CICS are located. This CSECT is generated from the CEECOPT sample and is incorporated into the CEECCICS load module.
  2. In the CEEROPT CSECT, where the region-wide default options are located. This CSECT is link-edited into a load module of the same name and placed in a data set in the DFHRPL library concatenation for the CICS job.
  3. Start of changeThe user replacable program DFHAPXPO ( applies to XPLINK programs only).End of change
  4. In the CEEUOPT CSECT, where user-supplied application program-level runtime options are located. This CSECT is linked with the application program itself.
  5. In the application source code using the programming language options statements, as follows:
    Note:
    There is no source code mechanism that allows the setting of runtime options within COBOL programs or within C++ programs.
  6. In the Language Environment options specified in a debugging profile. For more information, see Debugging profiles.

In most installations, the first method in the list above is not available to application programmers, and the second is often not available. However, application programmer can use the last two methods. They are in effect equivalent (some of the newer compilers make them equivalent by generating a CEEUOPT CSECT when PLIXOPT is declared). Choose either methods 3 or method 4; do not attempt to use both methods. For details of generating a CEEUOPT CSECT to link with your application, see z/OS Language Environment Customization.

Notes:
  1. Both CEEDOPT and CEEROPT are able to set any option so that it cannot be overridden by a later specification.
  2. Under CICS many of the Language Environment option settings are ignored. These are all the Fortran-only options plus the following:
    ABPERC AIXBLD CBLOPTS CBLQDA
    DEBUG EXECOPS INTERRUPT LIBRARY
    MSGFILE NONIPTSTACK PLITASKCOUNT POSIX
    RTEREUS RTLS SIMVRD THREADHEAP
    VERSION
  3. Start of changeCICS provides an environment variable called CICSVAR to allow the CONCURRENCY and API program attributes to be closely associated with the application program itself by using the ENVAR runtime option. Whilst it may be used in a CEEDOPT CSECT to set an installation default, it is most useful to be set in a CEEUOPT CSECT linkedited with an individual program, or set via a #pragma statement in the source of a C or C++ program, or set via a PLIXOPT statement in a PL/I program.

    For example, when a program has been coded to threadsafe standards it can be defined as such without having to change an PROGRAM resource definition, or adhere to an installation defined naming standard to allow a program autoinstall exit to install it with the correct attributes. CICSVAR can be used for Language Environment conforming assembler, for PLI, for COBOL and for C and C++ programs (both those compiled with the XPLINK option, and those compiled without it) that have been compiled using a Language Environment conforming compiler. CICSVAR cannot be used for assembler programs that are not Language Environment conforming or for java programs.

    Use of CICSVAR overrides the settings on a PROGRAM resource definition installed via standard RDO interfaces, or via program autoinstall. Prior to the program being run for the first time, an INQUIRE PROGRAM command shows the keyword settings from the program definition. Once the application has been run once, an INQUIRE PROGRAM command shows the settings with any CICSVAR overrides applied. CICSVAR can take one of three values, QUASIRENT, THREADSAFE or OPENAPI.

      CICSVAR=QUASIRENT   results in a program with attributes    
    CONCURRENCY(QUASIRENT)     APIST(CICSAPI)

      CICSVAR=THREADSAFE   results in a program with attributes  
    CONCURRENCY(THREADSAFE)  APIST(CICSAPI)

      CICSVAR=OPENAPI   results in a program with attributes
    CONCURRENCY(THREADSAFE)  APIST(OPENAPI)   

    An example of ENVAR coded in a CEEUOPT CSECT is given below:

    CEEUOPT CSECT        
    CEEUOPT AMODE ANY    
    CEEUOPT RMODE ANY    
            CEEXOPT ENVAR=('CICSVAR=THREADSAFE')   
            END

    This can be assembled and linkedited into a into a load module and then the CEEUOPT load module linkedited together with any language program supported by Language Environment as explained above.

    Alternatively for C and C++ programs, add the following statement at the start of the program source before any other C statements:

    #pragma runopts(ENVAR(CICSVAR=THREADSAFE)) 

    For PL/I programs add the following statement following the PL/I MAIN procedure statement:

    DCL PLIXOPT CHAR(25) VAR STATIC EXTERNAL  INIT('ENVAR(CICSVAR=THREADSAFE)');  
    End of change

Finally, be aware that , after all the above changes, there are two exits that are called in the following order and both of these can change some of the options as follows:

  1. By setting the CEEAUE_A_OPTION return parameter of the CEEBXITA Language Environment user exit (apart from the LIBRARY, RTLS, STACK, and VERSION options).
  2. In the storage tuning user exit, CEECSTX, the options STACK, LIBSTACK, HEAP, ANYHEAP, and BELOWHEAP can be set.

The storage tuning exit, like the CEEROPT CSECT, is region wide, but CEEBXITA is linked into every program. Language Environment calls CEEBXITA the assembler exit because, like CEECSTX, it is invoked before the environment is fully established and must therefore be coded in assembler.

Language Environment supplies a sample source version of CEEBXITA in the SCEESAMP library (it simply returns to its caller for whatever reason it is called). You can use this as it is or modify it for use as the installation default version. However, you can link-edit a specifically tailored version of CEEBXITA with any application program and this version is then used instead of the installation default version. Take great care if you choose this method since CEEBXITA is invoked for up to five different reasons during the course of program execution, and an application-specific version of CEEBXITA must be capable of handling all these invocations.

For more details on both CEEBXITA and CEECSTX see z/OS Language Environment Customization.

Runtime options in child enclaves

Under CICS the execution of a CICS LINK command creates what Language Environment calls a Child Enclave. A new environment is initialized and the child enclave gets its runtime options exactly as discussed above. These runtime options are completely independent of those that existed in the creating enclave. Frequent use of EXEC CICS LINK, and the individual setting of many runtime options could affect performance (see also the CICS system initialization parameter RUWAPOOL for CICS LINK performance considerations). A static or dynamic call does not incur these overheads. If you need to use CEEUOPT to specify options, specifying only those options that are different from the defaults will improve performance.

Something similar happens when a CICS XCTL command is executed. In this case we do not get a child enclave, but the existing enclave is terminated and then reinitialized with the runtime options determined for the new program. The same performance considerations apply.

CEEBXITA coding

If you write your own version of CEEBXITA, you must write it in assembler. You can use all CICS commands except the ones listed here, provided you specify the NOHANDLE, RESP or RESP2 option, to prevent conditions being raised during the execution of the exit. These are the commands that cannot be used within CEEBXITA, or any routines called by CEEBXITA:

Determining which options were used

If you want to know which options were in effect when your program ran, specify the option RPTOPTS(ON). When the program ends this produces a list of all the runtime options used. The list is written to the CESE TD queue. The list contains not only the actual settings of the options, but also their origin, that is, whether they are the default for the installation or the region, or whether they were set by the programmer or in one of the exits.

Note:
Do not use RPTOPTS(ON) in a production environment - there is significant overhead and it causes a large amount of data to be written to the CESE queue.

For more information about how to specify Language Environment runtime options and also for their meanings, see z/OS Language Environment Programming Reference.

[[ Contents Previous Page | Next Page Index ]]