Rational Developer for System z
Enterprise PL/I for z/OS, Version 3.8, Language Reference Manual

OPTIONS option and attribute

The OPTIONS option can be specified on PACKAGE, PROCEDURE, ENTRY, and BEGIN statements. The OPTIONS attribute can be specified on ENTRY declarations. It is used to specify processing characteristics that apply to the block and the invocation of a procedure. The options shown in the following syntax diagrams are listed alphabetically and discussed starting in ***.

Read syntax diagramSkip visual syntax diagramBEGIN statement
 
              .-------------------------.
              V   .-ORDER-------.       |
>>-OPTIONS--(---+-+-------------+-----+-+-)--------------------><
                | '-+---------+-'     |
                |   '-REORDER-'       |
                | .-NOCHARGRAPHIC---. |
                +-+-----------------+-+
                | '-+-------------+-' |
                |   '-CHARGRAPHIC-'   |
                | .-NOINLINE---.      |
                '-+------------+------'
                  '-+--------+-'
                    '-INLINE-'
 

Read syntax diagramSkip visual syntax diagramENTRY declaration
 
               .-------------------------------------.
               V                                     |
>>-OPTIONS--(----+-+-----------------------+-------+-+--)------><
                 | +-ASSEMBLER-+---------+-+       |
                 | |           '-RETCODE-' |       |
                 | +-COBOL-----------------+       |
                 | '-FORTRAN---------------'       |
                 +-FETCHABLE-----------------------+
                 | .-BYADDR------.                 |
                 +-+-------------+-----------------+
                 | '-+---------+-'                 |
                 |   '-BYVALUE-'                   |
                 +-+--------------+----------------+
                 | +-DESCRIPTOR---+                |
                 | '-NODESCRIPTOR-'                |
                 +-LINKAGE-(-linkage-)-------------+
                 | .-IRREDUCIBLE---.               |
                 +-+---------------+---------------+
                 | '-+-----------+-'               |
                 |   '-REDUCIBLE-'                 |
                 '-+-----------------------------+-'
                   +-NOMAP-+----------------+----+
                   |       '-parameter-list-'    |
                   +-NOMAPIN-+----------------+--+
                   |         '-parameter-list-'  |
                   '-NOMAPOUT-+----------------+-'
                              '-parameter-list-'
 

Read syntax diagramSkip visual syntax diagramENTRY statement
 
>>-OPTIONS--(--------------------------------------------------->
 
   .-----------------------------------------------.
   V                                               |
>----+-+-----------------------+-------+-REENTRANT-+--)--------><
     | +-ASSEMBLER-+---------+-+       |
     | |           '-RETCODE-' |       |
     | +-COBOL-----------------+       |
     | '-FORTRAN---------------'       |
     | .-BYADDR--.                     |
     +-+---------+---------------------+
     | '-BYVALUE-'                     |
     +-+--------------+----------------+
     | +-DESCRIPTOR---+                |
     | '-NODESCRIPTOR-'                |
     +-DLLINTERNAL---------------------+
     +-LINKAGE(linkage)----------------+
     +-+-----------------------------+-+
     | +-NOMAP-+----------------+----+ |
     | |       '-parameter-list-'    | |
     | +-NOMAPIN-+----------------+--+ |
     | |         '-parameter-list-'  | |
     | '-NOMAPOUT-+----------------+-' |
     |            '-parameter-list-'   |
     | .-IRREDUCIBLE---.               |
     '-+---------------+---------------'
       '-+-----------+-'
         '-REDUCIBLE-'
 

Read syntax diagramSkip visual syntax diagramPACKAGE statement
 
              .-------------------------.
              V   .-NOCHARGRAPHIC---.   |
>>-OPTIONS--(---+-+-----------------+-+-+-)--------------------><
                | '-+-------------+-' |
                |   '-CHARGRAPHIC-'   |
                | .-ORDER-------.     |
                +-+-------------+-----+
                | '-+---------+-'     |
                |   '-REORDER-'       |
                '-+-----------+-------'
                  '-REENTRANT-'
 

Read syntax diagramSkip visual syntax diagramPROCEDURE statement
 
               .--------------------------------------.
               V                                      |
>>-OPTIONS--(----+-+-----------+--------------------+-+--)-----><
                 | +-ASSEMBLER-+                    |
                 | +-COBOL-----+                    |
                 | '-FORTRAN---'                    |
                 +-+---------------------+----------+
                 | +-FETCHABLE-----------+          |
                 | '-MAIN--+-----------+-'          |
                 |         '-NOEXECOPS-'            |
                 | .-BYADDR--.                      |
                 +-+---------+----------------------+
                 | '-BYVALUE-'                      |
                 | .-NOCHARGRAPHIC-.               |
                 +-+----------------+---------------+
                 | '-CHARGRAPHIC----'               |
                 +-+--------------+-----------------+
                 | +-DESCRIPTOR---+                 |
                 | '-NODESCRIPTOR-'                 |
                 +-DLLINTERNAL----------------------+
                 +-FROMALIEN------------------------+
                 +-LINKAGE--(--linkage--)-----------+
                 +-+------------------------------+-+
                 | +-NOMAP--+----------------+----+ |
                 | |        '-parameter-list-'    | |
                 | +-NOMAPIN--+----------------+--+ |
                 | |          '-parameter-list-'  | |
                 | '-NOMAPOUT--+----------------+-' |
                 |             '-parameter-list-'   |
                 | .-NOINLINE-.                    |
                 +-+-----------+--------------------+
                 | '-INLINE----'                    |
                 | .-ORDER---.                      |
                 +-+---------+----------------------+
                 | '-REORDER-'                      |
                 | .-IRREDUCIBLE-.                  |
                 +-+-------------+------------------+
                 | '-REDUCIBLE---'                  |
                 +-REENTRANT------------------------+
                 +-RETCODE--------------------------+
                 '-WINMAIN--------------------------'
 

The options are separated by blanks or commas. They can appear in any order.

ASSEMBLER
Abbreviation: ASM

The ASSEMBLER option has the same effect as NODESCRIPTOR.

If a procedure has the ASSEMBLER option, then upon exit from that procedure, the PLIRETV() value will be used as the return value for the procedure.

For more information, refer to the Programming Guide.

BYADDR or BYVALUE
These specify how arguments and parameters are passed and received. BYADDR is the default.

BYVALUE can be specified only for scalar arguments and parameters that have known lengths and sizes.

The BYVALUE and BYADDR attributes can also be specified in the description list of an entry declaration and in the attribute list of a parameter declaration. Specifying BYVALUE or BYADDR in an entry or a parameter declaration overrides the option specified in an OPTIONS statement.

The following examples show BYVALUE and BYADDR in both entry declarations and in the OPTIONS statement. The examples assume that the compiler option DEFAULT(BYADDR) is in effect.

Example 1

  MAINPR: proc options(main);

 
    dcl D entry (fixed bin byaddr,
                 ptr,
                 char(4) byvalue)         /*  byvalue not needed      */
          options(byvalue);
    dcl E2 entry;                         /* default(byaddr) in effect */
    dcl Length fixed bin,
        P      pointer,
        Name   char(4);

 
    call D(Length, P, Name);             /* Length is passed byaddr */
                                         /* P is passed by value */
                                         /* Name is passed by value */

 
    call E2(P);                          /* P is passed by address */

 
  D: proc(I, Q, C)
     options(byvalue);
    dcl I fixed bin byaddr,
        Q ptr,
        C char(4) byvalue;

 
  E2: proc(Q);
     dcl Q ptr;

Example 2

  dcl F entry (fixed bin byaddr,        /*  byaddr not needed       */
               ptr,
               char(4) byvalue)
        options(byaddr);
  dcl E3 entry;
  dcl E4 entry (fixed bin byvalue);

 
  call F(Length, P, Name);             /* Length is passed byaddr */
                                       /* P is passed byaddr      */
                                       /* Name is passed by value */

 
  call E3(Name);                       /* Name is passed byaddr   */
  call E4(Length);                     /* Length is passed by value */

 
  F: proc(I,P,C) options(byaddr);
    dcl I fixed bin byaddr;             /*  byaddr not needed       */
    dcl P ptr byaddr;                   /*  byaddr not needed       */
    dcl C char(4) byvalue;              /*  byvalue needed          */

 
  E3: proc(L);
     dcl L char(4);

 
  E4: proc(N);
     dcl N fixed bin byvalue;
CHARGRAPHIC or NOCHARGRAPHIC
Abbreviations: CHARG, NOCHARG

The default for an external procedure is NOCHARG. Internal procedures and begin-blocks inherit their defaults from the containing procedure.

When CHARG is in effect, the following semantic changes occur:

When NOCHARG is in effect, no semantic changes occur.

COBOL
This option has the same effects as NODESCRIPTOR (see below), but additionally OPTIONS(COBOL)
DESCRIPTOR or NODESCRIPTOR
These indicate whether the procedure specified in the entry declaration or procedure statement will be passed a descriptor list when it is invoked.

If DESCRIPTOR appears, the compiler passes descriptors, if necessary.

If NODESCRIPTOR appears, the compiler does not pass descriptors.

If neither appears, DESCRIPTOR is assumed only when one of the invoked procedure's parameters is a string, array, area, structure, or union.

It is an error for NODESCRIPTOR to appear on a procedure statement or entry declaration in which any of the parameters or elements:

However, NODESCRIPTOR is allowed if the parameters with unspecified extents are NONASSIGNABLE VARYING or VARYINGZ strings.

DLLINTERNAL
This option indicates that the procedure or entry is intended to be internal to a DLL and, consequently, that its name should not be included in any definition side file generated by the compiler.

The DLLINTERNAL attribute is valid only on EXTERNAL procedures or ENTRYs.

FETCHABLE
This option indicates the procedure is dynamically fetched if necessary before invoking it.

The FETCHABLE attribute is not valid on INTERNAL procedures.

FETCHABLE procedures should not be linked into a load module that contains a MAIN procedure.

FORTRAN
This option causes no descriptors to be passed except for character variables.
FROMALIEN
This option indicates that this procedure can be called from a non-PL/I routine. FROMALIEN can be specified on any procedure; however, this would incur unnecessary overhead.
INLINE or NOINLINE
INLINE and NOINLINE are optimization options that can be specified for begin-blocks and non-nested level-one procedures in a package.

INLINE indicates that whenever the begin-block or procedure is invoked in the package that defines it, the code for the begin-block or procedure should be executed inline at the point of its invocation. Even if INLINE is specified, the compiler can choose not to inline the begin-block or procedure.

NOINLINE indicates that the begin-block or procedure is never to be executed inline.

OPTIONS(INLINE) makes it easier to write well-structured, readable code. For instance, a program could be written as a series of calls to a set of procedures, and OPTIONS(INLINE) could be used to eliminate the overhead of actually calling these procedures one by one.

If a procedure or begin-block is executed inline, the values returned by built-in functions like ONLOC return the name of the procedure into which it is inlined. Similarly, traceback information does not include the called procedure.

Some procedures and begin-blocks are never inlined. These include, but are not limited to:

If a non-nested procedure with the INLINE option is not external and not referenced, no code will be generated for it. If neither INLINE nor NOINLINE is specified for a procedure, the option is set by the DEFAULT compiler option.

For more information about using INLINE and NOINLINE, refer to the Programming Guide.

LINKAGE
This option specifies the calling convention used and may be specified on PROCEDURE statements and ENTRY declarations.
CDECL (INTEL only)
This option specifies the CDECL linkage convention used by 32-bit C compilers.
OPTLINK
This option is the default, and is the fastest linkage convention. It is not standard linkage for most compilers.
STDCALL (Windows Only)
This option specifies the STDCALL linkage which is the standard linkage convention used by all Windows APIs.
SYSTEM
This option is the calling convention which should be used for calls to the operating system. Although this option is slower than OPTLINK, it is standard for all MVS and AIX applications.

For more information about calling conventions, refer to the Programming Guide.

MAIN
This option indicates that this external procedure is the initial procedure of a PL/I program. MAIN is valid, and required, only on one external procedure per program. The operating system control program invokes it as the first step in the execution of that program.

A PL/I program that contains more than one procedure with OPTIONS(MAIN) can produce unpredictable results.

NOEXECOPS
The NOEXECOPS option is valid only with the MAIN option. It specifies that the run-time options will not be specified on the command or statement that invokes the program. Only parameters for the main procedure will be specified.
NOMAP, NOMAPIN, NOMAPOUT
These options prevent the automatic manipulation of data aggregates at the interface between either COBOL or FORTRAN and PL/I.

Each option argument-list may specify the parameters to which the option applies. Parameters may appear in any order and are separated by commas or blanks. If there is no argument-list for an option, the default list is all the parameters of the entry name.

NOMAP, NOMAPIN and NOMAPOUT may all appear in the same OPTIONS specification. This specification should not include the same parameter in more than one specified or default argument list.

These options are accepted but ignored unless the COBOL option applies.

ORDER or REORDER
ORDER and REORDER are optimization options that are specified for a procedure or begin-block.

ORDER indicates that only the most recently assigned values of variables modified in the block are available for ON-units that are entered because of computational conditions raised during statement execution and expressions in the block.

The REORDER option allows the compiler to generate optimized code to produce the result specified by the source program when error-free execution takes place.

For more information on using the ORDER and REORDER options, refer to the Programming Guide.

If neither option is specified for the external procedure, the default is set by the DEFAULT compiler option. Internal blocks inherit ORDER or REORDER from the containing block.

REDUCIBLE or IRREDUCIBLE
Abbreviations: RED, IRRED

REDUCIBLE indicates that a procedure or entry need not be invoked multiple times if the argument(s) stays unchanged, and that the invocation of the procedure has no side effects.

For example, a user-written function that computes a result based on unchanging data should be declared REDUCIBLE. A function that computes a result based on changing data, such as a random number or time of day, should be declared IRREDUCIBLE.

REENTRANT
This option is ignored. On the Intel and AIX platforms, all PL/I programs are reentrant. On the z/OS platform, all programs compiled with the RENT compiler option are reentrant, and other programs are reentrant if they do not alter any static variables (which may require use of the NOWRITABLE compiler option).
RETCODE
This option specifies that if the ENTRY point also has the ASM or COBOL option, then the ENTRY will return a value that will be saved, after the ENTRY is invoked, as the PL/I return code. Essentially, after such an ENTRY is invoked, its return value will be passed to the PLIRETC subroutine.
WINMAIN (Windows only)
pp599win

This option automatically implies LINKAGE(STDCALL) and EXT('WinMain'). The associated routine should contain four parameters:

  1. An instance handle
  2. A previous handle
  3. A pointer to the command line
  4. An integer to be passed to ShowWindow.

These are the same four parameters expected by the C WinMain and the calls made from this routine are the same as those expected from a C routine.

pp599end

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)