Liren Large Software Subsidy 7

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 7 / 07.iso / c / c185 / 1.ddi / READ.ME < prev

Wrap

Text File | 1989-09-12 | 84.1 KB | 2,227 lines

C-scape 3.1 READ ME Copyright (c) 1989, Oakland Group, Inc. Table of Contents 1: INTRODUCTION 1 2: WHAT YOU SHOULD READ 1 3: DISK CONTENTS 1 4: INSTALLATION 2 4.1: Quick And Dirty (First Time Installation) 2 4.2: Quick And Dirty (Upgrade) 2 4.3: Less Quick And Dirty (First Time Installation) 2 4.4: Less Quick And Dirty (Upgrade) 3 4.5: Notes On Source Code 3 5: COMPILING AND LINKING 4 5.1: General Information 4 5.2: Microsoft C 5.0 And 5.1 4 5.2.1: Microsoft C 5.0 And 5.1 Command Lines 4 5.2.2: Microsoft Quick C Command Lines 4 5.2.3: Microsoft Quick C Integrated Environment 5 5.2.3.1: Microsoft Quick C 2.0 Integrated Environment 5 5.2.3.2: Microsoft Quick C 1.0 Integrated Environment 5 5.2.4: Microsoft C 5.0 And 5.1 Common Compile And Link Errors 6 5.3: Turbo C 2.0 7 5.3.1: Turbo C 2.0 Command Line 7 5.3.2: Turbo C Integrated Environment 7 5.4: Turbo C Versions Prior To 2.0 8 6: UPDATES TO THE MANUAL 8 6.1: Updates To The 3.1 Manual 8 6.2: Updates To The 3.0 Manual 9 6.3: Updates To The 3.0 Manual Addendum 9 7: ERRATA FOR THE MANUAL 9 7.1: Errata For The 3.1 Manual 9 7.2: Errata For The 3.0 Manual 12 7.3: Errata For The 3.0 Manual Addendum 13 8: SAMPLE PROGRAMS 14 8.1: cscape 14 8.2: demofm 14 8.3: demomous 14 8.4: demofram 14 8.5: demoslug 14 8.6: demosled 14 8.7: demograf 14 8.8: demopcx 14 8.9: demoflod 14 8.10: demofsav 14 8.11: demohelp 15 8.12: demotty.c 15 9: WHAT'S BEEN FIXED 15 10: WHAT'S NEW IN THIS RELEASE 15 11: WHAT'S IMPROVED IN THIS RELEASE 16 12: NEW FUNCTIONS 16 13: NEW SLED FUNCTIONS 17 14: CMAP AND PMAP WINDOWS 18 15: OAKLAND DEBUGGING AID 21 16: A FEW OAKLAND CODE CONVENTIONS 22 16.1: OGLOBAL 22 16.2: OEXTERN 22 16.3: FNULL 22 17: RECOMPILING THE SOURCE CODE 23 17.1: General 23 17.2: Microsoft C Make 24 17.2.1: OWL 24 17.2.2: CSCAPE 24 17.3: Turbo-C 2.0 Make 24 17.3.1: OWL 24 17.3.2: CSCAPE 25 17.4: Opus Make 5.0 25 18: OS/2 25 19: OAKLAND TECHNICAL SUPPORT 26 20: WHAT IS COMING FROM OAKLAND 26 _______________________________________________________________________________ 1: INTRODUCTION Thank you for purchasing C-scape 3.1! Please complete and return your registration card so we can send you the library source. The registration card also serves to allow us to send you information of new versions and features. We automatically notify registered users of new versions and new products. New C-scape users and those current users who are upgrading from 2.0 should have received the following: 2 disks (an additional source disk is sent upon receipt of registration) 2 manuals (the C-scape Manual and the C-scape Function Reference) Current users who are upgrading from version 3.0 or 3.0a should have received the following: 2 disks (an additional source disk is sent upon receipt of registration) 1 addendum (the C-scape Manual Addendum) _______________________________________________________________________________ 2: WHAT YOU SHOULD READ THIS FILE DOCUMENT CONTAINS INFORMATION ESSENTIAL TO USING C-SCAPE. AT A MINIMUM, YOU SHOULD READ THE FOLLOWING SECTIONS OF THIS DOCUMENT: DISK CONTENTS INSTALLATION COMPILING AND LINKING MANUAL UPDATES MANUAL ERRATA In addition we recommend that you read the following additional sections: OAKLAND DEBUGGING AID OAKLAND CODE CONVENTIONS If you are upgrading to C-scape 3.1 from 3.0 or 3.0a, you should read the following additional sections of this document. WHAT'S BEEN FIXED WHAT'S NEW IN THIS RELEASE WHAT'S IMPROVED IN THIS RELEASE NEW FUNCTIONS (SLEDS) NEW FUNCTIONS (PCX FILE SUPPORT) OAKLAND DEBUGGING AID _______________________________________________________________________________ 3: DISK CONTENTS The distribution disks are high-density DOS format floppies. All files on the C-scape distribution disks with the .EXE filename extension are self-extracting archives. In the following list, disk numbers followed with an M refer to the Microsoft version, T refers to Turbo-C version. TDisk READ.ME This file 1 CSHEAD.EXE C-scape header files OWLHEAD.EXE Oakland Windowing Library (OWL) header files FUNCS.EXE Source for field functions EXAMPLE.EXE C-scape examples and Demos INSTALL.BAT Installation batch file T2LOWL.EXE Large memory model Turbo-C OWL library T2LCSCAP.EXE Large memory model Turbo-C C-scape library T2MOWL.EXE Medium memory model Turbo-C OWL library T2MCSCAP.EXE Medium memory model Turbo-C C-scape library INSTALL.BAT Installation batch file MDisk READ.ME This file 1 CSHEAD.EXE C-scape header files OWLHEAD.EXE Oakland Windowing Library (OWL) header files FUNCS.EXE Source for field functions EXAMPLE.EXE C-scape examples and Demos M1LOWL.EXE Large memory model Microsoft OWL library M1LCSCAP.EXE Large memory model Microsoft C-scape library M1MOWL.EXE Medium memory model Microsoft OWL library M1MCSCAP.EXE Medium memory model Microsoft C-scape library INSTALL.BAT Installation batch file Source CSSRC.EXE C-scape source code OWLSRC.EXE OWL source code Source is shipped separately upon receipt of registration _______________________________________________________________________________ 4: INSTALLATION 4.1: Quick And Dirty (First Time Installation) The quick and dirty installation of C-scape is just that, very quick. All that is needed is to place the first floppy in the appropriate disk drive, change to that disk drive and enter install D:. This will automatically create the C-scape directories and copy the files to those directories. As an example, to install C-scape just off the main directory of a C drive from the a: drive, do the following: place the floppy in drive a: and enter: >install c: and sit back and watch. This will need to be done with both C-scape diskettes. The directories created are as follows( This assumes that the installation was done off the root directory ). \cscape\lib library (.lib) files \cscape\include header (.h) files \cscape\source field function source (.c) files \cscape\examples C-scape example and Demo programs 4.2: Quick And Dirty (Upgrade) NOTE The quick and dirty installation of a C-scape upgrade is identical to the above except that you must ensure that there are no old C-scape headers or libs in the directories. NOTE Be sure to recompile ALL of your application source using the new headers and libraries. Failure to do so will produce some very strange unresolved external errors in the link. 4.3: Less Quick And Dirty (First Time Installation) To install C-scape we suggest that you create a C-scape directory on your hard disk with the following sub-directories: \cscape\lib library (.lib) files \cscape\include header (.h) files \cscape\source field function source (.c) files \cscape\examples C-scape example programs All files on the C-scape distribution disks with the .EXE filename extension are self-extracting archives. To decompress the archive simply enter the name of the archive followed by the drive and directory in which you wish to place the files to be extracted. For example: FUNCS C:\CSCAPE\SOURCE would extract the C-scape field function source from FUNCS.EXE and place them in the \CSCAPE\SOURCE directory on drive C:. In order to verify that the archive has not been corrupted ( a fairly unlikely event ) you may wish to use the -t switch so that the archive will perform a test of its own integrity. CSHEAD -t C-scape 3.1 actually consists of two libraries. There is the C-scape library and the Oakland Windowing Library (OWL). And, for each of the two libraries there is a large memory model and a medium memory model version of the library. There are also two groups of associated header files: C-scape headers and OWL headers. In accordance with the above directory structure, a complete installation would involve entering the following: T2MCSCAP C:\CSCAPE\LIB T2LCSCAP C:\CSCAPE\LIB T2MOWL C:\CSCAPE\LIB T2LOWL C:\CSCAPE\LIB CSHEAD C:\CSCAPE\INCLUDE OWLHEAD C:\CSCAPE\INCLUDE * CSSRC C:\CSCAPE\SOURCE * OWLSRC C:\CSCAPE\SOURCE * NOTE that the source diskette that contains these two archives is sent to you upon receipt of the registration card The above would install C-scape 3.1 libraries, header files and source code for use with the Borland Turbo-C 2.0 compiler. If you have the Microsoft C 5.1 compiler then the library medium and large memory model archive names would begin with M1M and M1L instead of T2M and T2L. You must install ALL header files for both C-scape and OWL headers are necessary to compiling a C-scape application program. Likewise, you must link with BOTH the C-scape and OWL libraries before running your program. You do not need the files contained in FUNCS.EXE or EXAMPLE.EXE to use C-scape but you may find them useful. 4.4: Less Quick And Dirty (Upgrade) NOTE The installation of a C-scape upgrade is identical to the above except that you must ensure that there are no old C-scape headers or libs in the directories. NOTE Be sure to recompile ALL of your application source using the new headers and libraries. Failure to do so will produce some very strange unresolved external errors in the link. 4.5: Notes On Source Code The diskettes you have been shipped include source code for the field functions only. These are the functions documented in Appendix B of the C-scape Function Reference. These functions are those that programmers find it necessary to modify at one time or another. The source for the rest of the functions in the libraries is sent by Oakland upon receipt of your registration card. Note that sending in your registration card signals the end of your 30 day trial period and should not be done until you have decided to keep the C-scape package. _______________________________________________________________________________ 5: COMPILING AND LINKING 5.1: General Information The first three letters of the C-cscape library files indicate the compiler and memory model of the library. M1 for Microsoft C 5.1, T2 for Turbo C 2.0). Only large and medium memory models of the libraries have been provided. A small model library is not included because the base size of an executable with C-scape code exceeds the amount of code allowable in the code segment of a small model program. You must link with BOTH the OWL and C-scape libraries. You must be sure to use the appropriate memory models. All C-scape's header files must be placed where the compiler can find them. Creating a sub-directory \cscape\include is recommended. To tell the compiler the location of the C-scape header files, use either the environment variable INCLUDE or a compiler flag. Consult your compiler reference for more information. Please do not call us with questions about compilers. Call the compiler vendor. 5.2: Microsoft C 5.0 And 5.1 5.2.1: Microsoft C 5.0 And 5.1 Command Lines Medium model compile and link lines: cl /c /DM5 /AM /I\cscape\include myprog.c link /SE:500 cscape, cscape, , \cscape\lib\m1mowl \cscape\lib\m1mcscap; Large model compile and link lines: cl /c /DM5 /AL /I\cscape\include myprog.c link /SE:500 cscape, cscape, , \cscape\lib\m1lowl \cscape\lib\m1lcscap; You must define M5 (not M1) with the /D flag. This is because some of the Oakland header files are compiler specific. If you do not define this symbol you'll get the Microsoft C message "error C2061: syntax error: identifier 'byte'". Note also that your .c source file must have the STDIO.H or STDLIB.H file included before the CSCAPE.H file in order for the compiler to use certain implementation specific symbols. If this is not done you will recieve a message telling you that SIZE_T is undefined. You may have to alter the use of /SE: to increase the number of link segments. The above specification of /SE:500 is only a suggestion. It should work with most compilations of application programs. If you get the Microsoft error message "error L1049: too many segments" then you need to increase the number of segments specified with the /SE:. Note that if the /SE: switch is not included then the Microsoft Linker defaults to 128. Do not the packed structures (/Zp) option when compiling. We have compiled C-scape library objects with the default Microsoft compiler setting. Use of the /Zp option to force any other alignment will result in incompatibility. If you need to use packed structures - because you are linking with another library that uses them, for example - you must recompile the entire C-scape and OWL libraries with the same structure packing as your application. See the section of the READ.ME file RECOMPILING THE SOURCE CODE. 5.2.2: Microsoft Quick C Command Lines Please refer to the previous section discussing the command lines for the Microsoft C 5.0 and 5.1 Optimizing Compiler. While the Quick C compiler does not have all the options the 5.0 and 5.1 compilers offer the command lines specified above will work under both. 5.2.3: Microsoft Quick C Integrated Environment 5.2.3.1: Microsoft Quick C 2.0 Integrated Environment To use the Quick C 2.0 integrated environment follow these instructions: 1) Select "Set Program List" from the "Make" menu. a) Type in the name of the .mak file you wish to create in the "File Name" field - e.g., "myprog.mak". Answer "Yes" when you are asked if you wish to create a file "myprog.mak". b) Type the name of your C program in the "File Name" field. Example: "myprog.c". Press ENTER and the file name will appear in the "Program List" box. c) Type in the path and name of the C-scape medium or larger model library in the "File Name" field - e.g., "\cscape\lib\m1lcscap.lib". Press ENTER and "m1lcscap.lib will appear in the "Program List" box. d) Type in the path and name of the OWL large or medium model library in the "File Name" field - e.g., "\cscape\lib\m1lowl.lib". Press ENTER and "m1lowl.lib" will appear in the Program List box. e) Your list should now look like this: myprog.c m1lcscap.lib m1lowl.lib f) Select the "Save List" option. 2) Select the "Make" option from the "Options" menu. a) Select "Compiler Flags". Set the memory model for the compilation and, in the "Defines" field, enter "M5". Select "Ok". b) From the Build Flags screen, select "Ok". 3) Select the "Environment" option from the "Options" menu. a) In the "Include files directories" field, type the directory path of your header files - e.g., ".\, \qc\include\, \cscape\include\". b) In the "Library file directories" field, type the directory path of the library files - e.g., "., \qc\lib\, \cscape\lib\". c) Select "Ok". 4) Select "Exit" from the "File" menu and reply "Yes" when your are asked if you wish to save the changes to your program make file. 5) Re-enter Quick C and edit your program make file. To the macro definition of "LFLAGS_D" append "/SE:" (follow the ":" with the number of segments you want the linker to use). Save your make file. (Note: if we had edited the make file, and saved it before exiting in step 4, the "/SE:" change would have been overridden by Quick C's update). 6) You may now build you program by selecting "Build" from the "Make" menu. 7) Consult the Quick C Programmer's Guide for more information about using the integrated environment. 5.2.3.2: Microsoft Quick C 1.0 Integrated Environment To use the Quick C 1.0 integrated environment follow these instructions: 1) Select "Set Program List..." from the "File" menu. a) Type in the name of the .mak file you wish to create in the "File Name" field - e.g., "myprog.mak". Answer "Yes" when you are asked if you wish to create a file "myprog.mak". b) Type the name of your C program in the "File Name" field. Example: "myprog.c". Press ENTER and the file name will appear in the "Program List" box. c) Type in the path and name of the C-scape medium model library in the "File Name" field - e.g., "\cscape\lib\m1mcscap.lib". Press ENTER and "m1mcscap.lib will appear in the "Program List" box. d) Type in the path and name of the OWL medium model library in the "File Name" field - e.g., "\cscape\lib\m1mowl.lib". Press ENTER and "m1mowl.lib" will appear in the Program List box. e) PLEASE NOTE THAT THE QUICK-C 1.0 INTEGRATED ENVIRONMENT ONLY SUPPORTS THE MEDIUM MEMORY MODEL. f) Your list should now look like this: myprog.c m1mcscap.lib m1mowl.lib g) Select the "Save" option. 3) We need to edit the makefile. a) Go to the "File" menu and "Open" the your program's make file - e.g., "myprog.mak". b) You note that at the end of the make file there is a reference to "$(LDFLAGS)" on the link line. Define this at the top of the make file so that the "/SE:" switch is used. This switch sets the number of segments that the linker can use - the default is 128 (too low for C-scape library usage) and the ceiling is 3072. 400 or 500 should be sufficient for most programs so, define "LDFLAGS" - e.g., "LDFLAGS=/SE:500". c) Save the changes you've made to your makefile. d) Exit Quick-C. You must do this so that you can pull in the updated make file for use. Had you simply re-opened your program source and tried to compile it would not know about the "LDFLAGS" definition yet. 4) Re-start Quick-C and open your program source file. 5) Select the "Compile..." Option from the "Run" menu. a) In the "Include:" field, type the directory path of your header files - e.g., "., \owl\include\, \cscape\include\". b) In the "Define:" field, enter "M5". c) Go ahead and select the compilation action - i.e, "Build Program", "Compile", or "Rebuild All". If you select "Cancel" the "Include:" and "Define:" field contents are not going to be added to your make and you'll have to re-edit these fields should you exit and come back later. 6) Select "Exit" from the "File" menu and reply "Yes" when your are asked if you wish to save the changes to your program make file. 7) Consult the Quick C Programmer's Guide for more information about using the integrated environment. 5.2.4: Microsoft C 5.0 And 5.1 Common Compile And Link Errors C1027: DGROUP data allocation exceeds 64K Your program is running out of static data space. Experiment with the /Gt compile flag. This tells the compiler not to place all static data (such as menu_Printf format strings) within the same data segment. See the Microsoft User's Guide, p.247, for more information. C2061: syntax error: identifier "byte" You must define M5 with the /D flag. This is because some of the Oakland header files are compiler specific. C2061: syntax error: identifier "SIZE T" In your source code place the #include <stdio.h> or #include <stdlib.h> statement before the #include "cscape.h" statement. L1049: too many segments Use the /SE: option to increase the number of link segments (128 is the Microsoft LINK default value). L1101: invalid object module It can be caused by having an older version of the LINK command somewhere on your DOS path. The other possibility is that the library or one of the code modules has been corrupted. L2003: intersegment self-relative fixup This can be caused by compiler and library memory model mismatch. You've probably compiled under the medium model C library and are linking to a the large model C-scape libraries; or, compile under large model and are linking to the C-scape medium libraries. Note that there are no small model C-scape libraries. 5.3: Turbo C 2.0 5.3.1: Turbo C 2.0 Command Line Medium model: tcc -c -mm -I\cscape\include myprog tlink \tc\lib\c0m myprog, myprog, , \tc\lib\emu \tc\lib\mathm \tc\lib\cm \cscape\lib\t2mowl \cscape\lib\t2mcscap Large model: tcc -c -ml -I\cscape\include myprog tlink \tc\lib\c0l myprog, myprog, , \tc\lib\emu \tc\lib\mathl \tc\lib\cl \cscape\lib\t2lowl.lib \cscape\lib\t2lcscap Do not use the word alignment (-a) option when compiling. We have compiled C-scape library objects with the default Turbo C setting. Use of the -a option to force any other alignment will result in incompatibility. If you need to use word alignment - because you are linking with another library that uses them, for example - you must recompile the entire C-scape and OWL libraries with the same alignment as your application. 5.3.2: Turbo C Integrated Environment To use the Turbo C integrated environment follow these instructions: 1) Select Options/Environment from the main menu. Select Directories. a) Make sure the include directories option lists the path to the directory containing the C-scape include (.h) files. Example: \tc\include;\cscape\include; b) Make sure the libraries directories option list the path to the directories containing the C-scape library (.lib) files. Example: \tc\lib;\cscape\lib; 3) Create a project (.prj) file by opening a new file (consult the Turbo-C manual for more information about project files). 4) In the project file, list the names of the .C file(s) you are working on. (There should be one file name per line.) Next, add the C-scape library with which you wish to link (make sure you choose the correct memory model). Example: -------- sample.c t2lowl.lib t2lcscap.lib 5) Save the project file. 6) Use the Project menu to set the project name to the file just created. 7) Now use the compile menu to compile (or build) your program. 8) Consult the Turbo C Manual for more information about the integrated environment. 5.4: Turbo C Versions Prior To 2.0 The objects created by the compiler of versions of Turbo C prior to 2.0 are incompatible with those of Turbo C 2.0. C-scape is compiled under Turbo C 2.0. If you are using an older version of Turbo C you must recompile the C-scape source. When recompiling for Turbo-C C 1.5 you will have to place a -DTC on the command line because the C-scape and OWL code depends on a pre-defined macro define __TURBO_C__ not found in the 1.5 compiler. _______________________________________________________________________________ 6: UPDATES TO THE MANUAL 6.1: Updates To The 3.1 Manual - Please see the New Sled Functions section of this document. - There is no built in mouse support for the slug menuing system. - Screen files now require that you include object class functions in the fsyminit_struct symbol table. If you use seds, sleds and user functions then you must add the following entries to your symbol table: { FSYM_CLASS }, { "sedwin_Class", (VOID_FPTR)sedwin_Class, NULL }, { "sledwin_Class, (VOID_FPTR)sledwin_Class, NULL }. { "ufunc_Class", (VOID_FPTR)ufunc_Class, NULL }, Always include the entry of the delimiter "{ FSYM_CLASS }". If you are using seds you need the sedwin_Class entry. If you are using sleds then include the sledwin_Class entry. If you are using slugs or framers include the ufunc_Class entry. If you purchased Look & Feel, Look & Feel will automatically generate the fsyminit_struct symbol table for your screens and include the above classes as appropriate. - For code portability you should use FNULL as the second member of a fsysminit_struct, instead of NULL, if you need to specify a null function pointer. A null third member, the data pointer, may be specified with NULL. This is to insure compatibility with compilers that differentiate between data and function pointers. - ted_funcs use the sed generic data pointer for the cut buffer. If the pointer is null at the time the cut buffer is to be first used then ted_fkey allocates the buffer and sets the sed data pointer to point to it. This would be the case if you had not explicitly set the sed's data pointer by calling sed_SetData. If the pointer is not null, but points to your data, ted_fkey assumes the buffer has been allocated and will use that pointer as if it indicated the cut buffer. If you wish to alter this behavior then change ted_fkey in FNTED.C. - The field functions char_funcs and hex_funcs do not make use of validation. - The valid_String() command code prefix {n}, for limiting the validation to the first n characters of the string, is valid for values of 0 through 9. A new command {s}, tells string validation to ignore ALL whitespace when making it's comparisons. Example: "{s}Hello" would validate "H e ll o ". The following functions no longer exist: - sed_Clear 6.2: Updates To The 3.0 Manual - Please see the C-scape Manual Addendum. - Please see the New sled functions section of this document. - The integer values in the slug and framer menu definition structure should be positive and NON-ZERO (i.e., > 0). - There is no built in mouse support for the slug menuing system. - The border bd_exp no longer exists. You can get the same results by using: sed_SetBorder(sed, bd_1); sed_SetExplode(sed, exp_std); - Embedded seds must use spc_Embed to operate properly. - The inner workings of sleds differ from their description in the manual (section 10.3.1). Namely, spc_Sled does all of the work of maintaining the sled. The parent sed's field function, sled_funcs, does no sled work. In fact sled_funcs has been defined to be bob_funcs. Because of these changes, sleds can also operate without being embedded. After opening the sled with sled_Open, simply call sled_Repaint and sled_Go. Refer to the source file spcsled.c for more information. - The field functions char_funcs and hex_funcs do not make use of validation. - Field formatting has a new command, c. This command removes ALL whitespace form the field's record. - the valid_String() command code prefix {n}, for limiting the validation to the first n characters of the string, is valid for values of 0 through 9. A new command {s}, tells string validation to ignore ALL whitespace when making it's comparisons. Example: "{s}Hello" would validate "H e ll o ". The following functions no longer exist: - sed_Clear 6.3: Updates To The 3.0 Manual Addendum - Screen files now require that you include object class functions in the fsyminit_struct symbol table. You must add the following entries to your symbol table: { FSYM_CLASS }, { "sedwin_Class", (VOID_FPTR)sedwin_Class, NULL }, { "sledwin_Class, (VOID_FPTR)sledwin_Class, NULL }. { "ufunc_Class", (VOID_FPTR)ufunc_Class, NULL }, Always include the entry of the delimiter "{ FSYM_CLASS }". If you are using seds you need the sedwin_Class entry. If you are using sleds then include the sledwin_Class entry. If you are using slugs or framers include the ufunc_Class entry. If you purchased Look & Feel, Look & Feel will automatically generate the fsyminit_struct symbol table for your screens and include the above classes as appropriate. - For code portability you should use FNULL as the second member of a fsysminit_struct, instead of NULL, if you need to specify a null function pointer. A null third member, the data pointer, may be specified with NULL. This is to insure compatibility with compilers that differentiate between data and function pointers. - There is yet another border feature that you can enable with the sed_SetBorderFeature call: BD_TOP. Enabling this allows you to bring the window to the foreground by clicking the mouse on the border. _______________________________________________________________________________ 7: ERRATA FOR THE MANUAL 7.1: Errata For The 3.1 Manual The following are mistakes in the C-scape manual and reference. 45 The code fragment with a reference to menu_Print lacks quotes. The line in question should read: menu_Printf(menu, "@f[%s], NULL, &menu_funcs, p); 59 In section 5.13, Auxiliary Functions, the penultimate sentence of the 2nd paragraph should read: C-scape automatically ... and after each field's fexit function. Not: C-scape automatically .. and before each field's fenter function. 63 The code example at the top of the page has a line which reads: sed_MarkField(sed, fldno, reg, sel); The line should be: sed_MarkField(sed, fldno, sel, sel); 184-185 The example code MyTed_fkey requires #include <ctype.h> for the call to the call to isprint in the default case of the switch statement. 158 The spc_Embed has a null case BOB_UP that falls thru to the UP case; BOB_DOWN falls thru to DOWN. The cases for LEFT and RIGHT should be cases for SHFT_TAB and TAB, respectively. Also the null cases BOB_LEFT and BOB_RIGHT fall thru to SHFT_TAB and TAB, respectively. See SPCEMBED.C 160 The bob_fkey code listed before the switch is printed as: { bob_type bob; bob = sed_GetFieldBob(osed, sed_GetFieldNo(osed)); It should read: { bob_type bob; int ret, fieldno; fieldno = sed_GetFieldNo(sed); if ((bob = sed_GetFieldBob(osed, fieldno)) == FNULL) { /* Error: no bob attached to the field */ sed_SetBaton(osed, BOB_QUIT); sed_ToggleExit(osed); return; } ret = bob_Go(bob); /* See if special function is interested in BOB_ code */ if (sed_DoSpecial(osed, ret)) return; 163 The first sentence beneath the diagram should read: If you passed sed three to sed_GetAncestor it would return sed two. 176, The return value of MyTed_fexit should be: 190 return(std_fexit(sed)); 180 The reference in the example MyTed_sexit to ted_RewindTB should be a reference to sed_RewindTB. 235 bd_bar does not support a title. A-17 disp_GetMapEntry is described incorrectly. It should read: SYNOPSIS VOID disp_GetMapEntry(index, bg, fg); byte index; /* index into the attribute map */ opixal *bg; /* pointer to background color */ opixval*fg; /* pointer to foreground color */ EXAMPLE opixval fore, back; disp_GetMapEntry(0x07, &back, &fore); A-21 cmwin_Class description mentions disp_Open, it should mention disp_Init. A-24 The arguments for disp_SetMapEntry are: byte index; opixval back; opixval fore; A-65 kb_Idle() is a VOID (it has no return value). A-67 The line sed_SetPosition(sed, disp_GetHeight() - 1, 0); should be sed_SetPosition(timesed, disp_GetHeight() - 1, 0); A-89 - You need to #include <pcmode.h> when using any of the pc_ A-92 functions. A-297 The synopis to sled_SetColVar is missing the begining line: #include <sled.h> A-396 The synopsis should read valid_String(string, vstr), not (num, vstr). A-380 The function name in the synopsis should be tm_DayOfWeek, not tm_FirstDay. B-6 char_funcs does not support validation. B-10 date_funcs require the inclusion of the your compiler's TIME.H file. B-17 hex_funcs does not support validation. B-39 time_funcs require the inclusion of the your compiler's TIME.H file. 7.2: Errata For The 3.0 Manual The following are mistakes in the C-scape manual and reference. 3 The current release does not include an ANSI terminal driver 40 The code fragment with a reference to menu_Print lacks quotes. The line in question should read: menu_Printf(menu, "@f[%s], NULL, &menu_funcs, p); 90 spc_Embed should refer to section 10.1.1 116 (5) the integer value used in the slug definition structure should be a positive, NON-ZERO value. 117 The type cast in the call to slug_Go should be a (VOID *), not a (char *). 117 The data type of "sdata" in the example user function should be (VOID *), not (char *). 118 (3) the integer value used in the frame definition structure should be a positive, NON-ZERO value. 128 spc_Embed uses TABs not arrows. 142-143 In the example code pertaining to creating a sed with a ted field there should be a calls to explicitly set the sed size in order that the ted area be non-zero. Use sed_SetHeight(sed) and sed_SetWidth(sed) before the sed_Repaint(sed) call; 144, The return value of MyTed_fexit should be: 156 return(std_fexit(sed)); 147 The reference in the example MyTed_sexit to ted_RewindTB should be a reference to sed_RewindTB. 151-152 The example code MyTed_fkey requires #include <ctype.h> for the call to the call to isprint in the default case of the switch statement. 157 The example should read: case DEL: if (ted_GetMark(sed) == TED_NOMARK) { /* Delete the marked region (if there is one) */ ted_BlockDelete(sed); } else { /* Delete a character */ ted_DeleteChar(sed); } break; 159 The example should read: case ALT_S: /* ... */ if (ted_Search(sed, search, TED_FORWARD | TED_AFTER)) { sed_BorderPrompt(sed, FNULL); } 168 bd_bar does not support a title. A-15 disp_GetMapEntry is described incorrectly. It should read: SYNOPSIS VOID disp_GetMapEntry(index, bg, fg); byte index; /* index into the attribute map */ opixal *bg; /* pointer to background color */ opixval*fg; /* pointer to foreground color */ EXAMPLE opixval fore, back; disp_GetMapEntry(0x07, &back, &fore); A-19 cmwin_Class description mentions disp_Open, it should mention disp_Init. A-21 The arguments for disp_SetMapEntry are: byte index; opixval back; opixval fore; A-61 kb_Idle() is a VOID (it has no return value). A-63 The line sed_SetPosition(sed, disp_GetHeight() - 1, 0); should be sed_SetPosition(timesed, disp_GetHeight() - 1, 0); A-85 - You need to #include <pcmode.h> when using any of the pc_ A-88 functions. A-103 sed_Clear no longer exists. A-376 The synopsis should read valid_String(string, vstr), not (num, vstr). A-360 The function name in the synopsis should be tm_DayOfWeek, not tm_FirstDay. B-7 char_funcs does not support validation. B-11 date_funcs require the inclusion of the your compiler's TIME.H file. B-17 hex_funcs does not support validation. B-39 time_funcs require the inclusion of the your compiler's TIME.H file. 7.3: Errata For The 3.0 Manual Addendum 7 The code example at the top of the page has a line which reads: sed_MarkField(sed, fldno, reg, sel); The line should be: sed_MarkField(sed, fldno, sel, sel); _______________________________________________________________________________ 8: SAMPLE PROGRAMS The following programs are included on your distribution disk to demonstrate the use of various parts of C-scape. They are archived in the file EXAMPLE.EXE. Compile them following the instructions listed in section 4, above. It is hoped that these programs will enable you to better learn C-scape; that you tinker with them; and, that you use them as a code source from which you can cut and paste to your own C-scape application. 8.1: cscape CSCAPE.C is a simple data entry screen. It is the hello world of the C-scape world. 8.2: demofm DEMOFM.C is a sample program that demonstrates one of the recommended ways of handling a framer menu that is driven by both the mouse and the keyboard. Also demostrates the detection of mouse double-clicks and button1-, 2-, or 3-down events. 8.3: demomous DEMOMOUS.C demonstrates mouse use with C-scape. If you have not installed a mouse driver, demomous will display a message to that effect. 8.4: demofram DEMOFRAM.C demonstrates the framer menuing system. Press any key to get started. Press Escape from the top menu to leave. 8.5: demoslug DEMOSLUG.C demonstrates the slug menuing system. A popup window will ask you if you wish to create a horizontal or vertical menuing system. Press Escape from the top-most menu to leave. 8.6: demosled DEMOSLED.C demonstrates how to create a screen from several smaller screens. It includes a scrolling, resizing list (sled), a notepad text editor (ted), and mouse support. It stores and retrieves data from the ASCII file DEMOSLED.DAT. Press Escape to leave the program. 8.7: demograf DEMOGRAF.C (Microsoft and Turbo Only) demonstrates how C-scape screens can be placed on top of graphics images. It uses either the Microsoft or Turbo graphics libraries to draw the graphic images. You must run demograf on a system capable of supporting graphics. Note: on some CGA systems you may have to run the DOS-supplied utility GRAFTABL.COM to load the graphics character set. The Turbo version of demograf looks for the Borland .BGI graphics driver files in the \TC directory and the directory in which you run it. You can change this search path by changing the constant BGI_PATH in demograf.c 8.8: demopcx DEMOPCX.C demostrates loading and displaying graphics images stored on disk using the PCX file format. 8.9: demoflod DEMOFLOD.C demonstrates loading a screen file. 8.10: demofsav DEMOFSAV.C demostrates saving a screen file. 8.11: demohelp DEMOHELP.C is data entry screen that uses the C-scape help system to provide context sensitive help. DEMOHELP.HLP is the accompanying help text file. 8.12: demotty.c DEMOTTY.C is an example of using a character map window to display text in a tty-like fashion. _______________________________________________________________________________ 9: WHAT'S BEEN FIXED Please note that this is not a comprehensive list of the bugs we've fixed: - To correct an erroneous definition vid_DrawBox has changed from a macro to a function with appropriate parameters - def_ModeCurrent now allows the usage of 132 column and odd-sized displays. - The macros for frame_Lock and frame_Unlock now work properly. - pc_Mode7 can now be used when an EGA/VGA card is installed. - def_ModeText no longer pre-empts mode 7 in favor of mode 3 if the video mode is already mode 7 - the mode will remain 7. - Text display in graphics mode for IBM bios incompatible EGA/VGA cards is now supported. - The problem of intermittent lock-ups while using the mouse - due to the sending of messages to invalid windows - has been corrected. - The cursor-under pixmap is now correctly de-allocated in graphics mode. - menu_DeleteRows now correctly updates the menu row count. - pop_View now scrolls horizontally when lines wider than the width of the pop up are to be displayed. - The protection of virtual fields is now respected by inter-field-grid movement. - Problems moving out of scrolled virtual fields (bobbed seds) into the nesting sed have been corrected. - sed_GetTB now pays attention to length of the array passed to it so that it doesn't trash memory. - win_PutUnder now repaints in the case of a descending window. - Scroll lights now correctly reflect the scrollable status of the menu and are properly painted upon initial display - Sled displays now function properly in graphics mode. - ted_fkey now correctly handles block deletion. - sled column array (sarray) code now accomodates the case of the NULL array. - kb_Record catches every keystroke. - The window manager more fully enforces window clipping. - You can now open a sed with a fieldless menu, then menu_Printf, and _Go on the sed. - Worked around a Microsoft optimization bug that disabled Explode functions - Worked around a Microsoft optimization compilation bug in sed_GotoLastField. - You can now use sed_SetFieldBob to swap bobs. - You can now delete the current field and the currfield member of the sed structure will be reset. - kb_Record now works properly in teds and also records mouse events. _______________________________________________________________________________ 10: WHAT'S NEW IN THIS RELEASE These are new library features. - Screen file (sfile) support is now present. See Chapter 4 of the C-scape Addendum - Two new mouse handlers are available: sedmou_GreedyTrack and sedmou_GreedyClick. See Chapter 6 section 4 of the C-scape Addendum. - All library field functions are now sensitive to the sed's mousecode. See chapter 6 of the C-scape addendum. - Mouse handling capabilities are now features on all borders that can be enabled by means of sed_SetBorderFeature. See Chapter 6 and page A-16 of the C-scape Addendum. - Auxiliary functions now offer further field function customization capability. See Section 2.1 ,page A-7, and page A-13 of the C-scape Addendum. - Shadows are now part of all seds and can be made visible by sed_SetShadow. See Section 2.2, page A-21, and page A-22 of the C-scape Addendum. - You can now protect a column of a sled by either using the @fp command in the menu_Printf when you are defining a sled row; or, by calling the new function sled_ProtectCol. You can also protect a complete row of a sled by calling sled_ProtectRow. Note that you cannot specify protection on an individual column array entry basis. Please see the New Sled Functions section of this document. _______________________________________________________________________________ 11: WHAT'S IMPROVED IN THIS RELEASE These are some of the changes in C-scape 3.1 that have made it more efficient than 3.0: - menu_Printf has doubled in speed. - sled_SetColVar has been optimized to allow faster loading of the sled column array data. - The framer menuing system code has been revised and now incorporates a new, framer-specific mouse handler. - We've revamped our object mechanism. We now have less indirection and faster access to object instance data. And, seds are now windows (you no longer need to call sed_GetWin). - The OWL makes use of far and near pointers to increase efficiency. - General Display performance has been enhanced by more efficient painting of the screen. Specifically, we no longer paint text and fields separately. - Graphics display performance has been increased via direct ram screen writes in all modes. - Mouse handling has been clarified in the C-scape Manual Addendum. - The Oakland Windowing Library (OWL) now has pixmap functions and pcx file loading support. See the code example demopcx.c and the section in this readme on cmap and pmap windows. - Various and sundry changes and improvements have been made to the text handling code. _______________________________________________________________________________ 12: NEW FUNCTIONS - nowrite_funcs is a new field function: OGLOBAL field_funcs_struct nowrite_funcs = { stdNoCur_fenter, std_fexit, menu_fkey, string_senter, FNULL, VAR_STRING }; Treats the field as a menu choice. Supports grid movement among fields. Identical to menu_funcs except it uses string_senter. The text of the menu choice is determined by the contents of the field's string variable. Hence, it can be changed at run-time but the user may not edit the field. Upon exit the value of the field is not written back to the variable. - VOID disp_MapMono(mono) boolean mono; If mono is TRUE this maps colors for mono displays. Higher values are generalized as lighter than lower values, with the range being from 0-7 (8-F are moduloed, but bolding and blinking are preserved) therefore: fore < back (eg. 0x31) maps to 0x70 fore > back (eg. 0x25) maps to 0x07 - boolean disp_ReInit(dmode) dmode_fptr dmode; This routine installs a new display manager without closing down the window manager. It restore the mode that existed prior to disp_Init, changes the display mode, and repaint the display. You might use it to change from text mode to EGA 43 line mode and back: disp_Init(def_ModeText, FNULL); /* ... */ disp_ReInit(pc_ModeEGA43); /* ... */ disp_ReInit(def_ModeText); - bob_type ufunc_Open(ufunc, idata) ufunc_fptr ufunc; int idata; Creates a bob from a user function. Returns the bob if successful; NULL if not. The idata argument is a value that is passed to the user function upon invocation. - VOID *sed_GetCurrFieldData(sed, datano); sed_type sed; int datano; Similar to sed_GetFieldData except that it refers to the current field. _______________________________________________________________________________ 13: NEW SLED FUNCTIONS Please note that the header file SLEDWIN.H is now named SLED.H. If in your older code you had included BOBSLED.H for sled function use then you need make no changes - BOBSLED.H includes SLED.H. If you had explicitly used SLEDWIN.H then change the references to SLED.H. New routines have been added to the library to allow the protection and marking of row and columns in sleds (scrolling list editors). Protection and marking can be done independently of each other. Every attempt has been made to keep the sled functions as close as possible to their field counterparts. Any row or column can be protected using the appropriate function calls. Any changes to a row or column's protection status take effect the next time sled_Remap or sled_Repaint is called. Be careful that you do not attempt to protect the current row or column without moving out of it IMMEDIATELY afterward. Highlighting can be added to a sled by using the sled_Mark and sled_Attr routines. As with protection, changes take effect the next time sled_Remap is called. All rows and columns will be marked with the same regular and selected attributes. The attribute can be changed or inspected with sled_SetMarkAttr() and sled_GetMarkAttr(). The attributes are uninitialized, so you should call sled_SetMarkAttr() before you mark anything. Both protecting and marking can be done to any sled row or column, whether it is currently displayed or not. Return the current marking colors in regular and selected: OEXTERN VOID sled_GetMarkAttr(sed, regular, selected); sed_type sed; byte *regular; byte *selected; Set the sled's marking colors to regular and selected": OEXTERN VOID sled_SetMarkAttr(sed, regular, selected); sed_type sed; byte regular; byte selected; Use these routines to check the mark status of a row or column: boolean sled_IsMarkedRow(sed, row); sed_type sed; int row; boolean sled_IsMarkedCol(sed, col); sed_type sed; int col; These routines are for marking or unmarking and row or column in a sled: #define sled_MarkRow(sed, row); sed_type sed; int row; #define sled_UnMarkRow(sed, row); sed_type sed; int row; #define sled_MarkCol(sed, col); sed_type sed; int col; #define sled_UnMarkCol(sed, col); sed_type sed; int col; Use these routines to check the protect status of a row or column: boolean sled_IsProtectedRow(sed, row); sed_type sed; int row; boolean sled_IsProtectedCol(sed, col); sed_type sed; int col; Protect a row or col with these routines. Use "b" to pass TRUE or FALSE, indicating whether you want protection ON or OFF: VOID sled_ProtectRow(sed, row, b); sed_type sed; int row; boolean b; VOID sled_ProtectCol(sed, col, b); sed_type sed; int col; boolean b; _______________________________________________________________________________ 14: CMAP AND PMAP WINDOWS Seds are windows of the sedwin_Class. This is the most common C-scape window. There are there other window types available in the Oakland Windowing Library (OWL), however. We will take a brief look at two of these other windows - cmap and pmap windows. The forthcoming Oakland Advanced Programming Guide is the manual for the OWL and will provide a more in-depth look at window classes and objects. Here we present the rudiments. Character map (cmap) windows are of the cmwin_Class. Pixel map (pmap) windows are of the pmwin_Class. A character map is a two-dimensional array of characters and attributes; a pixel map is a bit map of video ram. You can create a window with win_Open. This routine creates an object of class winclass. The starting size and position (in display coordinates) is given by the ocbox cboxp. The window is placed in the unemployed window list. win_Open returns a pointer to the newly created window or NULL if unsuccessful. win_type win_Open(winclass, cboxp) class_fptr winclass; /* window class */ ocbox *cboxp; /* character box pointer */ You employ the window - painting it to the display - with win_Employ. boolean win_Employ(win) win_type win; /* the window to hire */ The window is fired - removing it from the display without destroying it - by calling with win_UnEmploy. boolean win_UnEmploy(win) win_type win; /* the window to fire */ You can destroy the window with win_Close. This removes the window from the display and deallocates its storage. VOID win_Close(win) win_type win; /* the window to destroy */ Some common additional functions enable you to attached a border, set the window position, and create a bob from the window so that you may nest it within a sed. boolean win_SetBorder(win, bd) win_type win; /* the window to which to attach */ class_fptr bd; /* the border */ viod win_SetPosition(win, row, col) win_type win; int row; /* display relative */ int col; bob_type win_CreateBob(win, depend) win_type win; int depend; /* depend is either BOB_DEPEND or BOB_INDEPENDENT a dependent bob will be painted and moved with its parent, while an independent bob must be painted separately */ You can display text in the cmap window by string the text in the cmap: char *cmwin_DrawString(win, row, col, string, attr, slen) win_type cmap; int row; int col; char *string; /* terminated string */ byte attr; int slen; /* Places string within window's cmap, clipping against cmap edges. Puts blanks from end of string to slen if string was too short. String is not read after a newline or a '\0'. Coords are relative to cmap. For blanks past the end of the string, attribute 'attr' is used. Returns pointer to char after last one put into cmap. */ You display images in a pmap window by opening, loading, and attaching the pmap. The only stock method provided by the OWL for loading a pmap from a PCX graphics format file. If you have images in other file formats there are many available utilities that will perform conversion to PCX format. The PCX file interface must be intialized by calling pmap_IoInit. VOID pmap_IoInit() You then create a color map capable of holding the range of colors that will be used to create the image by calling ocolmap_Open. This routine takes an index, firstpix, a the number of entries the color map will have, nentries. You get back a color map with the entries set to black; or, NULL if the range of the map was outside that of the default sytem map. ocolmap_type ocolmap_Open(firstpix, nentries) opixval firstpix;s unsigned nentries; You load a map from a PCX file that you've opened in "rb" (read binary) mode by calling pmap_Load. Note that when you open a pmap window with win_Open the pmap is not allocated. pmap_Load reads the .pcx file, initializing your colormap, allocates a pmap and loads it with the PCX file image. A pointer to the pmap is returned to you. pmap_type pmap_Load(fp, crange) FILE *fp; ocolmap_type crange; (If you wished to open a pmap - intending to load it yourself - you would call pmap_Open. This routine takes a pixel size specification and creates a pmap window. You are returned the window; or, NULL if it could not be opened.) pmap_type pmap_Open(pixwidth, pixheight) odim pixwidth; /* this type is currently defined */ odim pixheight; /* to be an unsigned int */ pmap_Load does not, itself, set the system palette up with your color map. To do this you make a separate call to disp_SetColMap once pmap_Load has initialized the color map from the PCX file. VOID disp_SetColMap(map) ocolmap_type map; After opening a pmap, either by pmap_Open or pmap_Load, you attach the pmap to the pmap window with pmwin_SetPmap. VOID pmwin_SetPmap(win, pmap) win_type win; pmap_type pmap; You initially paint the window to the display with win_Employ, as mentioned above. You can refresh the display of a cmap or a pmap window with win_Paint. win_Paint only paints the window. If you wish to paint the border, any window shadow, and the window then call bord_Paint. In general, win_ calls affect only the window; bord_ calls affect the window and border. If you have nested it by the used of win_CreateBob, call sed_Repaint. Alternating use of either of pmwin_SetPmap and win_Paint can produce an animated image. VOID win_Paint(win) win_type win; /* paint only the window */ VOID bord_Paint(win) win_type win; /* paint window,border,and shadow */ When you are done with the pmap you destroy it with pmap_Close. Make sure to nullify the pmap window's pointer to the map by calling pmwin_SetPmap(win, NULL). win_Close is used to destroy the pmap window itself but note, win_Close will not deallocate any associated pmap - you must call pmap_Close explicity. boolean pmap_Close(pmap) pmap_type; Please see the two sample programs in the EXAMPLE.EXE archive, DEMOTTY.C and DEMOPCX.C, for the details of the call sequences used to display cmap and pmap windows. You may consult the source for cmwin_Class and pmwin_Class in CMWIN.C and PMWIN.C, respectively. The headers CMWINOBJ.H and PMWINOBJ.H will give you some listing of function macros pertinent to these window classes. _______________________________________________________________________________ 15: OAKLAND DEBUGGING AID This is not an example program but rather a debugging aid. In order to aid in tracking down memory problems under DOS we have include a file OAKMEMOK.C in the example archive. The functions contained in OAKMEMOK.C replace the current memory handling routines used by C-scape. The C-scape memory allocation routines are simple shells around calls to the C run time library allocators. OAKMEMOK.C has some additional functionality: It places a guard byte before and after each block at the time of allocation; it keeps a linked list of each block that is allocated complete with a tag that identifies what C-scape object has been allocated or freed; and, it checks the integrity of the guard bytes for each block of memory in the linked list whenever an allocation is made. Of particular note in OAKMEMOK.C is a function called alloc_test. The allocation routines use this function to perform the check of the linked list of memory blocks. This function takes two arguments: a prompt and a mode. alloc_test returns 0 if the heap is OK. If one of the blocks has had its guard bytes overwritten then it returns the the tag value of the bad block. int alloc_test(char *msg, int mode) The value of mode determines the verbosity of the report: 0 silent 1 print summaries 2 print dump list - Print the entire list of blocks and tags When alloc_test prints it does so by means of a printf. When the allocation routines call this they pass a NULL msg and a mode 0. If a bad block is detected the allocation routine will print an error message noting the bad block's tag. Again, printf is used for the output. To use this aid, compile and link OAKMEMOK.C with your application. Note that you must include the header DEBUG.H. (If you are compiling under Microsoft, remember to pass the /NOE switch to the linker so that references to the memory allocation routines are resolved by the functions in the oakmemok.obj module, not the library.) Every allocation will automatically perform a check on the list of memory blocks and print an error message if the check fails. To pinpoint when and where in your application memory is getting trashed (usually by a bad pointer) you must often call alloc_test explicitly. Pepper your code with calls to this function to localize the error. Sometimes you may also find it necessary to compile those C-scape source modules pertinent to where the error is occuring with the debug switch set and then link these with your application so you can trace into the library and locate an error. This is particularly true in cases where you have modified library code or are otherwise unable to localize the error. When you do this, add alloc_test calls to library source as needed. Since alloc_test and other routines in OAKMEMOK.C us printf to perform output you can redirect this to a file on the DOS command line: myprogrm >myprogrm.err These functions aid in tracking down memory faults but they are not full proof. They can not detect when a memory block has been overwritten without affecting the guard bytes. Despite this limitation they are very good for tracking down most memory errors. _______________________________________________________________________________ 16: A FEW OAKLAND CODE CONVENTIONS The following are a some code convention we use to insure code portability. While not required for DOS and OS/2 it is suggested that you incorporate such conventions in your C-scape application code for ease of porting to other operating systems. 16.1: OGLOBAL In the .c files of C-scape and the OWL, you'll see the use of OGLOBAL - most notably before the definition of a particular field function's field_funcs_struct. Under most operating systems, DOS and OS/2 included, this symbol is conditionally defined by our headers to macro out to nothing. But because of the way compilers for some systems, VMS specifically, treat structure initialization, it is necessary to provide a mechanism for expanding OGLOBAL to something else. Under VMS, our headers expand it to "globaldef" - a keyword peculiar to the compilers for that system which allows the proper compilation of such code. 16.2: OEXTERN In the .h files of C-scape and the OWL, you'll see the use of OEXTERN in declarations of variables that are defined elsewhere. Under most operating systems, DOS and OS/2 included, this symbol is conditionally defined by our headers to macro out to the standard 'C' keyword "extern". But because of the way compilers for some systems, VMS specifically, treat allocation, it is necessary to provide a mechanism for expanding OEXTERN to something else. Under VMS, our headers expand it to "globalref" - a keyword peculiar to the compiler for that system without which such code would not properly compile. 16.3: FNULL C-scape 3.1 library code now makes a distinction between a data and a function pointer. In accord with this, if you have occasion to specify a null function pointer you should use FNULL instead of NULL. Microsoft C, Turbo C and most compilers for DOS and OS/2 won't complain if you don't do this, but compilers for other systems may. You should do this for the sake of code portability. For example, where you used to write: disp_Init(def_ModeText, FNULL); you should now write: disp_Init(def_ModeText, FNULL); What else is affected by this? In general, null pointers in references to borders, mouse handlers, user supplied functions, class functions, explode functions, auxiliary functions, special functions, and the component functions of field_funcs. Here is a summary of the functions or structures refered to in the C-scape 3.0 and 3.1 Manual Function References and in the C-scape 3.0 Manual Addendum that are affected by this: those that deal with borders - frame_Open, slug_Open, pop_View, _Edit, _Prompt, _Menu, _Message, _Text, the hx_struct or hv_struct you pass to help_Init; with mouse handlers - sed_SetMouse; user supplied functions - kb_Idle, the slug_def structure that you pass to slug_Open, the frame_def structure that you pass to frame_Open; class functions - disp_Init; explode functions - sed_SetExplode; auxiliary functions - sed_SetAux; special functions - sed_SetSpecial, sled_Open; and field_funcs component functions - _senter, _sexit, _fenter, _fkey, _fexit. In addition, the list of fsyminit_structs necessary for use with screen files is affected. The fsyminit_struct has three members. The first is a string, the second a function pointer and the third a data pointer. The type casts used for the last two members, as discussed in the manual, are (VOID_FPTR) and (VOID *). Likewise, FNULL and NULL should be used when you wish to initialize these last two members of an fsyminit_struct list entry to a null value. _______________________________________________________________________________ 17: RECOMPILING THE SOURCE CODE 17.1: General Should you wish to use C-scape with another compiler you can purchase the object files for that compiler from us for $100. You can also recompile the source yourself. We will not be obligated to support recompiled source code, however. Note that on the distribution disks we have included a Make file suitable for the Turbo-C and Opus Make utility to facilitate recompilation. If you use a makefile the object modules produced will automatically be organized into a library. If you do not use the makefile and wish to form a library then you will have to use a librarian utility such as Microsoft's LIB utility or Borland's TLIB. When recompiling your source, use the appropriate compiler and assembler flags listed below, In general, recompiling the source is a matter of getting to know the make utility provided with your compiler. We provide makefiles for the Turbo-C Make utility and the Opus Make utility. C-scape makes extensive use of function prototyping. If you are recompiling the source and the compiler you are using does not support prototyping you must define the symbol NO_PROTO in the compile command to disable the prototyping used in the C-scape source. Consult OAKLAND.H to see how this is implemented. 17.2: Microsoft C Make Programmers using Microsoft's make utility should be aware that the default make provided puts severe constraints upon the user. A 512 character limit on macro expansion space as well as nonstandard filename macros tend to render this make utility very difficult to use for large projects. For this reason we do not supply a microsoft make specific makefile. For those who do wish to produce such a makefile, the Turbo-C makefile will act as a good starting point. The major changes that will need to be made consist of breaking up the OBJ macros into several smaller groupings and generating a response file for the LIB utility. See the Microsoft C documentation for details. 17.2.1: OWL The actual command line used in producing the OWL object modules is: cl /c /DM5 /AL /FPc /W3 /I. /Zl /Olt /Tc FILENAME We must caution you that the optimization flags /Ox /Oa can cause very unpredictable effects in C-scape code. The Oakland Group will not support C-scape library source that has been recompiled with the /Ox or /Oa switches Note that the above assumes that you are using only DOS. If you were compiling the library for OS/2 use in addition to DOS you would add the -DOAK_OS2 and -OAK_FAMILYAPI The MASM command line for the assembler modules is : L Model masm /ML /DM5=99 /DLMOD=99 oakint86.asm, \M1L\; M Model masm /ML /DM5=99 /DMMOD=99 oakint86.asm, \M1M\; 17.2.2: CSCAPE The command line used in producing the CSCAPE object modules is: cl /c /DM5 /AL /FPc /W3 /I. /Zl /Olt /Tc FILENAME We must caution you that the optimization flags /Ox /Oa can cause very unpredictable effects in C-scape code. The Oakland Group will not support C-scape library source that has been recompiled with the /Ox or /Oa switches Note that the above assumes that you are using only DOS. If you were compiling the library for OS/2 use in addition to DOS you would add the -DOAK_OS2 and -OAK_FAMILYAPI. 17.3: Turbo-C 2.0 Make 17.3.1: OWL A Turbo-C specific makefile (T2OWL.MAK) and a response file (TC2OWL.RSP) are provided in source archive OWLSRC.EXE and should be usable with only minor modifications. The makefile assumes that you are using TASM rather than MASM. The OWL library is really composed of several sub-libraries, each with its own compile line. The main difference between the compile lines is a flag that sets the name of the code segment for the object module. Each sub-library has the same code segment name. This allows us to make near calls within certain portions of the library. The command line for the OWL library is : tcc -c -ml -w -G -O -Z -zCOWL_TEXT -f FILENAME The above command line assumes that your TURBOC.CFG file is fairly simple and will not conflict with any of the options described here. The assembler files in the OWL library should assembled using the following flags: l Model tasm /ml /dTC=99 /dlMOD=99 /dOWLSEG=99 FILENAME.asm,,; m Model tasm /ml /dTC=99 /dmMOD=99 /dOWLSEG=99 FILENAME.asm,,; 17.3.2: CSCAPE A Turbo-C specific makefile (T2CSCAP.MAK) and two response files (T2CSCAP1.RSP ,T2CSCAP2.RSP) are provided in source archive CSCAPSRC.EXE and should be usable with only minor modifications. The command line for the CSCAPE library is : tcc -c -ml -w -G -O -Z -f FILENAME The above command line assumes that your TURBOC.CFG file is fairly simple and will not conflict with any of the options described here. 17.4: Opus Make 5.0 The Opus Make utility is used in-house at the Oakland group. It is available from Opus Software (415) 664-7901 . We have found it to be very effective and flexible make utility. We provide a initialization file (MAKE.INI) and a makefile (MAKEFILE) in the source archive OWLSRC.EXE . We provide a makefile (MAKEFILE) in the source archive CSCAPSRC.EXE . _______________________________________________________________________________ 18: OS/2 The Microsoft version of the C-scape 3.0 libraries can be used to create OS/2 applications. Only def_ModeText is currently supported under OS/2. Graphics mode is not currently supported under OS/2. We will, at some future date, support graphics under the OS/2 Presentation Manager. To create an OS/2 application you must define the symbol OAK_OS2 when compiling your source. The basic compile line is: cl /c /DM5 /DOAK_OS2 /I\cscape\include myprog.c OAK_OS2 may also be placed in your source file. If you place it in your source file you don't need to define it on the command line. If you do this, you should place the definition in the your .c file that contains the disp_Init call and you must place it before the include statements. #define OAK_OS2 /* for OS/2 */ #include <stdio.h> #include <cscape.h> /* ... */ { disp_Init(def_ModeText, FNULL); /* ... */ Please note that when OS/2 version 1.0 changed to OS/2 Extended Edition 1.1 the library DOSCALLS.LIB was renamed to OS2.LIB. Along with that change, one of the functions changed its name slightly. What was called DosGetPid is now DosGetPID. The Microsoft 5.1 LIBCEP libraries however, still refer to DOSCALLS.LIB. The current call name, DosGetPID, is what appears in OWL source. If you are compiling for OS/2 E.E. 1.1, all is well. If, however, you are compiling for OS/2 1.0 then you must make an additional step. Redefine the current call name back to the older one so that the linker can find DosGetPid. You redefine this in the OWL module that has the call reference - OS2HARD.C: #define DosGetPID DosGetPid /* define for compat. with 1.0 */ then recompile OS2HARD.C. Note that this must be compiled in a code segment that bears the name "OWL_TEXT" (use the /NT flag to name the segment). Then, replace OS2HARD.C in the OWL library. After compilation you must link with the OWL, C-scape and C run time libraries. For Microsoft 5.1 with OS/2 prior to the Extended Edition 1.1: link /SE:500 myprog.obj,,,LLIBCEP.LIB \cscape\lib\m1lowl.lib \cscape\lib\m1lcscap.lib; For Microsoft 5.1 with OS/2 Extended Edition 1.1: link /NOE /SE:500 myprog.obj,,,OS2.LIB LLIBCEP.LIB \cscape\lib\m1lowl.lib \cscape\lib\m1lcscap.lib; If you wish to create a family mode application add the following to the above steps. Define both OAK_FAMILYAPI and OAK_OS2 in the compile command line for the recompilation of the three OS2 files in the OWL: OS2HARD.C, OS2DISP.C and OS2OPEN.C. After this you may link these with your application: Again, for Microsoft 5.1 with OS/2 prior to the Extended Edition 1.1: link /SE:500 myprog os2hard os2disp os2open, myprog, , LLIBCEP.LIB \cscape\lib\m1lowl.lib \cscape\lib\m1lcscap.lib; For Microsoft 5.1 with OS/2 Extended Edition 1.1: link /NOE /SE:500 myprog os2hard os2disp os2open, myprog, , OS2.LIB LLIBCEP.LIB \cscape\lib\m1lowl.lib \cscape\lib\m1lcscap.lib; Then bind your family api application. For OS/2 prior to Extended Edition version 1.1: bind myprog.exe doscalls.lib api.lib -n @bind.exc For OS/2 Extended Edition version 1.1: bind myprog.exe os2.lb api.lib -n @bind.exc For the bind, bind.exc is a text file containing the following lines: DOSCREATETHREAD DOSENTERCRITSEC DOSEXITCRITSEC DOSGETPID DOSMUXSEMWAIT DOSSEMCLEAR DOSSEMREQUEST DOSSEMSET DOSSEMWAIT MOUDRAWPTR MOUGETNUMQUEEL MOUOPEN MOUREADEVENTQUE MOUREMOVEPTR MOUSETDEVSTATUS This file is necessary because our code contains references to OS2 calls above which have no family api counterparts. The bind utility is warning us of this - it would be a problem to run under DOS. But our own provides the functionality to perform the associated tasks under DOS so we may ignore these. _______________________________________________________________________________ 19: OAKLAND TECHNICAL SUPPORT The Oakland Bulletin Board telephone number is (617) 491-1644. It is accessible at both 1200 and 2400 baud. The line protocol is 8 data bits, No parity, and 1 Stop bit. We encourage all to use the bulletin board as a forum by which to share C-scape ideas, comments and code (field functions, drivers, borders, etc.) with others. _______________________________________________________________________________ 20: WHAT IS COMING FROM OAKLAND As adjuncts to the C-scape Manual two additional Oakland publications are mentioned in the its Introduction. Note that The Oakland Advanced Programming Guide and The C-scape Cookbook are both, as yet, under development. All registered users of C-scape will be automatically notified of their availability when completed. Of all references to C-Spot and C-Cell software, note that these products are under developement and not yet available. Registered user's of C-scape will be automatically notified of their availability when completed.