Installation Guide

llJ~r~

^TM

INCORPORATED

High C ™

Installation Guide

Version 1.2 Concurrent DOS

by Meta Ware

^TM

Incorporated

High C ^....

Installation Guide

Version 1.3 for Concurrent DOS 286

~1 983-86 .. MetaWare- Incorporated .. Santa Cruz .. ^CA . All rights reserved

NOTICES

The software described in this guide is licensed. not sold. Use of the soft- ware constitutes agree~ent by the user with the ter~s and conditions of the End-User License Agree~ent packaged with the software. Read the Agree~ent

carefully. Use in violation of the Agree~ent or without paying the license fee is unlawful.

Every effort has been ftade to ~ake this guide as accurate as possible. How- ever, Heta~are Incorporated shall have no liability or responsibility to any person or entity with respect to any liability. loss. or daftage caused or alleged to be caused directly or indirectly by this guide. including but not

li~ited to any interruption of service. loss of business or anticipated pro- fits, and all direct. 1ndirect. and consequential daftages resulting froft the use of this guide and the software that it describes. .

MetaWare Incorporated reserves the right to change the specifications and characteristics of the software described in this guide. fro~ tifte to tifte.

without notice to users. Users of this Quide should read the file nafted

"READHE" contained on the distribution ~ed1a for current inforftation as to changes in files and characteristics. and bugs discovered in the software.

like all coftputer software this prograft is susceptible to unknown and undis- covered bugs. These will be corrected as soon as reasonably possible but cannot be anticipated or eliftinated entirely. Use of the software is subject to the warranty provisions contained in the License Agreeftent.

Y.04.15.86

A. M. D. G.

Trademark Acknowledgments is a tradeftark of 01gl tal Research. Inc.

Digital Research. Inc.

MetaWare Incorporated MetaWare Incorporated MetaWare Incorporated AT&T Bell laboratories. Inc.

@ 1983-86 HetaWare Incorporated

Installation Guide

page 1

Installation Guide

for the

High C ... Compiler

Version 1.3 for Concur rent DOS 1.2 and Later

Table of Contents

No. Section Title Pi!M

1. Requirements and Assumptions ... 2

2. Installation ..••.••••.•••••••.••••.•••... 2

3. A Small Demonstration ... 3

4. Changing Memory Models ....•..•••••••.•.• 3

5. Installing an Individual Memory Model. ... 4

6. Uti I ities ...•••...•...•.. 4

1. Compiling and Executing Programs ... 5

8. Recommended File Organization ... 6

9. Distribution Diskettes ~ontents ... 9

10. Configuring the Compiler .••••••. ' ••••••••• 12 11. Embedded Applications ... 13

12. Solutions to Potential Problems ... 15

Last ... 16

Y.04.15."86 (CJ 1983-86 Hetavare Incorporated

1.0 Requirements and Assumpt ions 1. Hard disk space needed with

Compiler, associated support software, and

Small memory model I ibtary ... 1.7 MB Libraries for additional nu~rnory rnudels ... 0.9 MB Utilities ... 0.2 MB Allow about 230KB per library pair: co-processor and emulator versions.

2. ???KB of main memory to run the compiler in non- overlaid mode .. and ???KB in overlaid mode. But note:

use of the -ansi option requires about 15K more - the -ansi option turns off any and all extensions beyond the (proposed) ANSI Standard. [[[??? Fill in KB sizes above. 111 3. You have a 1.2MB floppy disk drive designated as A: .. and

a hard disk drive known as C:. All installation proce- dtres install from A: aMontoC:. If these drive letters are different on your system, make the appropriate substitutions when typing in commands from this docu- ment .. and change the contents of the suppl ied . BAT fi les ..

or use the Cuncur rent ASSIGN curnrnand to change drive letter assignments.

2.0 Installation

Due to the compiler's size, you must install it on your hard disk before using it. To install the compiler, do the following:

1. Create a directory on your hard disk where you want the compiler and associated software to reside. Make that directory your work i ng d i rectory. For examp I e:

lid Ihighc cd Ihighc

to create a directory at the root called "'highc" and make "highc^H the working directory.

2. Get your floppies ready. Put the floppy labeled # 1 into the A: dr ive.

v.D4.1S.86 (9 1983-86 HetaWare Incorporated

Installation Gui.de pnge 3

3. fype "a: install". INSTALL will prompt you to load the appr opria tely nurF1b~r ~d fluppies and it wi II extr act the information from them.

3.0 A Small Demonstration

After the compiler is installed, he. 286 - the non-overlaid version of the compiler - and the Aun- Time Library for the Small memory model reside on the hard disk. You can then get a small demonstration of the compiler in operation by enter-

ing:

s.aldenlO

If you do not have enough memory to run the compiler non-overlaid^l you wi II have to run the INSTALL2 batch fi Ie to install the overlaid campi ler (on diskette #3), or you can just copy it yourself. The overlaid campi ler is named heav.286.

Replace he. 286 with the overlaid version by typing copy A:heov.286 C:he.286

4.0 Changing Memory Models

Typically, you wi II write programs that use one memory model; the next section below tells how to install just one model. The campi ler supports five memory models to make optimal use of the 8088/80861186/188/286 processor. Refer to the Programmer's Guide for a d~r.ript inn of the memory models.

To install the rest of thE:! rnudE:!ls (and thE:! utility prugrarns described in Section Uti/ilies-beluw), rnClke sure thClt you still have about 1.1 MB of free hard disk space, then enter:

instal12

You can see a demonstration of programs running in all the memory models by typing

alldemo

'1.04. 15.86 @ 1983-86 HetaYare Incorporated

5.0 instal I ing an Individual Memory Model

To install the Run-Time Library of a given memory model, copy its directory from distribution diskette #2. See below for a I ist of the diskettes and their contents.

For example .. copy the compact directory from diskette #2 to get the Library for the Compact model. If your want to replace one or more Libraries of other memory models with' this Library .. you should delete their directur ies in Ihighc ..

either before or after thi!; !;tep. In general, you may delete any Library directory at any time is is not needed.

The suppl ied batch file GETMOD automates the selection and copying of a particular memory model. Type

get.od memory_model_name

where metnory_model_name is slllCill .. mediullI, CUillpocl .. big .. or large (typed in all lower case). Also, if memory_model_name is utils .. BEllO) copies the uti I ities described next.

6.0 Uti I ities (Concurrent Helper-)

The Compiler and Run-Time Libraries are distributed with a set of UNIX--like uti I ity programs, called Concurrent Help- er-.. that can much enhance productivity on Concurrent. The uti lit ies provide a host of capabi I i ties lacking in the oper at ing system itself, such as file Clr chiving Clnd sear ching functions.

The utilities can be used to maximize performance and organ- ization under the versati Ie Concurrent hierarchical directory structure.

Concurrent Helper consists of eight distinct programs:

FiND faci litates general-purpose .. powerful directory main- tenance and archiving. (FINO is used by the INSTALL program to lUCId the curnpiler.)

TAIL prints the "tailH (last few lines) of a file.

HV renames one or more files or moves them from one direc- tory to another.

V. 04.15.86 ^(g 10R3-A6 HetaUaTp. Incorporated

Installati.on Gui.de page 5

lS lists the contents of directories in various useful formats.

CAT concatenates a sequence of fi les into a single fi Ie.

UNIQ removes duplicates of lines rrom a fi Ie.

FGREP rapidly searches a file or files for a string pattern.

(FGRF.P is an attractive alternative to a bulky printed paper cross-refer ence, since it is very fast.)

Ie counts the number of lines and words in one or more files.

Th~p. utilitip.s arp. dp.~crihp.d in rietail in the on-line docu- mentation on the last diskette.

7.0 Compiling and Executing Programs

TheProgrammer·s Guide tells you how to compile .. link,·

and execute programs. But just to get you started quickly,

herf~ are the essential instructions:

1. Edit a program into a file "hello. eN. For example, main() {

printf(MHello, world.^{M) ;}

}

(demos/hello. e contains a copy of this program.) 2. Run the compiler:

he hello

just to compile, or

he hello -on list> hello.l

to produce a listing and send it to file "hello. 1".

3. Link lh~ pr ugr am:

1 ink hp.llo, slIln 11/hcsp.. 186

4. Aun the program:

hello

You should receive a greeting.

v.D4.15.86 (9 1Q83-R6 "et8Uare Incorporated

Installation Guide

8.0 Recommended t-i Ie Organization

Once you have installed the compiler, it resides in its own directory which we wi II assume is called Ihighc. However, you will probably not want to do program development from this dir eclory. A better idea is to leave the Ihighc directory alone and do your work elsewhere.

To do this, you must arrange matters so that the compiler, and preferably Concurrent Helper, arc r.nsi Iy r.xr.r.utClblc from

your program dp.vp.lopmp.nt dirp.r.torip.s, and so that the Run- Time L ibrary( -ies) you I ink to are easi fy avai fable.

To make the campi ler and uti lities executable from any di- rectory, Ihighc/hc.286 and the. 286 utility files must be visi- ble on your execution path. We recommend that you construct a Ibin directory (following UNIX cunventiuns, fur "binary executables^{H) ..} if you have not already, and place all common executables there.

Instruct Concurrent to search the Ibin directory for

hc.286 by' adding "c: Ibin^H to the "path^H• For information on

"pathN, see the Digital Research Concurrent DOS User's Guide manual section on Concurrent DOS Commands.

Assuming that you run INSTALL2, or use "getlDod utils· for the utilities only .. as presented above .. you must first move all the utilities into your Ibin directory. Enter

cd Ihighc/utils

IIIV *.7.Rfi Ibin

which moves all the utility programs into Ibin. The "IRY^u

command is one of the Concurrent Helper uti I ities.

Now move the compi ler ~~hc.ll:Jtj" to Ibin from Ihighc by entering:

mv Ihighc/hc.286 Ibin

Any Run-Time Libraries you use may also reside in /bin.

For purposes uf i lIustr ation, assume that you intend to use the

v.D4.1S.B6 ~ 19R3-R6 HetaYare Incorporated

Installation Guide page 7 Small memory model with floating-point emulation, so that the Run-Time Library you wi" I ink to is "hcse.186". Enter:

mv Ihighc/small/hcse.185 Ibin to move the I ibrary there.

High C comes with the standard ANSI -required ^{I t .} h" head- er fi les. These fi les are located in the" Ihighc/inc" directory.

In addition there are a collection of "uti I ity packages" with suffix". cf" whose interfaces are located in the" Ihighc/inc"

directory. The packages provide access to Concurrent directly and supply useful utility routines. See both the Programmer's Guide and the contents of the fi les in " Ihighc/inc^{l l} for more

information.

You wi" want to access the package interfaces from what- ever directory you work in. One way of doing this is to use a full path name when including the package interface:

Binclude "/highc/inc/stdio.h"

main

0 {

int i;

for (i

=

0; i

<=

9; i++)

printfC"%d squared is %d/n", i, i*i);

}

However, the text " Ihighc/inc/stdio. h" in your program requires program changes should you want to move the "inc"

directory elsewhere. To avoid this inconvenience you can direct the compi ler to search a sequence of directories when opening input fi les (such as a linclude-d fi Ie above) by using the Concurrent "define ipath=" command ("ipath" for "in- put path'·). For example:

define ipath=/highc/inc/;lotherlstuff/;/etc/;

instructs the compi ler to look first in Ihignc/inc, then in

lotherlstuff, then in letc for input fi les. (For information on

" define", see the Digital Research Concurrent DOS User·s Guide manual section on Concurrent DOS Commands.) With this, the above program can be simplified:

v.04.15.86 ~ 1983-86 MetaUare Incorporated

'include "stdio.h"

main () { int i;

for (i

=

^0; i (= 9; i++)

printf("%d squared is %d/n~,i,i*i);

}

If you decide to change where stdio. h resides, you need only change the "ipath~~. For further information on "ipaths", see Section Compiler Contro/sin the Programmer IS Guide.

You may want to change your AUTOEXEC. BAT file to include the "define ipath=" command shown here. Then the ... ipath ....

will be defined every time the system is booted.

Alternatively, the form of 'include in which the fi Ie is not quoted but instead enclosed in the characters

<

and

>

searches first an

"<>-

include" search path that you can set up at installation time using the CONFIG program; see Configuring

the Compiler below. If you specify the value "/highc/inc/~~

for the <>-include search path, you can write 'include <stdi~.h>

main 0 { int i;

for (i = 0; i (= 9; i++)

printf("%d squared is %d/n",i,i*i);

}

to obtain the inclusion of Ihighc/inc/stdio. h.

If you plan to use the -ansi option, you must place the Ihighc/inc directory on the "ipath", since files necessary for operation in ANSI mode are stored in Ihighc/inc.

v.04.15.66 @ 1983-66 MetaWare Incorporated

Installation Guide page 9 9.0 Distribution Diskettes Contents

The contents of the distribution disks are as detai led below.

On diskette #1 you will not actually see all the files. Some are "hidden" inside a large". tar" fi Ie and are extracted when you run the INSTALL program discussed above. However, the library directories are directly visible on the second diskette, so it is easy for you to extract the portions of a desired mem- ory model subdirectory.

Any name I isted below that ends with a I is the name of a (sub- )directory.

Diskette No. Contents 1 install. doc

readme find. 286 demos/

bench.mks/

Description

The text of this document.

Last minute installation notes.

Uti I ity program to load the software.

Various demonstration programs.

Common bench-mark demos. .

inc/ . hand. pf interface fi les for accessing standard ANSI header files and the util-

ity packages in the Run-Time Libraries.

See the Library Reference Manual and the Programmer's Guide.

hcansi. st ANSI scan and hcansi. pt ANSI parse hcansip.pt tables.

hc.286 xref.285

*.bat config.285

v.04.15.B6

(Needed for the -ansi campi ler option.) The compiler.

The cross-referencer.

Various batch fi les.

Campi ler configuration program.

fi3 19B3-B6 HetaWare Incorporated

bd.285 A binary dump uti I ity that readably dis- plays the contents of .OBJ and .186 fi les.

Specify "bd f1 f2 _" to dump fi les f1, f2, .... To understand its output you must know Intel OMF; consult part number 121748-001, 8086 Aelocatable Object Module Formats, avai lable from Intel Corporation, 3065 Bowers Avenue, San- ta Clara, CA 95051.

clname.286 Uti I ity to change l-names in .OBJ fi les.

Consult the README fi Ie for more infor- mation.

libl

src/ Library sources currently being distri- buted. See Sect i on Embedded Applica-

tions in the Programmer's Guide for more details on the source. See also

Embedded App/icationsbe low.

etc/ . Last-minute or unclassified software.

2 small/ Run- Time Library for the Small model.

hcse.185 hcse.185 ptoc.185

c_close.obj c_heap.obj c_scanf.obj c-printf.obj cfinit.obj heap1.obj

stkdmp.obj hc.pro pp.pro

model. a85

mediuml Run- Time Library for Medium model.

heme. 185 c_close.obJ c"printf.obj stkdmp.obj model. a85

heme. 185 ptoc.185 c_heap.obj c_scanf.obj cfinit.obj heap1.obj

hc.pro pp.pro

compact/ Run- Time Library for Compact model.

v.04.15.86

heec.186 c_close.obj c_printf.obj stkdmp.obj . model. a86

heee.186 ptoc.186

c_heap.obj c_scanf.obj cfinit.obj heap1.obj

hc.pro pp.pro

fi3 1983-86 MetaWare Incorporated

Installation Guide page.1!

big/ Aun- Time Library for Big model.

hcbc.186 c_close.obj c-printf.obj stkdmp.obj model. a86

hebe. 186 ptoc.186 c_heap.obj c_scanf.obj cfinit.obj heap1.obj

hc.pro pp.pro

large/ Aun- Time Library for Large model.

hclc.186 c_close.obj c-printf.obj stkdmp.obj model. a86

hele.186 ptoc.186

c_heap.obj c_scanf.obj cfinit.obj heap1.obj

he. pro pp.pro

3 utils/

doc/

MetaWare Concurrent Helper uti I ities.

Documentation for the uti I ities.

hcov.286 Overlaid version of hc.285. Uses much less memory but takes longer to run due to operating system loader overhead.

The contents of each of the five model subdirectories are similar. For example, the contents of the small/ subdirectory are:

hcsc.186 c_close.obj c-printf.obj stkdmp.obj model. a85

hcse.186 c_heap.obj cfinit.obj hc.pro

ptoc.186 e_seanf.obj heap1.obj pp.pro

The first fi Ie is the Aun- Time Library ("he") for the Small model e's") that assumes an 8087 co-processor ("e"). The second does not assume an 8087 (" e'" = emUlator), but wi II use one if present.

ptoc.186 and cfinit.obj are used when linking with pro- grams written in MetaWare's Professional Pascal language.

stkdmp.obj and heap1.obj are used to obtain certain post- mortem traces. c_heap.obj is used to (almost) completely eliminate the heap manager if desired. c_close. obj, c_scanf .obj, and c-printf.obj similarly reduce memory require- ments. See the Programmer IS Guide, Section Linking a Com-

v.04.15.86 ~ 1983-86 HetaWare Incorporated

piled Program", for more detai Is. The source of c_heap. obj is lib/src/c_heap.c.

For each memory model M, the hc. pro fi Ie is a compi ler

"profi Ie" for use when compi I ing programs in M. It contains a pragma to set the memory model to M. See the Program- mer's Guide on the Memory_model pragma and the profi Ie. The pp. pro fi Ie is a si,mi lar profile, but for MetaWare's Profes- sional Pascal language. Use it when recompi I ing for model M suppl ied Run-Time Library source in lib/src; you wi II need this only for doing embedded appl ications programming - and you will need the Professional Pascal compiler for Concurrent.

File "model. a86" is used for assembling supplied Run-Time Library source; see EmbeddedApplicationsbelow.

The disk containing the MetaWare Concurrent Helper uti 1- ity programs contains all their documentation. There is no suppl ied hard-copy documentation for them.

10.0 Configuring the Campi ler

Various campi ler defaults are modifiable through direc- tives either specified on the compi ler invocation I ine, such as

"he program -off Warn" or in the source code of a program, such as "pragma Off (Warn); ~'.

The CONFIG program provides a way to change some of these defaults within the compiler itself.. so that the defaults hold for every program compi led. The CONFIG program actually modifies the campi ler executable fi Ie. The changed defaults hold unti I changed again by the CONFIG program.

Some of the configurables are: run-time checks; the num- ber of tree pages in memory during compi lation; the memory model to generate code for; whether to generate code for a 186/286 processor; the assumed suffix of source fi les when none is suppl ied with compi ler invocation; etc.

The CONFIG program is self-documenting. It tells you what defaults are configurable and guides you through changing

v.04.15.B6 ~ 1983-86 HetaWare Incorporated

Installation Guide page 13 them. For detai Is on what option,.pragma, and toggle defaults are configurable, consult the Programmer's Guide.

The configurable options are generally those that you set up once and then forget. In particular, you will probably want to set the -tpages value to one appropriate for your memory configuration.

[[[Appropriate suggestions for tpages?]]] The more -tpages, the less paging of the compi ler's internal tree to disk, and the faster the compi lation.

(Note that most "memory-mapped disk drives", also call- ed "mdrives'.I or "RAM disks", consume avai lable memory; if you have such a drive, be sure to adjust your computation of avai lable memory. If you have never heard of "mdrives", you probably do not have one and can ignore this parenthetical remark.)

11.0 Embedded Appl ications and Suppl ied Source Fi les For special appl ications environments, the source· of some of the Run-Time Library has been provided. Read the Pro- grammer's Guide Section Embedded Applications for more information as to the purpose and use of this source.

You can make any changes to the I ibrary source that you like, but note that all source in lib/src is copyrighted by MetaWare. You may use the source as long as only the object code of it leaves your premises. In essence, you have the same rights to the object code from this source as you do to the Run-Time Library object; you have the same rights and obi iga- tions with respect to the source as you do the campi ler object.

The MetaWare copyright notice must be preserved and be present in any I inked .286 fi les that use any portion of the MetaWare Libraries. The init. a86 source has a copyright notice in the data definition for the initial run-time stack that satisfies this requirement if it is preserved. If you replace

v.04.15.66 ~ 1963-66 MetaWare Incorporated

init. a85 entirely you must include such a copyright notice if you use any portion of the library.

Assembly source is written in Digital Research's "rasm"

assembly language, not Intel assembly ·Ianguage. To assemble it with a specific model in mind (Small, Medium, Big, etc.), the macro fi Ie "model. a85"", specific to each modeL must be included. It sets ,the parameters for the model. Therefore there are five "model. a86" sources. Each can be found in the directory by the same name as the model.

Thus .. for example .. to assemble init. a8S for each of the five models, you would need the following fi les:

lib/src/init.a86 small/model.a86 eompaet/model.a86 medium/model.a86 big/model. a86 large/model. a86

Other library routines are written in a combination of MetaWare's High C and Professional Pascal; to recompi Ie them for a particular memory model, use the pp. pro (for Pas- cal) or he. pro (for C) file contained in that modells subdirec- tory to set the model. Of course, you may need a copy of both compi lers for Concurrent, depending upon which routines you are recompi ling.

Alternatively you may choose to replace them altogether with your own routines. At least by looking at the source you can see how the implementation was done and what the pro- grams must do for embedded appl ications.

v.04.15.86 ~ 1983-86 HetaWare Incorporated

Installation Guide page 15

·12.D Solutions to Potential Problems

Here are a few problems that you might encounter .. and what to do with them.

1. The compi ler complains that it is "Out of memory.".

If you have limited main memory on your machine, you must set the number of tree pages down to a sma II number .. such as 50 or even less. For example:

he program.p -tpages 50

You can also "configure" the compiler to have 50 tree pages and to assume limited memory; see Configuring

the Compi/erabove. .

Note that running with the -ansi option requires about 15K more memory.

2. You have successfully campi led a program .. but the I ink- er complains that one of the symbols SHALL?, HEDIUH? ..

COMPACT?, BIG?, or LARGE? is undefined.

This means that you are linking with the wrong library.

Programs compiled for a particular memory model must be I inked with the I ibrary for that model. See the Programmer IS Guide for more information on mem- ory models.

3. You have successfully compiled a program, but the link- er complains that the symbol _mw87 _used is undefined.

This means you have object fi les that contain 8087 or 80287 floating- point instructions, but you are I inking with an emulation library. Programs compiled into -87 floating-point instructions must be I inked with the co-processorlibrary for that model. See, the Program- merls Guide for more information on libraries.

4. You have typed he

v.04.15.86 ~ 1983-86 MetaWare Incorporated

to start up the campi ler and it has printed a banner but is doing nothing else.

It is waiting for the program to be entered from the terminal. When no parameters are given to the com- piler, it assumes that the input program is coming from the standard input, which in this case is the console.

You can type the program in directly, terminated by a . control- Z to signify end-of-fi Ie (and end-af-program).

v.04.15.86 ·@"1983-86 HetaWare Incorporated

Acknowledgments

The authors of these manuals and designers of Professional Pascal would like to thank Victor Technologies Incorporated for the initial impetus to actually implement our own Pascal. We especially thank Marq Elliott for his enthusiastic support, along with Tony Jeans and Bobby Taylor.

We thank three enthusiastic people at "beta" test sites for their valuable feedback on the manuals, the language, and the compiler. They are John Ciccarelli of Zoran Corporation, Wes Embry of Daisy Systems Corporation, and Reed Kotler of General Transformation Corporation.

Thanks also to Professor Bill McKeeman of the Wang Institute of Graduate Studies for his valuable feedback and to one of our marketers, the people at Microtec Research Incorporated, especially Craig Franklin, for their insights into the needs of typical users, for many suggestions for technical improvements, and for the evaluation of the language which they supported by Gene Powers. And thanks for your insights,

Gene. .

Most of all we acknowledge that we are not self-made, but God-made. And we thank God for building into us the talents that made it possible for us to create Professional Pascal.

Ad majorem Dei gloriam (A.M.D.G.).

v.09.1S.8S • 198'-8' Metaware Incorporated

Meta Ware ™ High C ™

v.09.1S.85

Installation Guide

© Copyright 1983-85 MetaWare Incorporated

Santa Cruz, CA 95060

o 1983-85 Metaware Incorporated