| Handling Protection Violation Errors | Migrating Applications | |
This chapter provides guidelines on developing applications that are portable at either source code or intermediate code level between this COBOL system and equivalent systems on other environments. These systems are principally COBOL for DOS and COBOL for UNIX respectively. For brevity, this chapter refers to DOS to mean DOS, Windows and OS/2.
Portability is achieved using the INTLEVEL Compiler directive. The guidelines in this chapter describe programming methods that enable you to make best use of this directive in creating portable applications.
This chapter assumes a working knowledge of the DOS and UNIX operating systems and of this COBOL system and its equivalents on these operating systems.
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".
The COBOL systems required to achieve INTLEVEL"2" portability are:
The COBOL systems required to achieve INTLEVEL"1" portability are:
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 from 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, Windows, OS/2, 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.
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.
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.
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.
INTLEVEL"1" restricts you to the following COBOL syntax:
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.
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 hard-coding a filename. 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 |
The following sections list restrictions you must observe to ensure portability.
Of the call-by-name library routines, only those whose names begin with CBL_ are portable. The call-by-number routines are not portable.
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 run-time system error messages.
You can use the directives CHIP"16" and FLAG-CHIP to make the Compiler warn you if you exceed this limit.
Do not use the RETRYLOCK directive.
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 COBFSTATCONV=RMSTAT and compile your program with the COBFSTATCONV directive before executing your program. To use it with a linked application, you include rmstat.obj in the link and set COBFSTATCONV=RMSTAT before executing your program.
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 run-time system 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.
The windowing syntax is only available on UNIX environments. It is not portable.
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 | FLAG-CHIP | RETRYLOCK |
| ALTER | FLAGQ | REWRITE-LS |
| ANALYZE | FLAGSTD | RM |
| ANIM | FORM | RTNCODE-SIZE |
| ANS85 | IBM-MS | SEG |
| ASSIGN | IBMCOMP | SEQCHK |
| AUTOLOCK | KEYCOMPRESS | SEQUENTIAL |
| BELL | LINKCOUNT | SETTING |
| BOUND | LIST | SHOW-DIR |
| BRIEF | LISTWIDTH | SIGN |
| CHARSET | MFCOMMENT | SPZERO |
| CHIP | NATIVE | STRUCT |
| COMP | NESTCALL | SUPFF |
| CONFIRM | ODOSLIDE | SYMBSTART |
| COPYLBR | OLDCOPY | TIME |
| COPYLIST | OLDINDEX | TRACE |
| CURRENCY-SIGN | OPTIONAL-FILE | TRUNC |
| DATE | PERFORM-TYPE | VERBOSE |
| DEFAULTBYTE | PROGID-COMMENT | WARNING |
| ECHO | QUAL | WRITE-LOCK |
| ECHOALL | QUERY | XREF |
| ERRLIST | RECMODE | ZEROSEQ |
| ERRQ | REF | |
| FILESHARE | REFNO |
The following sections provide additional guidance on developing applications that are portable between the COBOL for DOS and COBOL for UNIX environments.
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.
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 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.
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 filenames 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.
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 filename. Therefore, you should not use drive identifiers.
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.
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 Terminal Devices in your Object
COBOL User Guide.
The value returned by some COBOL operations is specified in the Language Reference as undefined; for example, dividing by zero, or using data that does not conform to a picture clause. If you were to examine the values actually returned by these operations, you would find that they differ according to the executable file format and the COBOL system on which the program was compiled.
For example, a divide-by-zero operation might return a different value in an intermediate code program to that returned in a generated code program. Similarly, the value returned in a program compiled on the 16-bit COBOL system might be different from the value returned in the same program compiled on a 32-bit COBOL system.
You should ensure that the results or logic of your program do not depend on the results of operations specified as giving undefined results. For example, as the result of a divide-by-zero operation is unpredictable, you should always use the ON SIZE ERROR phrase if you want a specific action or procedure to be performed depending on this result. See the description of ON SIZE ERROR in your Language Reference for more details.
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.
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.
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.
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 the section Creating Portable Intermediate Code.
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 those marked with a Y are.
| File Format | File Organization | DOS to UNIX | UNIX to DOS |
|---|---|---|---|
| Fixed | Line Sequential Record Sequential Relative Indexed - CISAM Indexed - Level II Indexed - IDXFORMAT3 Indexed - IDXFORMAT4 |
Y Y X Y Y Y Y |
Y Y X Y Y Y Y |
| Variable | Line Sequential Record Sequential Relative Indexed - IDXFORMAT3 Indexed - IDXFORMAT4 |
Y Y Y Y Y |
Y Y Y Y Y |
Note: File-naming conventions for indexed files differ between OS/2 and UNIX.
Copyright © 1998 Micro Focus Limited. All rights reserved.
This document and the proprietary marks and names
used herein are protected by international law.
| Handling Protection Violation Errors | Migrating Applications | |