HP 3000 Manuals HP 3000 Manuals
Making Applications Portable
This section describes how to use the INTLEVEL "integer" compiler
directive to develop applications that will be portable at either source
code or intermediate code level between Micro Focus COBOL for DOS and
OS/2 as implemented on DOS and OS/2 and Micro Focus COBOL for UNIX as
implemented on UNIX.
These are referred to throughout as COBOL for DOS and COBOL for UNIX
respectively. However, for brevity, this appendix refers to DOS to mean
both PC-DOS and OS/2.
INTLEVEL "integer" can take either a value of 1 or 2.
Unless otherwise specified, descriptions apply to both INTLEVEL"2" and
INTLEVEL"1".
Assumed User Environment
The products required to achieve INTLEVEL"2" portability are:
* on DOS: Micro Focus COBOL for DOS and OS/2 together with TOOLSET
V3.0
* on UNIX: Micro Focus COBOL for UNIX V3.0
The products required to achieve INTLEVEL"1" portability are:
* on DOS and OS/2: Micro Focus COBOL/2 with TOOLSET V2.5
* on UNIX: Micro Focus COBOL/2 for UNIX V1.3
Introduction to Portability
This appendix assumes a working knowledge of the DOS and UNIX operating
systems and of Micro Focus development systems on these operating
systems.
Micro Focus COBOL systems have always offered the ability to execute
applications by having an interpreter (the Run Time Environment) 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.
Micro Focus products have benefited from this for a number of years,
since they are written in Micro Focus COBOL.
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
platforms such as DOS, OS/2, and many UNIX variants (Micro Focus COBOL is
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, so 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. In any case, if appropriate to your business, a Micro
Focus COBOL system can translate 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"2".
On DOS and UNIX
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) will be portable to the
other environment. 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 Chapter 8 , Library
Routines (Call-by-Name).
By observing the portability guidelines and known restrictions listed
later in this chapter you can ensure that the resultant intermediate code
will execute with the same results on the Micro Focus COBOL for DOS and
for UNIX products.
The INTLEVEL"2" compiler directive is equivalent (at the COBOL language
level) to the MF"8" compiler directive
and is on by default. Specifying INTLEVEL"2" will not flag or reject any
syntax (or calls) outside of the scope of the INTLEVEL"2" definition.
The intermediate code subsequently can be translated into native code by
either the Micro Focus COBOL for DOS or COBOL for UNIX product for
execution in that environment.
Using INTLEVEL"1".
On DOS
By default, the intermediate code created on DOS is not portable to UNIX
as it contains instructions not supported by COBOL for UNIX.
There is a compiler directive INTLEVEL"1". When this is specified on
DOS, the intermediate code created will not contain any instructions that
are not supported on UNIX, provided the program uses only the COBOL
syntax defined in section "Portable Syntax" below.
By adhering to this COBOL subset, using INTLEVEL"1", and observing the
guidelines given later, you will get intermediate code that will execute
with the same results on DOS and on all existing Micro Focus COBOL
systems for UNIX.
The directive has two formats:
* NOINTLEVEL
the default. This makes the compiler produce intermediate code
suitable for execution only on PC-DOS.
* INTLEVEL"integer"
integer must be 1.This makes the compiler produce intermediate
code that can be executed on both PC-DOS and UNIX.
Intermediate code created with INTLEVEL"1" may be less efficient than
that created with NOINTLEVEL.
On UNIX
The intermediate code created on UNIX is a subset of that recognized on
PC-DOS.
As on PC-DOS, by adhering to the COBOL subset given below, using
INTLEVEL"1", and observing the guidelines given later, you will get
intermediate code that will execute with the same results using COBOL on
PC-DOS and using COBOL on UNIX.
Intermediate code created using Micro Focus COBOL for UNIX will execute
with the same results on any other UNIX variant running the same version
of that Micro Focus system, regardless of the COBOL syntax subset used,
use of the INTLEVEL"1" directive, or conformance to the guidelines below.
It may not execute on other Micro Focus COBOL systems for UNIX without
first being recompiled.
Portable Syntax
The following sections provide guidelines on using COBOL syntax when
creating portable applications using INTLEVEL"2" and INTLEVEL"1".
Using INTLEVEL"2".
All supported COBOL syntax, as defined by the MF"8" compiler directive,
is available for the production of intermediate code programs that are
operating system independent (see Appendix G , Directives for
Compiler/Generator for details on the MF directive). However, as
previously stated, there are some run-time restrictions that apply (see
below). The current COBOL dialects that Micro Focus COBOL supports are
defined in your Language Reference.
It is, of course, possible to develop COBOL programs that are environment
specific (for example, hardcoding a file-name), so when developing your
applications you should keep in mind your objective of creating a
portable application. In most situations, you can use the CBL_library
routines to enable you to do this.
You can use all the COBOL syntax defined by the MF"8" directive, except
for those listed in the section "Restrictions" .
Using INTLEVEL"1".
This section details the syntax subset that you must adhere to in order
to create intermediate code that is portable between UNIX and PC-DOS: *
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 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 Micro Focus screen handling module including Screen Section
and Enhanced ACCEPT/DISPLAY (that is, the additional formats of
the ACCEPT and DISPLAY statements described in your Language
Reference); except as detailed 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 will be 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
WARNING Exceeding the portable syntax subset with INTLEVEL"1" specified
will have unpredictable results either when the code is created
or when it is executed. There may not be any indication of this
when the code is created.
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 Chapter 8 , Library
Routines (Call-by-Name).
COMP-5.
On DOS, overflow of unsigned COMP-5 items behaves as for COMP-X items; on
UNIX it behaves as for COMP items (see your Language Reference for
details). On DOS, you can make it behave as on UNIX by using the
directive COMP-5"1". On UNIX, the default DOS behavior is not available.
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 will get
run-time 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 will 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 will not be executed when
a file exception is detected. Instead a run-time error will occur as if
the USE statement had not been specified. You can avoid this by always
defining a FILE STATUS item for each file.
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
ALIGN FLAG RESEQ
ALPHASTART FLAGQ RETRYLOCK
ALTER FLAGSTD REWRITE-LS
ANALYZE FLAG-CHIP RM
ANIM FORM RTNCODE-SIZE
ANS85 IBMCOMP SEG
ASSIGN IBM-MS SEQCHK
AUTOLOCK KEYCOMPRESS SEQUENTIAL
BELL LINKCOUNT SETTING
BOUND LIST STRUCT
BRIEF LISTWIDTH SHOW-DIR
CHARSET MFCOMMENT SUPFF
CHIP NATIVE SIGN
COMP NESTCALL SPZERO
CONFIRM ODOSLIDE SYMBSTART
COPYLBR OLDCOPY TIME
COPYLIST OLDINDEX TRACE
CURRENCY-SIGN OPTIONAL-FILE TRUNC
DATE PERFORM-TYPE VERBOSE
DEFAULTBYTE PROGID-COMMENT WARNING
ECHO QUAL WRITELOCK
ECHOALL QUERY XREF
ERRLIST RECMODE ZEROSEQ
ERRQ REF
FILESHARE REFNO
Portability Guidelines
The following sections provide additional guidance on developing
applications that will be portable between the COBOL for DOS and COBOL
for UNIX environments.
Operating System Specific Features.
Try to avoid using in your application 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 Chapter 8 , Library Routines
(Call-by-Name) 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 will
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
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 will 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 "/" will be 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 may 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 may 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.
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.
See the section "Control and Alt Key Support" in the chapter Device
Handling and Terminfo and Appendix N , UNIX Key Usage Chart for
further information of these keys.
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 may 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 .GNT Code Directives.
Do not embed
directives that affect generated code in the source of your program
(using $SET); they may not be meaningful on all machines where the
program is to be run.
The ROLLBACK Phrase.
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 PC-DOS
and UNIX you simply want to produce source code that will compile on both
operating systems.
All COBOL syntax supported by COBOL on UNIX is supported on PC-DOS.
However, COBOL on PC-DOS supports advanced syntax not available on UNIX
prior to Micro Focus COBOL V3.0.
Limiting your COBOL syntax to that supported on UNIX ensures that your
application will be acceptable for syntax-checking on either PC-DOS or
UNIX. If you are developing on PC-DOS, setting the directives:
NOMS
MF(4)
VSC2(1)
will help to enforce it.
You should also observe the Portability Guidelines detailed in section
"Creating Portable Source Code" .