Compiler Options

Note: When compiling from the command line, enclose any compiler option values that contain special characters (including spaces) in double quotes (" "). For example, enter:
-optexec  vtrace,plitest(b 10)

and

-optexec  plitest(b 10)

as:

-optexec  "vtrace,plitest(b 10)"

and

-optexec  "plitest(b 10)"

Compiler option values can always be enclosed in double quotes even if containing no special characters. However, do not use single quotes to enclose compiler option values.

The list below describes each of the Compiler options and its default setting, when applicable.

-#
Provides information on how the Compiler and linker would be invoked without actually invoking them. This option also shows which UNIX options are translated to Micro Focus options; for example, when the standard UNIX -O option is given on the driver command line, it is translated on the Compiler invocation line as -opt.
-adt
-adt [adt-filename]

Generates a file containing the data structures processed by the PL/I compiler. If adt-filename is not specified, a file with the name program-name.adt is generated. This file is consumed by the Record/Segment Layout Editor, which creates Segment Layout Files (SLF) and Record Layout Files (STR) using these PL/I structure descriptions. Data File Tools can then use these layout files to aid in processing/editing the segments or records (Data File Convert, Data File Editor, IMS Database Editor, IMS Database loader).

Use the ADT file with the Layout Editor to create SLF and STR files.

-agginit
Performs initialization of aggregates compatible with 7.x versions of Open PL/I (scalar arrays only).

Example:

dcl myarr(4) fixed bin(31) static init (1);
put skip list (myarr);

results in:
             1               1               1               1

By default, without -agginit, only the first element is initialized.

-ascii
Specifies to use the ASCII character encoding for all character data. This option is set by default.
-auto_warn_limit[19]
Sets an automatic storage warning limit for procedures and functions, and generates a compiler warning if the automatic storage usage of a procedure or function exceeds the specified limit.

Syntax:

-auto_warn_limit limit[MB|GB]

Parameters:

limit
The number of megabytes or gigabytes that represent the maximum storage space allowed before issuing a warning.
MB|GB
Megabytes and Gigabytes respectively. If omitted, MB is assumed.

Default:

Not set.

Examples:

-auto_warn_limit 500MB
-auto_warn_limit 1GB
-bid
Windows platforms only - Indicates the storage format for DFP FLOAT DECIMAL data is Binary Integer Decimal mode (BID), meaning Intel native format. Use this option if your programs come from the mainframe with *PROCESS FLOAT(DFP), and you want to use BID format.
Restriction: -bid must used with -dfp. For example:
-dfp -bid

See the -dfp option later in this topic and the Float Decimal (p) - Windows platforms topic for complete information.

-bifprec {15 | 31}
Sets the precision of a built-in function's result to 15 or 31 (default=15). This option affects following built-in functions:
  • INDEX
  • LENGTH
  • LINENO
  • MAXLENGTH
  • PAGENO
  • SEARCH
  • SEARCHR
  • SIGN
  • TALLY
  • VERIFY
  • VERIFYR
-bigendian
Specifies that all FIXED BINARY, CHARACTER VARYING, GRAPHIC VARYING and WIDECHAR VARYING items are implicitly declared with the BIGENDIAN data attribute, unless the NATIVE attribute is explicitly applied to a data item.
-bitsltr
Stores bit strings left-to-right within each byte. This is similar to Big Endian bit ordering (Intel only). The Intel default is to store bit strings right-to-left, but when the option is used, bit strings are stored left-to-right within each byte.
-c
Suppresses linking and produces a relocatable object file. This option applies to mfplx only.
-cics
Invokes the CICS preprocessor for EXEC CICS support. This allows EXEC CICS statements to be recognized and processed to generate native PL/I source code.
-coffdebug
Emits line number information for the debugger to enable breakpoints, statement tracing, and call stack information of Open PL/I source code.
Restriction:
  • Evaluation of variables is not supported.
  • -coffdebug is not supported on 64-bit Windows.
-ctf
Compile to enable use of the Consolidated Tracing Facility (CTF Trace). See CTF Trace for details.
Syntax
-ctf event-severity,type
Parameters

event-severity

  • 0 — Debug
  • 1 — Info
  • 2 — Warning
  • 3 — Error
  • 4 — Severe

type

  • 8#syspgm (system program, Micro Focus use only)
  • 16#pgm (user program)
Examples
-ctf 0,16

Generates a trace for debug level, and #pgm PL/I tracing flags in CTF Trace configuration.

-ctf 3,16

Generates a trace for error level, and #pgm PL/I tracing flags in CTF Trace configuration.

Tip: Error level trace (3) provides a minimal amount of data, which can make isolating a problem easier in that extraneous data is omitted.
-currency_symbol
Allows an alternate currency symbol for picture specification. It can take a character, decimal number, or hex constant of the form 0xDD, for example, -currency_symbol £, -currency_symbol 163, -currency_symbol 0xa3.
-deb (-debug)
Produces debugging information for CodeWatch, Micro Focus's source-level debugger. You must specify this option when using CodeWatch to debug source. When using -deb, you may specify only optimization levels 1 or 2. The default is -opt 2.
-decimal[1]
Sets the conditions under which a FIXEDOVERFLOW is raised for a FIXED DECIMAL overflow.
Syntax:
-decimal sub-option[,sub-option[...]]
Sub-options
[no]foflonasgn
Raise FIXEDOVERFLOW condition when the assignment to a FIXED DECIMAL variable causes the FIXED DECIMAL overflow.

Default: foflonasgn

[no] foflondiv
Raise FIXEDOVERFLOW condition when the result of a division operation caused the FIXED DECIMAL overflow.

Default: nofoflondiv

[no] foflonmult
Raise the FIXEDOVERFLOW condition when the result of a multiplication operation causes FIXED DECIMAL overflow.

Default: nofoflonmult

[no]forceodd
Use the extra-high order nibble allocated to a FIXED DECIMAL variable with an even precision (this is compatible with mainframe PL/I behavior).
Note: noforceodd maintains compatibility with versions of PL/I earlier than 8.0.

Default: forceodd

[no]validate
Validate the contents of FIXED DECIMAL variables and trigger an ERROR condition with an oncode of 8097 if invalid data is present.
Note: novalidate improves the speed of execution at expense of validation and detection.

Default: validate

[no]forcedsign

This option has no effect. The implicit behavior of Open PL/I is to assign the value 0xC to the sign nibble of the result when a FIXED DECIMAL arithmetic result with the value zero is generated.

Default: noforcedsign

-default_binary
Causes the BINARY attribute to be assumed if the FIXED attribute is specified without BINARY or DECIMAL.
-default_decimal 
Causes the DECIMAL attribute to be assumed if the FIXED attribute is specified without BINARY or DECIMAL. This option is the Compiler default.
-defext
Causes external variables to be defined in the data section. You must use this option for programs using external files.

The -defext option causes the initialized values of STATIC EXTERNAL variables and external file constants to be defined. Each STATIC EXTERNAL variable that has an INITIAL value must be declared in one and only one module that has been compiled with -defext. Failure to do so causes the INITIAL value to have no effect. The default is -nodefext.

Also, each file constant must be declared in one and only one module that has been compiled with -defext. When -defext is used, file attributes specified in the file declaration merges with attributes specified when the file opens. This is critical when doing VSAM/INDEXED I/O.

-dli
Invokes the DL/I preprocessor for EXEC DLI support. This allows EXEC DLI statements to be recognized and processed to generate native PL/I source code. This option is processed and supported by the EXEC preprocessor (EXEC PP).
-dfp
Windows platforms only - Use Decimal Float Point (DFP) mode for FLOAT DECIMAL data with the Densely Packed Decimal (DPD) storage format, which is mainframe compatible.

See the -bid option earlier in this topic and the Float Decimal (p) - Windows platforms topic for complete information.

-dll
Generates an object that can be used as a fetchable procedure. Use -dll to build shared fetchable procedure objects based on your operating system.
-dummy aligned | unaligned
When passing arguments, the option -dummy aligned causes a dummy argument to be created if the aligned and unaligned attributes differ between the argument and parameter descriptor. This is the default. When –dummy unaligned is used, the aligned and unaligned attributes are ignored.
-E
Causes any specified preprocessors to be run on the source file, and saves their output, but stops without running the Compiler.
-ebcdic
Specifies to use EBCDIC character encoding for all character data.
Note: The WIDECHAR and GRAPHIC data types are not supported with the -ebcdic compiler option.
-err_on_stdout
Displays or prints compiler error messages to STDOUT instead of STDERR.
-exp
Produces an expanded listing of the generated code in the form of assembly language statements in the listing file.
-f
Synonymous with -flag.
-fb7asfb15
Treats Fixed Binary (7) as Fixed Binary (15). Use for backward compatibility with previous versions of Open PL/I.
-fbmaxp n
Specifies the maximum Fixed Binary precision. The values can be:
31
Sets the maximum signed Fixed Binary intermediate result precision to 31. For unsigned fixed binary operands, the maximum intermediate precision is 32.
63
Sets the maximum signed Fixed Binary intermediate result precision to 63. This is the Open PL/I default.
Note: For –fbmaxp 63, arithmetic operations with fixed binary operands (p <= 31) will result in a maximum intermediate precision of p=31. For operands (32 >= p <= 63), the result precision will be promoted according to result precision rules with maximum fixed binary precision p=63. For unsigned fixed binary operands, the maximum intermediate precision is (p+1).

You can also use -fixed_bin_max_p as a synonym to -fbmaxp.

-fdasfb
UNIX platforms only - Causes Float Decimal data to be internally coded as Float Binary. This option produces much faster code but loses precision in the least significant digits of arithmetic results. -fdasfb is the default. See also the -nofdasfb option later in this topic, and the Float Decimal (p) - UNIX platforms topic for complete information.
-fdcheck (deprecated)[1]
Attention: This option is deprecated as of Enterprise Developer version 8.0 Patch Update 1. Use the -decimal option instead.
Checks for a possible loss of digits when assigning or converting a Fixed Decimal (p,q) to Fixed Decimal (p1,q1) where (p,q) and (p1,q1) differ.
Note: Any of the options -cics, -sql, -dli, -mvs, and/or -ims imply -fdcheck. This can be overridden when used in combination with -nofdcheck.
-fdmaxp n,[m]
Specifies the maximum FIXED DECIMAL precision n. Recommended values are:
15
The z/OS default.
18
Open PL/I default for Enterprise Developer release 2.1 and earlier.
31
Open PL/I default for Enterprise Developer release 2.2 and later.
Fixed decimal precision 31 is the maximum allowed.
15,15
Corresponds to 15.
15,31
Arithmetic operations with fixed decimal operands with precision <= 15 produce a result with a maximum precision of 15. Arithmetic operations with fixed decimal operands with precision >15 and precision <= 31 produce a result with a maximum precision of 31.
31,31
Corresponds to 31.

You can also use -fixed_dec_max_p as a synonym to -fdmaxp.

-fixed_bin_max_p
The same as -fbmaxp.
-fixed_dec_max_p
The same as -fdmaxp.
-flag, -f
Specifies the minimum diagnostic level of messages. Diagnostics below this level are suppressed. Synonymous with -f.
-flag minimum diagnostic level
The minimum diagnostic level can be:
I
Emits diagnostic messages beginning at the Informational level (Lists all messages).
W
Emits diagnostic messages beginning at the Warning level. This is the default.
E
Emits diagnostic messages beginning at the Error level.
S
Emits diagnostic messages beginning at the Severe level.
-fmaxp
Causes floating-point precision to be used for the trigonometric built-ins and for the following arithmetic built-ins: EXP, LOG, LOG10, LOG2, SQRT. -fmaxp is the default. Use -nofmaxp for the standard PL/I conversion rules for the trigonometric and the named arithmetic built-ins.
-fpcobol
Tells the Compiler to generate code compatible with COBOL handling of floating-point parameters.
-full_list
Tells the macro preprocessor to omit %NOLIST directives normally placed before code included by the %INCLUDE statement, thereby allowing the included code to be visible in the compilation listing.
-graphic
Enables support for the GRAPHIC data type.
Note: EBCDIC data and constants in conjunction with -graphic is not supported .
-help
Prints out a list of available compiler options to the console or STDOUT output, and to EXIT.
-highbif
This option allows changing the value returned by the HIGH() built-in function. For example, -highbif 127 (the default value is 255; the value 127 may be used for compatibility with earlier versions of Open PL/I).
-incl
Invokes the Include preprocessor which will process selected or default include statements and produce a deck that may then be treated as a single source file by another preprocessor or the Open PL/I Compiler.
-initcall
Causes the program being compiled to fetch and execute a call to the named routine before executing any procedural code. At run time, the routine specified is called before any procedural code is executed.
Syntax
-initcall routine
Parameter
routine The name of a routine to be fetched and executed before executing procedural code
Example

The following command line shows how -initcall is used within an mfplx command:

mfplx -deb -defext -initcall DEBINIT foo.pli 
In this example, code is compiled such that the DEBINIT routine executes before the foo.pli program. The DEBINIT routine checks for memory corruptions as shown in the following code:
Note: (str) contains the name of the program being compiled, which in this case is foo.pli
:
DEBINIT: proc(str);

  dcl str char(*);

  /* Variables for PLICTF */  
  dcl  EVENT_ERROR     fixed bin(31) static init(1000);
  dcl  LEVEL_DEBUG               fixed bin(31) static init(0);
  dcl  LEVEL_INFO                fixed bin(31) static init(1);
  dcl  LEVEL_WARNING             fixed bin(31) static init(2);
  dcl  LEVEL_ERROR               fixed bin(31) static init(3);
  dcl  TRACE_FLAGS_ALL           fixed bin(31) static init(-1);
  dcl  error_msg                 char(300) varying;
  
  /* Variables for Memory Validation */
  DCL _MFP_MEMVALID    entry(fixed bin(31) value, *) 
         returns(fixed bin(31)) options(nodescriptor);
      
  dcl  01 mem_validate_param,       
          05  cblte_mv_version   fixed bin(31) init(0), 
          05  cblte_mv_flags     fixed bin(31) init(0), 
          05  cblte_mv_type      fixed bin(31) init(0), 
          05  cblte_mv_size      fixed bin(31) init(0), 
          05  cblte_mv_address   poinTer init(NULL);                                                                                                                                              
  dcl  ret           fixed bin(31);

  
  on error
     begin;
       on error system;
       error_msg = "DEBINIT Error: " || trim(str) || ' :' ||  oncode();
       call PLICTF(EVENT_ERROR, LEVEL_ERROR, TRACE_FLAGS_ALL, error_msg, length(error_msg));     
       /* Continue processing   */
       /* don't want to take down user code because of bad initcall code! */       
       goto end_debcall;  
     end;

      ret = _MFP_MEMVALID(3, mem_validate_param);
      if (ret = 1000) then
        do;
          error_msg = "Memory Corruption detected: " || trim(str) || ' :' ||  hex(cblte_mv_address);        
          call PLICTF(EVENT_ERROR, LEVEL_ERROR, TRACE_FLAGS_ALL, error_msg, length(error_msg));               
        end;
  
  end_debcall:
  
end;
-initcheck
Enables diagnostic warnings for possibly uninitialized automatic variables at first use within the given procedure. Default is -noinitcheck.
Note: Any of the options -cics, -sql, -dli, -mvs, and/or -ims imply -initcheck. This can be overridden when used in combination with -noinitcheck.
-ipath dirlist
Directs the Compiler to search specified directories for files to be included in the source program text by use of the %INCLUDE statement. dirlist is an ordered list of directories of the form
dirname[:dirname] ...

The -ipath option instructs the Compiler to use these directories in the specified order in its search for files to satisfy %INCLUDE statements (except in cases where an absolute directory path is specified in the %INCLUDE statement).

For example, suppose the source program contains:

%INCLUDE partlist;

and the Compiler invocation command is:

mfplx source_file -ipath .:/u/libr1:/u/libr2

In this case, the Compiler will first search for "PARTLIST" in the current working directory, then /u/ libr1, and finally /u/ libr2. If that fails, it will search for "partlist" (lowercase) in the same directories.

In a Windows environment, the equivalent Compiler invocation is:

mfplx source_file -ipath .;drive:\libr1;drive:\libr2
-ipubr
Causes bits for unsigned integers created using INT or POSINT and bit strings returned with UNSPEC to be inversed.
-isuffix string
Causes string to be appended to the filename specified in %INCLUDE statements, except those in which the quoted filename form of the %INCLUDE statement is used. º
-l [ file]
Produces a Compiler listing where file is the name of the file to which the listing is output. If you do not supply a filename, you must place this option after the source filename on the command line; otherwise, an error message appears. The default name of the file containing the listing is xxx.list, where xxx is the source filename (excluding the pathname) up to, but not including, the last "." (if any) in the name. For example, if the source filename is prog.pl1, the default listing is prog.list (prog.lst for Windows systems). A Compiler listing is produced by default whenever -exp, -map, or -xref is specified.
-laxbased
Disables storage checking of BASED variables. This is Open PL/I default. See also –nolaxbased.
-laxcomment
Disables diagnosis of comments containing a semicolon. This is Open PL/I default. See also –nolaxcomment.
-laxdefined
Disables type and storage checking of DEFINED variables. This is Open PL/I default. See also –nolaxdefined.
-laxif

The compiler allows IF, WHILE, UNTIL, and WHEN clauses that are not of type BIT(1). In this case the expression is converted to type BIT according to conversion rules. It also causes the compiler to allow assignments of the form A=B=C, which is the equivalent of A=(B=C). See also –nolaxif.

-laxinit
Disables dependency ordering of automatic initializers in block prologue. The declaration order is used.
-laxtype
Provides backwards compatibility to declarations that are not compatible with mainframe syntax.
-longint
Changes the default precision of Fixed Binary variables from (15) to (31).
-lowercase
Converts all uppercase names of internal and external variables and constants to lowercase.
Note: This option is deprecated and will be removed in a future release.
-macro
Invokes the Open PL/I Macro Preprocessor, mfpp. The default preprocessor output file name is xxx.pp, where xxx is the name of the source file. If the -pp option is not specified, the xxx.pp file is deleted after the compilation phase is completed. The -macro option applies to mfplx only.
-map
Produces a storage allocation map at the end of the listing file.
-map
Does one of the following:
  • When used without a colon or any arguments, -map produces a storage allocation map at the end of the listing file.
  • When used with a colon and an argument, for example -map:filename (where filename is the filename of a linker map file), this option passes to ldpli and to generate a linker map for the specified filename.

-map and -map:filename can be used together.

-margini s
Specifies a character to place in the column immediately preceding the left margin, and also in the column immediately after the right margin, of the listings produced by the -insource and -source options. c is a character that delimits the left and right margins in the source listing.
-margins l,r
Sets the margins within which characters of the source file are interpreted as source code and outside which all characters are ignored by the Compiler. l is the column number of the leftmost character, and r is the column number of the rightmost character to be interpreted as source code. Note that if tabs are used, each tab is counted as a single character. The -margins option can be overridden by a *PROCESS statement in the source.
Note: There must be no spaces around the comma separating the left and right margin.
-maxmsg
Specifies the maximum number of diagnostics of a specified severity or higher which will be produced during compilation.
-maxmsg Level,n

where Level is one of I, W, E, S as follows:

I
Counts all compiler messages starting at I-level (Informational) against the maximum.
W
Counts all compiler messages starting at W-level (Warning) against the maximum.
E
Counts all compiler messages starting at E-level (Error) against the maximum.
S
Counts only S-level (Severe) against the maximum.
n

The maximum number.

The default is -maxmsg W,1000.

Compilation terminates if the number of messages exceeds the maximum number allowed. If messages are below the specified severity, they are not counted in the number. The value of n can range from 0 to 32767. If you specify 0, the compilation terminates when the first error of the specified severity is encountered.

An unrecoverable A-level (Abort) error message always results in termination.

-multiclose
Allows multiple closure of groups by automatically inserting a END statements. This produces a W-level diagnostic.
-names
Adds extralingual characters to identifiers via the compiler options, similar in nature to %PROCESS NAMES().

Example:

-names 'string1' [ 'string2' ]
string1
Extralingual characters to add to identifier.
string2

Corresponding upper case characters. Optional.

The default is:

-names '$@#' '$@#'

For additional characters you must specify the default $@# or subset if desired, plus the additional lingual characters.

-names '$@#Ј'

For convenience, hex constants of the form 0xDD..DD are accepted in place of the strings above.

-names 0x402324a3
-nest
Causes the nesting of DO ... END, PROC ... END, and so on to be shown in the listing file. See the -l option for more information about the listing file.
-nocicsdebug
Allows use of CodeWatch to debug the original source file, rather than the intermediate file generated by the CICS preprocessor. Also, causes Compiler diagnostics to use line numbers referencing the original source file. This is the default. The -nocicsdebug command applies to mfplx and kixplt only.
-nodebuginfo
Tells the Compiler to not break the line for %FILE and %LINE information.
-nodefext

The -nodefext option prevents definition of initialized values of STATIC EXTERNAL variables and external file constants (default). See the -defext compiler option for more information.

Also, each file constant must be declared in one and only one module that has been compiled with -defext. When -defext is used, file attributes specified in the file declaration will be merged with attributes specified when the file is opened. This is critical when doing VSAM/INDEXED I/O.

-nofdasfb
UNIX platforms only - Causes Float Decimal data to be internally coded as Binary Coded Decimal. The default setting is -fdasfb. See also the -fdasfb option earlier in this topic, and the Float Decimal (p) - UNIX platforms topic for complete information.
-nofmaxp
Causes standard PL/I conversion rules to be used to determine the precision of trigonometric and certain arithmetic built-ins. The default is -fmaxp.
-nogotocheck
Disables runtime validity checking when attempting a goto on a subscripted label.
-noincludes
Tells the Compiler and/or macro preprocessor not to include the contents of %INCLUDE files in the compiled source.
-noinitcheck

Disables diagnostic warnings for possibly uninitialized automatic variables. Default is -noinitcheck.

-nolaxbased
For BASED variables declared using the form BASED (ADDR(x), enables storage checking with the base reference “x”. –laxbased is the Open PL/I default.
Note: Any of the options -cics, -sql, -dli, -mvs, and/or –ims imply –nolaxbased. This can be overridden when used in combination with –laxbased.

Example:

DCL X FIXED BIN (15); DECLARE Y FIXED BIN (31) BASED (ADDR(X));

will result in an appropriate diagnostic.

-nolaxcomment
Diagnoses comments containing a semicolon.
-nolaxdefined
For DEFINED variables, enables both type and storage checking on DEFINED variable and the base variable. –laxdefined is the Open PL/I default.
Note: Any of the options -cics, -sql, -dli, -mvs, and/or –ims imply –nolaxdefined. This can be overridden when used in combination with –laxdefined.

Example:

DCL S1 CHAR(10); DECLARE S2 CHAR(20) DEFINED (S1);

will result in an appropriate diagnostic.

-nolaxdcl
Tells the Compiler to not allow compiler declarations for undeclared variables.
-nolaxif
The compiler diagnoses IF, WHILE, UNTIL, and WHEN clauses that are not of type BIT(1). It also causes the compiler to flag assignments of the form A=B=C, which is the equivalent of A=(B=C). See also -laxif.

The following compiler options imply -nolaxif:

  • -cics
  • -sql
  • -dli
  • -mvs
  • -ims

To override this for the above-referenced compiler options, set them in combination with -laxif.

-nolaxinit
Enables dependency ordering of automatic initializers in block prologue. This is the Open PL/I default.
- nolaxtype
Do not allow laxed TYPE/LIKE usage.
-nomacro
Suppresses the invocation of the Open PL/I Macro Preprocessor. The default is -nomacro.
-noobj
Compiles for syntax and semantic checking only. Does not produce an object file.
-noopt
Compiles without optimization. This is the default.
-nomulticlose
Does not allow multiple closure of groups. Default setting. This produces an E-level diagnostic.
Note: Use the -multiclose compiler option to revert to the behavior of previous product versions, which produced a W-level diagnostic.
-norange
This option is deprecated and will be removed in a future release. See the -prefix option.
-not_symbol
Lets you specify an alternate NOT symbol. It can take a character, decimal number, or hex constant of the form 0xDD. See also %PROCESS in the Language Reference Manual.
-nounixdebug
Avoids generating the additional object file data needed to report source file and line number when a fatal run-time error occurs, or for use by the ONLOC built-in function.
-nounrefexternals
Prevents external entry symbols that are not referenced in the program from being generated in the object file. This is the default.
-nowarn
Suppresses all INFORMATIONAL and WARNING level diagnostics. This is equivalent to setting the –flag option to E.
-[no]xref
Tells the compiler to not include a cross-reference table of names that are used in the program. See the -xref compiler option for more information.
-O
Invokes the optimization phase of the Compiler. This option applies to mfplx only and is equivalent to the -opt option.
-o file
Names the object file the name you specify with file. If -o is not specified, the default name of the file is xxx.o, where xxx is the source filename up to, but not including, the last "." (if any) in the name. For example, if the source filename is prog.pl1, the default object filename is prog.o (prog.obj for Windows).

If -c is specified, the -o option is passed to the compiler; if -c is not specified, -o is passed to ldpli.

-opt [level]
Specifies the level of optimization by the Open PL/I Compiler, where level stands for the level (1 – 3) of optimization. The default setting is -noopt. If level is not included, the program is optimized at level 3. If -deb is specified, -opt 2 is the maximum level allowed. Note, -opt-deb is equivalent to -opt 2 -deb.
-optcics
Allows the CICS options to be passed to the CICS ECM
-optdli
Allows the DL/I options to be passed to the DL/I (IMS) ECM
-optexec {sub-option}[,sub-option]
Lets you specify options for the EXEC preprocessor. You can use the following for the -optexec option.
NEWNAME(newname)
Specifies a name for the outermost external procedure in addition to other names that may have been specified on the PROCEDURE statement. Use this when the name on the procedure does not match the name of the executable. (newname) is the same name as the name of the executable.
trace
Causes the preprocessor to create a file source.trc where source is the name of your source file.
ctrace
Creates a trace file for submission to Customer Care if requested.
strace
Creates a log file from the internal functions called by the program.
vtrace
Creates a dynamic visual trace of the program.
-options

Adds information about translated *PROCESS directives and command-line option processing to the compiler listing (-options implies –l). See the section on *PROCESS directives for more information.

-optsql
Allows the SQL options to be passed to the SQL preprocessor.
-or_symbol
Lets you specify an alternate OR symbol. It can take a character, decimal number, or hex constant of the form 0xDD. See also %PROCESS in the Language Reference Manual.
-pass
Connects to a remote DB2 database. You can use this option with a specified username and password. The format is:
–pass myid.mypass

Where myid is the username and mypass is the password for the remote DB2 connection. mfplx first checks the -pass for a username/password and uses these values if specified. If not specified, it uses the values set for the DB2_USERNAME and DB2_PASSSWORD environment variables.

-pic
Generates position-independent code, suitable for linking into a shared library. This option is only available on Solaris, SUSE Linux and Red Hat Linux.
Use this option when compiling code for inclusion in a shared object.
-pl1g
Causes Open PL/I to retain the behavior of releases prior to Open PL/I 5.0 for certain operations that have been changed in such a way as to become incompatible with that former behavior. For example, TIME() returns a value including three fractional digits (thousandths), but -pl1g causes it to return only two fractional digits (hundredths).
-plitdli

Specifies IMS linkage when calling a PLITDLI entry point name rather than a user supplied PLITDLI. This option allows for DCL PLITDLI ENTRY; declared as such in the user program (without an entry descriptor list and/or return type).

-pmod
Changes the output of the MOD builtin to always return a positive result, even with a negative divisor.
-pp [file]
Specifies the file name for the output file of the Open PL/I Macro Preprocessor. An output file created with the -pp option is preserved after the compilation phase is completed. This option applies to mfplx and mfpp only.
-ppcics [file]
Specifies the file name for the output of the CICS preprocessor. An output file created with the -ppcics option is preserved after the compilation phase is completed. This option applies to mfplx only.
-ppdli[file]
Specifies the file name for the output of the DL/I preprocessor. An output file created with the -ppdli option is preserved for consumption by a downstream preprocessor or the PL/I compiler.
-pporder
Selects which preprocessors are to be invoked and in what order. This option applies to mfplx only.

Syntax:

-pporder "pp-name [ (pp-string)] [ pp-name [ (pp-string)] ] …"
Note: The surrounding quotes are required.
pp-name
The name of the preprocessor. The preprocessor names must be one of must be one of MACRO,SQLDB2, SQLOCI, SQLODBC, CICS, or DLI.
pp-string
An argument associated with each preprocessor.

For INCL, no pp-string argument is applicable (or allowed).

For MACRO, the pp-string argument, if supplied, must be one of ‘CASE(ASIS)’ or ‘CASE(UPPER)’. This argument overrides any command-line argument –case_asis of –case_upper, if given.

For SQLDB2, SQLOCI, SQLODBC, the pp-string argument, if supplied, is what would be supplied to the –optsql option. This argument overrides any command-line argument for –optsql, if given. Refer to the Micro Focus SQL documentation for more information.

For CICS, the pp-string argument, if supplied is what is would be supplied to the –optcics option. This argument overrides any command-line argument for –optcics, if given. Refer to the Micro Focus CICS documentation for more information.

For DLI, the pp-string argument, if supplied, is what is would be supplied to the –optdli option. This argument overrides any command-line argument for –optdli, if given. Refer to the Micro Focus DLI documentation for more information.

A maximum of 31 invocations are allowed.

Note: If the –pporder option is not used, then the default ordering is applied, which is: INCL, MACRO, DLI, SQL, CICS, MACRO.

Selection of the above preprocessors to invoke is dependent upon the combination of given options –incl, –macro, -dli, -sql, and –cics. Refer to the Micro Focus documentation for more information on these options.

-ppsql [file]
Specifies the file name for the output of the SQL preprocessor. An output file created with the -ppsql option is preserved after the compilation phase is completed. This option applies to mfplx only.
-prefix ["condition-prefix[,condition-prefix]…"]
This option allows you attach one or more condition prefixes to your program without the need to edit the source code. These condition prefixes are logically prefixed to the beginning of the (implicit or explicit) PACKAGE statement, which in turn has the affect of logically prefixing these to each external (level 1) procedure in the program being compiled.

The default for -prefix is:

-prefix "conversion,fixedoverflow,invalidop,zerodivide,nosize,nostringrange,nostringsize,nosubscriptrange"
Note: Default condition prefixes remain in effect even when you explicitly specify a non-default prefix. To change a default condition prefix setting, specify its opposite when available. For example, specify stringrange to override the default nostringrange.
-proginfo
Causes the compiler to insert a data structure that allows the CBL_GET_PROGRAM_INFO function to identify and report PL/I programs when walking the program stack.
-proto
Provides more extensive prototype checking on arguments vs. parameters in entry declarations (also assumed by default when using -vax).

In this example using -proto, the compiler would recognize the mismatched declaration between the included entry declaration and the actual procedure declaration, by generating the following diagnostic:

MFPLI00256W : Parameter "A" type conflicts with the parameter type and/or attributes declared in the EXTERNAL ENTRY declaration for the same PROCEDURE

Example:

myproc.dcl
------------
declare myproc external entry(
  fixed binary(31),
  fixed binary(15),
  fixed binary(15));

myproc.pli
------------
%include 'myproc.dcl';

myproc: procedure(a,b,c);
  declare a fixed binary(15);  / * mismatch  with “myproc.dcl” */
  declare b fixed binary(15);
  declare c fixed binary(15);
end;

callmypr.pli
-------------
callmypr:proc;
  %include 'myproc.dcl';

  call myproc (1,2,3);
end;
-range
This option is deprecated and will be removed in a future release. You should use -prefix stringrange,subscriptrange instead.

While accepted, -range is effectively is treated as -prefix stringrange,subscriptrange and it overrides the same condition prefixes specified in -prefix.

See the -prefix option.

-rc n,0
Specifies the maximum error code level n which will result in a zero return code from mfplx. The default is –rc 4,0. The allowed values are:
  • -rc 0,0
  • -rc 4,0
  • -rc 8,0
The compiler error code levels and mfplx return codes are shown in the table below:
Compilation Error Code Level Return Code Description
0 0 No diagnostic messages or I-level ( Informational) only.
4 0 W-level (Warning) diagnostic messages (object code generated)
8 1 E-level (Error) diagnostic messages (object code generated but execution behavior is not defined – the source code is in error and should be corrected)
12 1 S-level (Severe) ) diagnostic messages (object code not generated)
16 1 Compiler Abort
The values in the table relate to the default –rc 4,0 setting.
The command-line driver mfplx returns 0 upon success and 1 upon failure. If a link is invoked after successful compilation, the mfplx return code is 0 if successful and 1 if failure.
-report [file]
Specifies the file name for the output of the Open PL/I Source Checker. If this option is not used, the output of the checker will be directed to the standard error file. This option applies to mfplx only.
-roundtozero[9]
Changes rounding mode of floating point arithmetic to round towards zero.
-setnull n
Designates a null pointer value n to be returned by the NULL built-in function, where n is a decimal value. If this option is not specified, the value of the NULL built-in function is an address with all bits set to 1.
-setstack [integer]
Sets each byte of the storage to the argument's value. The argument is an integer in the range 0-255. If no argument is provided, the memory is set to 0.
-so
Generates an object that can be used as a fetchable procedure. Use -so or -dll to build shared fetchable procedure objects based on your operating system.
-shortint
Tells the Compiler to set the default FIXED BINARY precision to 15.
-sql
Invokes the SQL preprocessor for EXEC SQL support. This allows EXEC SQL statements to be recognized and processed to generate native PL/I source code. This option is processed and supported by the EXEC preprocessor (EXEC PP). You can use the following for the -sql option.
odbc
Specifies an ODBC-compliant database.
db2
Specifies an IBM, DB2, or UDB database.
oci
Specifies an oracle "Call" interface database.
-stardesc
Tells the Compiler to produce argument descriptors for calls only when array bounds or string lengths in the parameter declaration are represented by the asterisk (*) symbol. (This was compiler behavior in releases prior to release 7.0.) When this option is not used, the Compiler produces descriptors for array, structure, and string arguments.
-stat
Prints Compiler statistics to the standard output as each Compiler phase completes.
-stbout
Generates an .stb file in the same directory as the output object file.
Note: You may need to set the CODEWATCH_STBPATH and CODEWATCH_SRCPATH variables to the appropriate locations when using this option.
-strip (ldpli)
Tells ldpli to not generate debugging information.
-structure_fillers
Tells the Compiler to produce warnings for structures containing fillers.
-systemcics

Specifies that this OPTIONS(MAIN) program will execute under the control of CICS. Such a program may have 0, 1, or 2 parameters, all of which must be POINTER. Such a program, almost always, will specify -cics and may also specify one or more of –sql and –dli.

-systemims
Specifies that this OPTIONS(MAIN) program will execute under the control of IMS. Such a program may have 0 thru n parameters, all of which must be POINTER. Such a program may also specify one or more of –sql and –dli.
-systemmvs
Specifies that this OPTIONS(MAIN) program will execute under the control of MVS. Such a program may have at most one parameter which must be CHAR(n) VARYING where “n” is not *. Such a program may also specify one or more of -cics, –sql and –dli.
-unaligned
This compile-time switch has been added for use on RISC architectures. This switch causes byte instructions to be generated for all based references, which might point anywhere in memory.
-unrefexternals
Causes external entry symbols to be generated in the object file, even if they are not referenced in the program.
-v
Prints information to stdout relating to the compilation and link-step phases. This option applies to mfplx only.
-variant string
Passes the variant string string to the Open PL/I Macro Preprocessor. This option applies to mfplx only.
-vax
Makes the following adaptations for programs originally written with Digital Equipment Corporations's PL/I Compiler for the VAX platform:
  • Enables Float Binary(24) as equivalent to Float Binary(23).
  • Enables Float Binary(53) as equivalent to Float Binary(52).
  • Causes the BINARY attribute to be assumed if the FIXED attribute is specified without BINARY or DECIMAL.
-warn
Suppresses INFORMATIONAL level diagnostics. This is equivalent to setting the -flag option to W. This is the default.
-window
Sets the value for the w window argument used in various date-related built-in functions.
w
Either a positive four-digit integer such as 1976 that represents the start of a fixed window or a negative integer that specifies a “sliding” window. For example, -window -50 indicates a window that starts 50 years prior to the year when the program runs.
-xmlattr apostrophe | quote

Causes the XMLCHAR built-in function to enclose XML attributes in apostrophes (single quotes) or quotations marks (double quotes). -xmlattr apostrophe is the default.

-xmlcase upper | asis

Causes the XMLCHAR built-in function to generate tags in its XML output to be all uppercase or in the case used in the declaration. –xmlcase upper is the default.

-xref
Produces cross-reference information in the listing file and specifies the type of cross reference information produced. The cross-reference shows names used in the program with the numbers of the statements where they are either declared or referenced. Unreferenced labels are shown in the listing without cross-reference information.
-zalign
Specifies z/OS aggregate mapping and alignment rules.
  • Affects mapping of structure members. z/OS structure mapping rules use a "shift-to-align" algorithm to minimize compiler inserted pad bytes for the alignment requirement of structure members. This differs from the default Open PL/I structure mapping rules described in the Structure topic, which are compatible with other UNIX and Windows compilers for inter-language compatibility.
  • Sets the default FLOAT BINARY single precision to 21 and the default FLOAT BINARY double precision to 53 ( implies -zfloat). The Open PL/I default is 23 and 52 respectively.
  • Specifies that the default alignment attribute for the CHAR, CHAR VAR, GRAPHIC, GRAPHIC VAR, WIDECHAR, WIDECHAR VAR and PICTURE data types is unaligned (implies -zchar). The Open PL/I default is aligned.
  • Implies double-word alignment of double precision FLOAT BINARY on Intel 32-bit systems (the Open PL/I and Intel native default alignment is word on Intel 32-bit systems)
  • Implies double-word alignment of AREA on Intel 32-bit systems (the Open PL/I default alignment is word on Intel 32-bit systems)

Structure Layout Example (Open PL/I default)

The following shows structure ST with size 8 bytes; member "C" is at offset 0 (byte alignment) and member "X" is at offset 4 (word alignment), with 3 compiler-inserted pad bytes between.

       1
       2      dcl 1 ST,
       3            2  C CHAR,
       4            2  X FIXED BIN(31);
       5

NAME             CLASS      SIZE      LOCATION    ATTRIBUTES

ST               BASED      8                    LEVEL 1 STRUCTURE
C               MEMBER      1         00000000   LEVEL 2 CHAR(1)
                            3         00000001    -pad-
X               MEMBER      4         00000004   LEVEL 2 FIXED BIN(31,0)

Structure Layout Example (-zalign)

The following shows structure ST with size 5 (8 bytes are allocated in memory); member "C" is at offset 0 (byte alignment) and member "X" is at offset 1 (word alignment). In this example each member is shifted by 3 bytes (OFFSET=3 as shown below) to properly align each member on its required boundary, thus minimizing (and in this case eliminating) compiler-inserted bytes. Effectively, the "shift-to-align" algorithm propagates pad bytes that fill natural alignment gaps between members toward the beginning of the structure. Pad bytes which have been shifted outside the structure (that is, preceding the first member) are known as "hang bytes".

       1
       2      dcl 1 ST,
       3            2  C CHAR,
       4            2  X FIXED BIN(31);
       5

NAME             CLASS      SIZE      LOCATION    ATTRIBUTES

ST               BASED      5                     LEVEL 1 STRUCTURE OFFSET=3
C               MEMBER      1         00000000    LEVEL 2 CHAR(1) UNALIGNED
X               MEMBER      4         00000001    LEVEL 2 FIXED BIN(31,0)
Note:
  • The use of this option is recommended only when structure mapping is required to match z/OS structure mapping rules. An example when required might be reading files imported from the mainframe containing record structures that have z/OS compiler-inserted (and possibly removed) pad bytes for alignment purposes.
  • If -zalign is used for the compilation of one module, it is recommended that all modules in a given program be compiled as such for compatibility. Mixing --zalign with compilation units in the same program may work, but this can be problematic if the modules compiled with -zalign are not "self-contained".
  • For adjustable structures (having REFER-extents or non-constant sized members), the -zalign "shift-to-align" algorithm will cause more code to be generated to access structure members with non-constant offsets (seen in the -map listing as (-V-) under the Location Field). Depending upon structure layout, the amount of code generated can be extensive as compared against the Open PL/I default mapping rules (when not using -zalign). Compiler optimization at a minimum level of -opt 2 is recommended.
Restriction:
  • For structures with multiple REFER-extents, compiler resources may be impacted resulting in a Compiler Abort. Please contact Micro Focus Customer Care.
-zchar
Specifies that the default alignment attribute for the CHAR, CHAR VAR , GRAPHIC, GRAPHIC VAR, WIDECHAR, WIDECHAR VAR and PICTURE data types is unaligned.
Note: This affects storage requirements for CHAR VAR , GRAPHIC VAR, and WIDECHAR VAR. It also affects parameter and descriptor matching at CALL statements.

Example (Open PL/I default):

Dcl c  char;
Dcl sub entry (char unaligned);

    Call sub(c);  /* A dummy argument is created for “c” */

Dcl c  char;
Dcl sub entry (char aligned);

Call sub(c);  /* “c” is passed by reference */

Example (-zchar)

Dcl c  char;
Dcl sub entry (char unaligned);

    Call sub(c);  /* “c” is passed by reference */

Dcl c  char;
Dcl sub entry (char aligned);

Call sub(c);  /* A dummy argument is created for “c”  */
-zfloat
Specifies the Float Binary single precision default as 21; specifies the Float Binary double maximum as 53. The Open PL/I defaults are 23 and 52, respectively.
Note: Floating point precisions that are less than or equal to 21 are implemented as IEEE single precision floating point. Floating point precisions that are greater than 21 are implemented as IEEE double precision floating point.
-zp1
Causes all structures to be mapped as if the UNALIGNED attribute is specified at the level 1 structure level. The option is for compatibility with versions of DEC VAX PL/I.

Compiling with -zp1 effectively packs all structures so that any pad bytes used for data alignment are eliminated. This is useful when files originating from the mainframe have records in which the data items are packed or unaligned.

When -zp1 is set, the compiler needs to take certain precautions, especially on RISC architectures where misaligned data can cause a hardware exception.

The -zp1 compiler options affects the following:

  • All structure members are packed without any pad bytes for alignment as if the UNALIGNED attribute were specified at the level 1 structure level.
  • All based variables are treated as if unaligned.
  • All parameters are treated as if unaligned.
  • All Character Varying data items are treated as if unaligned. The Open-PL/I default alignment for CHAR VAR is HALFWORD which is the natural alignment of the leading fixed bin (15) length.

When using -zp1, to maintain consistency in passing arguments without modifying the source code, the compiler disables creating dummy arguments at call points when the argument is a structure member and the argument and parameter descriptors do not explicitly differ between the UNALIGNED and ALIGNED attributes.

Note: Using -zp1 can have an overall impact on performance. On RISC architectures such as SPARC and AIX/Power, the compiler must generate sequences of byte addressable instructions to access unaligned data items in the memory. On Intel, no changes are required for code generation, but additional clock cycles are required for the hardware to access misaligned data items.
Important: If you are using this release as an upgrade to Enterprise Developer 2.2 Update 1, after the upgrade you must rebuild any applications that are compiled using the –zp1 option.

The behavior of the –zp1 option has been reverted to that of versions of Enterprise Developer earlier than 2.2 Update 1, with an additional correction relating to Char Varying data items.

The behavior has been restored to that in Enterprise Developer versions earlier than 2.2 where, when compiling with –zp1, all parameters are treated as unaligned. (In Enterprise Developer 2.2 Update 1, the behavior when compiling with –zp1 was to not treat parameters as if unaligned).

When using the –zp1 compiler option, all Character Varying data items are now treated as if unaligned. In previous versions of Open PL/I, for Character Varying data items, the –zp1 unaligned requirement was applied only to structure members and parameters.

To illustrate the change, consider the following example:

zptest: proc options(main); 
 
   dcl 1 st1, 
     2 c char, 
     2 x(4) char(7) var init ('a', 'xx', 'yyy', 'zzzz'); 
 
   dcl y(4) char(7) var init ('a', 'xx', 'yyy', 'zzzz'); 
 
   dcl sub entry ((4) char(7) var); 
 
   call sub (x); 
 
   call sub (y); 
 
end; 
 
sub: proc (z); 
 
   dcl z(4) char(7) var; 
 
   dcl i fixed bin(31); 
 
  do i = 1 to hbound(z); 
      z(i)  = 'x'; 
  end; 
 
end; 

Where:

  • For x and z, each char (7) var item is 7 plus 2 bytes which equals 9 and then multiplied by 4 equals 36.
  • If y were aligned on half-word by default, each array element is half-word aligned and each equals 10 bytes (9 + 1 pad byte), and the total size equals 40 bytes.
  • At call sub (x), the calling argument and parameter are matched.
  • At the call sub (y), the y element size (10 bytes) is mismatched against the parameter z element size (9 bytes) due to –zp1. This is incorrect and causes unexpected program behavior.

Due to this correction of treating all Char Varying data items as if unaligned when using –zp1, the size of CHAR VARYING arrays now differs from previous versions of Open-PL/I. For example:

   dcl X(4) char(7) var; 
 
   Put skip list (size(X))  /* size is 36 bytes vs. 40 bytes in previous versions of Open-PL1 */