HP 3000 Manuals

Making Applications Portable [ Micro Focus COBOL for UNIX COBOL User Guide ] MPE/iX 5.0 Documentation

Micro Focus COBOL for UNIX COBOL User Guide

Making Applications Portable

This section describes how to use the INTLEVEL Compiler directive to
develop portable applications. The directive has the format:

[NO]INTLEVEL"integer"

where integer can take a value of 1 or 2.

Unless otherwise specified, descriptions apply to both INTLEVEL"2" and
INTLEVEL"1".

Supported Environments

The COBOL systems required to achieve INTLEVEL"2" portability are:

* On DOS: Micro Focus COBOL V3.0 or later for DOS and OS/2 together
with Micro Focus Toolset V3.0 or later

* On DOS: Microsoft COBOL V4.5 or later together with Micro Focus
Toolset V3.0 or later

* On UNIX: Micro Focus COBOL V3.0 or later for UNIX

The COBOL systems required to achieve INTLEVEL"1" portability are:

* On DOS: Micro Focus COBOL/2 V2.5 or later with Toolset V2.5 or
later

* On DOS: Microsoft COBOL V4.0 or later with Toolset V2.5 or later

* On UNIX: Micro Focus COBOL/2 V1.3 or later for UNIX

Introduction to Portability

This COBOL system offers the ability to execute applications by having an
interpreter (in the run-time system) execute the intermediate code.
Under certain circumstances the intermediate code can be executed on a
different machine and operating system to that on which it was created.

The ability to migrate intermediate code enables Value Added Resellers
(VARs) and Independent Software Vendors (ISVs) to address the needs of
vertical markets and to help provide open system solutions.

The value of providing a COBOL solution across multiple operating system
environments such as DOS, OS/2, Windows, and many UNIX variants
(equivalent COBOL systems are available on hundreds of different variants
of UNIX) is confirmed by the directions taken by the Open Software
Foundation (OSF) with their Architecture Neutral Delivery Format (ANDF).

Generated code, being native machine code, usually gives a gain in
performance of an order of magnitude over intermediate code. If you
require performance rather than portability you should use generated
code. Intermediate code is preferable if your main interest is in
portability and ease of distribution. If appropriate to your business,
this or an equivalent COBOL system can optimize the intermediate code
into generated code for the machine and operating system in use.

Creating Portable Intermediate Code

This section discusses the operating system, environment, and COBOL
syntax issues you must consider when creating portable code. It also
covers restrictions you should observe to ensure portability.

Using INTLEVEL.

By specifying the INTLEVEL"2" Compiler directive, you can ensure that any
intermediate code created on any environment (using any of the COBOL
language as defined in your Language Reference) is portable to any other
environment that supports INTLEVEL"2".

The INTLEVEL"2" Compiler directive is equivalent (at the COBOL language
level) to the MF"8" Compiler directive
. Specifying INTLEVEL"2" does not flag or reject any syntax (or calls)
outside of the scope of the INTLEVEL"2" definition.

In addition to this syntax, there are the CBL_ library routines
. These provide generic system-level extensions to the COBOL language.
For details on the CBL_ routines available, see the chapter Library
Routines (Call-by-Name) in your COBOL System Reference.

By observing the portability guidelines and known restrictions listed
later in this chapter, you can ensure that the resulting intermediate
code executes with the same results on the Micro Focus COBOL for DOS and
for UNIX products.

The intermediate code can be subsequently translated into native code by
the equivalent Micro Focus COBOL system for execution in the required
environment.

Using INTLEVEL"1".

INTLEVEL"1" restricts you to the following COBOL syntax:

* All syntax and data types defined at the high level of the ANSI
COBOL standard X3.23-1974, except for the Communications module
and the Sort-Merge module.

* All syntax and data types defined in the high level of the ANSI
COBOL standard X3.23-1985, except for the Communications module
and Sort-Merge module.

* All RM/COBOL syntax and data types documented in your Language
Reference--Additional Topics and Compatibility Guide as supported;
except as detailed in the section Restrictions.

* USAGE COMP-3.

* USAGE COMP-5, except as detailed in the section Restrictions.

* The screen handling module, Adis, including Screen Section and
Enhanced ACCEPT/DISPLAY; except as detailed in the section
Restrictions.

WARNING Exceeding the portable syntax subset with INTLEVEL"1" specified
has unpredictable results either when the code is created or
when it is executed. There might not be any indication of this
when the code is created.

Portable Syntax

The following sections provide guidelines on using COBOL syntax when
creating portable applications using INTLEVEL"2" and INTLEVEL"1".

When developing portable applications you should keep in mind your
objective and be very careful not to make them environment-specific--for
example, by hardcoding a file-name. In many situations, you can use the
CBL_ library routines to help you avoid environment-specific code.

You can use all the COBOL syntax defined by the MF"8" directive, except
for that listed in the section Restrictions.

You do not need the dialect-controlling directives to ensure portable
intermediate code, and specifying them does not guarantee that
non-portable syntax is flagged when the program is syntax-checked.
However, it is useful to set the following directives, as this reduces
the possibility of inadvertently using non-portable syntax:

MF"4"

NODG

NOVSC2

NOOSVS

NOIBM-MS

Restrictions

The following sections list restrictions you must observe to ensure
portability.

COBOL System Library Routines.

Of the call-by-name library routines, only those whose names begin with
CBL_ are portable. The call-by-number routines are not portable. For
details on the available CBL_ routines, see the chapter Library Routines
(Call-by-Name) in your COBOL System Reference.

ACCEPT and DISPLAY.

Limit the Data Division of any program that has a Screen Section or uses
Enhanced ACCEPT/DISPLAY to 64 kilobytes (64K). If you compile with
INTLEVEL"1" or INTLEVEL"2" and do not observe this limit, you get RTS
error messages.

You can use the directives CHIP"16" and FLAG-CHIP
to make the Compiler warn you if you exceed this limit.

RM COBOL Semantics.

RETRYLOCK directive.

Do not use the RETRYLOCK directive.

WARNING In COBOL for DOS, the RM directive automatically sets RETRYLOCK.
If you use the RM directive, you must specify NORETRYLOCK after
it.

RM file statuses.

Intermediate code created on UNIX using the RM directive does not give RM
file statuses by default when run on DOS. You can get RM file statuses
returned on DOS by having the COBOL system map Micro Focus file statuses
to RM file statuses.

A mapping routine, RMSTAT, is supplied with Micro Focus COBOL for DOS. To
use this routine under the Run-time Environment, you set the
environment variable XFHCONV=RMSTAT before executing your program. To
use it with a linked application, you include rmstat.obj
in the link and set XFHCONV=RMSTAT before executing your program.

Fixed File Attribute Conflicts.

When a fixed file attribute conflict is detected by intermediate code
created with INTLEVEL"1" or INTLEVEL"2":

* Code created on DOS and running on UNIX returns file status error
9/139 rather than 3/9.

* Code created on UNIX and running on DOS does not give a file
status error.

Files with no FILE STATUS Item.

In a program compiled on DOS with INTLEVEL"1" or INTLEVEL"2", if a file
is defined with no FILE STATUS item but is referenced in a USE statement
in the Declaratives, the declarative procedure does not execute when a
file exception is detected. Instead a n RTS error occurs as if the USE
statement had not been specified. You can avoid this by always defining
a FILE STATUS item for each file.

Key Sequence Checking.

Key sequence checking returns a different status on DOS and UNIX. For
compatibility set the K RTS switch
for programs executing on UNIX.

Windowing Syntax.

The Windowing syntax is only available on UNIX environments. It is not
portable.

Other Directives.

There are a number of other directives that can affect the intermediate
code created. When portable intermediate code is required, you should
use the default settings of these directives. The list below shows the
directives that, if available on your COBOL system, can be altered
without preventing your intermediate code being portable:

Portability Guidelines

The following sections provide additional guidance on developing
applications that are portable between the COBOL for DOS and COBOL for
UNIX environments.

Operating System Specific Features.

Try to avoid using any features specific to your operating system. If
you must use them, your application can find out which operating
system it is running on by using the COBOL system library routine
CBL_GET_OS_INFO. See the chapter Library Routines (Call-by-Name) in your
COBOL System Reference for a description of this routine.

The User Attribute Byte.

A major area of incompatibility between the COBOL for UNIX and the COBOL
for DOS systems is the definition of the user attribute byte. It is best
to avoid using this; instead, to select video attributes, use the
language extensions in the portable syntax subset defined in the section
Portable Syntax. The video attributes that can be displayed depend upon
the hardware on which the program is running. The following attributes
can be specified in several ways using COBOL syntax:

BACKGROUND-COLOR

BLINK

FOREGROUND-COLOR

HIGHLIGHT

LOWLIGHT

NO-ECHO

REVERSE-VIDEO

SECURE

UNDERLINE

Screen I/O.

Screen I/O for programs executed using the CBL_EXEC_RUN_UNIT routine is
not portable between DOS, Windows, and OS/2 environments and UNIX
environments.

Under DOS, Windows, and OS/2, all programs write to the Video Screen Map,
so all programs executed are aware of each others' screen I/O.

Under UNIX, each program executed implements its own screen map. That
means that none of the programs executed are aware of any other program's
screen I/O. Thus, using screen I/O for programs executed using
CBL_EXEC_RUN_UNIT under UNIX can lead to unexpected results.

Case Sensitivity.

The UNIX file system is case sensitive. The DOS file system is not.

Applications developed on UNIX that are to be run on DOS should not
differentiate the names of called subroutines or data files by case
alone.

Applications developed on DOS that are to be run on UNIX must use called
subprogram names and data file-names that match exactly the names of the
physical files on the file systems.

The default extension for intermediate code on DOS is .INT (all upper
case). On UNIX the default extension is .int (all lower case). When
moving intermediate code created on DOS to UNIX, you must change the case
of the intermediate code file extension. Using the UNIX Bourne shell,
the following commands make the necessary change to all file names in the
current directory that have the extension .int:

for i in *.INT
do
mv $i `basename $i INT`int
done

Similarly, each overlay for a segmented program has an extension in the
format .Inn. On DOS the "I" is upper case, while on UNIX it is lower
case. These extensions also must be changed to the correct case.

Paths.

On DOS the separator for directories in a path to a file is the backslash
character (\). On UNIX it is the forward slash character (/). However,
on DOS "/" is recognized when used in a COBOL program, so you should use
"/".

Obviously, if paths to files are specified in a program, then the
relevant directory structure must exist on all machines where the program
is to be run.

DOS recognizes drive identifiers (for example, a:) in paths. UNIX would
assume these to be part of the file-name. Therefore, you should not use
drive identifiers.

Extended Character Sets.

COBOL on DOS supports certain PC-specific features. Generally these take
advantage of the special video characteristics of the IBM PC, PS/2, and
compatibles.

The most important is the IBM Extended Graphics Character Set. On DOS,
you can include eight-bit graphics characters in your source code. Some
UNIX systems support only seven-bit characters; the eighth bit might be
stripped from your source when you use a UNIX editor such as vi. Other
UNIX systems support different eight-bit character sets, for example the
ISO 8859-1 character set.

Therefore, eight-bit characters input on one operating system might
appear different on another. You should avoid using characters from
extended character sets unless you are certain that your target operating
system and hardware support them. Alternatively, use the generic
character routines CBL_GET_SCR_LINE_DRAW and CBL_GET_SCR_GRAPHICS which
supply the nearest equivalent characters to be used for line drawing and
graphics in all environments.

On DOS systems, these routines are supplied with Toolset.

The Alt and Ctrl Keys.

Most UNIX terminals cannot detect the Alt or Ctrl key being pressed
unless another valid key is pressed at the same time. Avoid using these
keys by themselves.

UNIX If you are running under UNIX, see the section
Control and Alt Key Support in the chapter Terminfo
Database and Terminals and the appendix UNIX Key
Usage Chart in your COBOL System Reference.

USAGE COMP-5.

The individual bytes of items described as COMP-5 are stored in the order
in which they would be stored by the machine code of the host machine.
This means their internal representation might differ depending on the
computer on which the program is being run. Therefore, avoid redefining
COMP-5 items or writing COMP-5 data items to files.

$SET and Generator Directives.

Do not embed directives that affect generated code in the source of your
program (using $SET); they might not be meaningful on all machines where
the program is to be run.

The ROLLBACK Statement.

Applications that use the ROLLBACK phrase are only portable within the
Fileshare Version 2 environment. For non-Fileshare Version 2
environments, the ROLLBACK phrase causes all record locks to be released
for all UNIX systems, and on DOS systems if the CALLFH Compiler directive
has been specified.

Creating Portable Source Code

Read this section if instead of porting intermediate code between DOS and
UNIX you simply want to produce source code that compiles on both
operating systems.

All COBOL syntax supported by COBOL on UNIX is supported on DOS. However,
COBOL on DOS supports advanced syntax not available on UNIX prior to
Micro Focus COBOL V3.0 for UNIX.

Limiting your COBOL syntax to that supported on UNIX ensures that your
application is acceptable for syntax-checking on either DOS or UNIX. If
you are developing on DOS, setting the directives:

NOMS

MF"4"

VSC2"1"

helps to enforce it.

You should also observe the Portability Guidelines detailed in section
Creating Portable Intermediate Code.

File Portability.

The following table shows the portability of files between Micro Focus
COBOL for DOS, Windows, and OS/2 and Micro Focus COBOL for UNIX. Files
marked with an X are not portable.

MPE/iX 5.0 Documentation