Compiler Options

-optexec  vtrace,plitest(b 10)

-optexec  plitest(b 10)

-optexec  "vtrace,plitest(b 10)"

-optexec  "plitest(b 10)"

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.

-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 Visual Studio 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.

-compact_msgs

Do not break the line for messages.

-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.

-db2

Invokes the DB2 preprocessor, mfdb2. The default DB2 preprocessor output file name is xxx.pp2, where xxx is the name of the source file. If the -ppdb2 option is not specified, the file xxx.pp2 is deleted after the compilation phase is completed. The -db2 option applies to mfplx only.

Warning: This option is required for the mfdb2 preprocessor, which is deprecated. Please use the EXEC preprocessor (invoked by -sql db2)

-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.

-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).

-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.

-E

Causes any specified preprocessors (-macro, -db2) 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.

-fdasfb

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.

-fdmaxp n

Specify 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.

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

-flag

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. This is the default).

W

Emits diagnostic messages beginning at the Warning level.

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.

-full_list

This option 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.

-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.

For example, suppose the source program contains:

%INCLUDE partlist;

and the Compiler invocation command is:

mfplx source_file -isuffix .INC

In this case, the Compiler searches for a file named partlist.inc.

-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.

-laxdefined

Disables type and storage checking of DEFINED variables. This is Open PL/I default. See also –nolaxdefined.

-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.

-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 add -map:filename can be used together.

-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.

-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

Causes Float Decimal data to be internally coded as Binary Coded Decimal. The default setting is -fdasfb.

-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.

-noincludes

Tells the Compiler and/or macro preprocessor not to include the contents of %INCLUDE files in the compiled source.

-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 S1 CHAR(10); DECLARE S2 CHAR(20) DEFINED (S1);

will result in an appropriate diagnostic.

-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 X FIXED BIN (15); DECLARE Y FIXED BIN (31) BASED (ADDR(X));

will result in an appropriate diagnostic.

-nolaxdcl

Tells the Compiler to not allow compiler declarations for undeclared variables.

-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.

-norange

Suppresses generation of code to check the validity of subscript references and substring bounds. This option should be used after your program has been debugged to improve execution time performance. The default is -norange.

-noopt

Compiles without optimization. This is the default.

-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.

[NO]PLITEST

Tells the EXEC preprocessor to inject an automatic call to start the GUI CodeWatch debugger.

Using the -optexec option with the PLITEST parameter also lets you debug PL/I programs that run under CICS. During execution, the program stops at the first executable statement (either the PROCEDURE statement or the first statement following the PROCEDURE statement, depending on the execution environment). Specify the appropriate program source files and debug files with the CODEWATCH_SRCPATH and CODEWATCH_STBPATH environment variables when using PLITEST with this 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 Technical Support if requested.

strace

Creates a log file from the internal functions called by the program.

vtrace

Creates a dynamic visual trace of the program.

-optsql

Allows the SQL options to be passed to the SQL ECM

-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).

-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.

-ppdb2 [file]

Specifies the file name for the output of the DB2 preprocessor. An output file created with the -ppdb2 option is preserved after the compilation phase is completed. This option applies to mfplx only.

-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.

-proto

Provides more extensive prototype checking on arguments vs. parameters in entry declarations (also assumed by default when using -vax).

Example:

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

   myproc: procedure(a,b,c);        /* mismatch diagnosed, -proto and -vax */
      declare a fixed binary(15);
      declare b fixed binary(15);
      declare c fixed binary(15);

   end t660;

-range

Validates all static array bound references at compilation time, and generates code to check the run time validity of all subscript references, and substring bounds. Note that the checking code slows down execution time performance.

Exceeding array or string bounds at run time, raise either the SUBSCRIPTRANGE or STRINGRANGE conditions as appropriate. Use this option to debug programming errors relating to subscripts and substrings. Use the -norange option for debugged code. The default is -norange.

-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.

-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

Initializes automatic storage to zero.

-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 along with 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

Does not suppress INFORMATIONAL and WARNING level diagnostics. This is equivalent to setting the -flag option to I. 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.

-xref full short

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 of referenced. Only label references on END statements are not included in the listing when using -xref.

Use full with -xref to include all identifiers and attributes in the listing. Use short with -xref to exclude unreferenced identifiers.

-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 SupportLine.

Attention: This feature is in Early Adopter Product (EAP) release status. We intend to provide the finalized feature in a future release. Please contact Micro Focus SupportLine if you require further clarification.

-zchar

Specifies that the default alignment attribute for the CHAR, CHAR VAR , GRAPHIC, GRAPHIC VAR, WIDECHAR, WIDECHAR VAR and PICTURE data types is unaligned. The Open PL/I default is aligned.

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 RS6000, 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 */