OPTIONS option and attribute

Edit online

You can specify the OPTIONS option on PACKAGE, PROCEDURE, ENTRY, and BEGIN statements. You can specify the OPTIONS attribute on ENTRY declarations. OPTIONS specifies processing characteristics that apply to the block and the invocation of a procedure.

BEGIN statement

ENTRY declaration

ENTRY statement

PACKAGE statement

PROCEDURE statement

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

AMODE31 or AMODE64

In a PROCEDURE statement, AMODE31 is valid only if the compiler option LP(32) is in effect, and AMODE64 is valid only if the compiler option LP(64) is in effect.

In an ENTRY declaration, AMODE31 or AMODE64 specifies the addressing mode (the "amode") of the routine.

Specifying AMODE31 or AMODE64 requires the FETCHABLE, NODESCRIPTOR, and LINKAGE options to be specified.

If an ENTRY or PROCEDURE with OPTIONS(AMODE31) or OPTIONS(AMODE64) has a BYVALUE parameter, then the type of that parameter must be one of the types POINTER, HANDLE, ORDINAL, or REAL FIXED BIN.

If an ENTRY or PROCEDURE with OPTIONS(AMODE31) or OPTIONS(AMODE64) has the RETURNS(BYVALUE ... ) attribute, then the RETURNS attribute must specify either an ORDINAL type or an unscaled REAL FIXED BIN of 4 bytes or less.

An entry constant with OPTIONS(AMODE31) or OPTIONS(AMODE64) must specify a (possibly empty) parenthesized list of no more than 64 parameters. If it has no arguments, it should be declared as ENTRY().

An entry constant with OPTIONS(AMODE31) or OPTIONS(AMODE64) cannot be assigned either implicitly or explicitly to another ENTRY.

An argument passed to an ENTRY with OPTIONS(AMODE31) must not be a structure expression or an array expression.

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.

A PROCEDURE or ENTRY statement that specifies OPTIONS(ASSEMBLER) will have LINKAGE(SYSTEM) unless a different linkage is explicitly specified.

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 is invalid with AREA, PICTURE, WIDEPIC, VARYING, and VARYINGZ.

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:

All character string assignments are considered to be mixed character assignments.

STRINGSIZE condition causes the MPSTR built-in function to be used. STRINGSIZE must be enabled for character assignment that can cause truncation and intelligent DBCS truncation is required. See the following example:

  Name: procedure options(chargraphic);
        dcl A char(5);
        dcl B char(8);

 /* the following statement...                            */

        (stringsize): A=B;

 /*...is logically transformed into...                     */

        A=mpstr(B,'vs',length(A));

The CHARGRAPHIC and NOCHARGRAPHIC options can also be specified outside of the OPTIONS option, but this usage is deprecated and does not conform to any language standard.

When NOCHARG is in effect, no semantic changes occur.

CMPAT

The CMPAT option specifies the CMPAT compiler option setting with which the routine is compiled.

In a PROCEDURE statement, the CMPAT value in the OPTIONS attribute must match that in the compiler CMPAT option.

In an ENTRY declaration, the CMPAT option is ignored unless AMODE31 is also specified. If CMPAT and AMODE31 are both specified, then the CMPAT value must match the CMPAT compiler option setting with which the routine is compiled.

COBOL

This option has the same effects as NODESCRIPTOR, but additionally OPTIONS(COBOL) has the following effects:

Implies LINKAGE(SYSTEM) unless a different linkage is specified on the entry declaration or procedure statement.
Permits the use of the NOMAP, NOMAPIN, and NOMAPOUT options.
Implies, if specified on a procedure statement, that upon exit from that procedure, the PLIRETV() value will be used as the return value for the procedure.

COBOL and MAIN must not be specified together.

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 an entry declaration in which any of the parameters or elements uses the asterisk ( * ) to indicate the extents, length, or size, or any parameter is NONCONNECTED.

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

DLLEXTERNAL or DLLINTERNAL

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

The DLLEXTERNAL and DLLINTERNAL attributes are valid only on EXTERNAL procedures or ENTRYs. The DLLINTERNAL attribute conflicts with the FETCHABLE attribute.

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.

FORTRAN and MAIN must not be specified together.

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 those in the following list:

Procedures and begin-blocks in packages in which condition enablement varies
Procedures and begin-blocks containing ON or REVERT statements
Procedures and begin-blocks containing data-directed input/output statements
Procedures and begin-blocks containing assignments or comparisons of ENTRY, FORMAT, or LABEL constants

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. The option can 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 that 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.

COBOL is not valid when MAIN is specified.

NOEXECOPS

The NOEXECOPS option is valid only with the MAIN option. It specifies that the runtime 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 COBOL and PL/I.

Each option argument-list can specify the parameters to which the option applies. Parameters can 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 can 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.

NORETURN

This attribute indicates that if the routine on which this attribute is specified has been called, then the routine will not return and the code after that call will not be executed (This would be true, for example, if a routine ends with a STOP or SIGNAL ERROR statement).

Specifying NORETURN helps the compiler to generate optimized code and to work more accurately to detect dead code and code that could be missing a RETURN statement.

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.

The ORDER and REORDER options can also be specified outside of the OPTIONS option, but this usage is deprecated and does not conform to any language standard.

For more information about 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.

The REDUCIBLE and IRREDUCIBLE options can also be specified outside of the OPTIONS option, but this usage is deprecated and does not conform to any language standard.

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 might require use of the NOWRITABLE compiler option).

RENT

This option indicates the ENTRY to be fetched contains code compiled with the RENT compiler option.

The RENT attribute is ignored unless FETCHABLE is also specified.

RETCODE

This option specifies that if the ENTRY point also has the ASM or COBOL option, 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)

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

An instance handle
A previous handle
A pointer to the command line
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.