KeyKOS C Programming Reference

Using Headers

One or more of the KeyKOS header files ("KEYKOS H", "KEYKOS1 H", "KEYKOS2 H") must be included in every C source file and should be the first included file. The header used depends on the type of runtime environment that is desired. The sections on each of these environments describes which headers to use. The most common header "KEYKOS H" is used with the environment that is described in this section and allows use of the full C language.

#include <keykos.h>

Of course, if you use any library functions, the corresponding headers should be included. No global MACLIBs are required for the compilation because the header files are read as individual CMS files, rather than members of a MACLIB.

Header files should not have sequence numbers. Any text in columns 73-80 will be compiled.

Using Updates

You can use the CMS UPDATE facility in conjunction with C programs and headers.

Because the Waterloo compiler does not perform updating of files, header files must be updated before they are used in a compilation. The base file for the header AHEADER should be named "AHEADERH HS" (think "Header Source"). The command:

VMFH AHEADER [ctl] [(options]

updates AHEADERH HS (using AHEADERH AUX... and AHEADERH update files) to produce an updated file called AHEADER H (note no H in the filename). Columns 73-80 of the updated file will be blank. You then add the following statement to your program:

#include "aheader.h"

To build updated source for a .h file, use the following command:

VMFH fname [ctl] [( HSTYLE [options]]

     VMFH <name>           updates "<name>H HS" to produce "name H".

     VMFH <name>(HSTYLE    updates "<name>  HS" to produce "name H".

The control file used is "ctl CNTRL". If ctl is not specified, "FT CNTRL" is used.

Other options will be documented here at a later date.

Compilation

- To update a source file, run the KCPP preprocessor, and compile the result, enter this CMS command:

VMFC fname [ctl] [(KJUMP otheroptions]

This uses the CMS file "fname C" and its updates, with the control file "ctl CNTRL". If ctl is not specified, the default control file is "FT CNTRL". The KJUMP option specifies the use of the key cache. Other options will be documented here at a later date.

- To run the KCPP preprocessor, enter this CMS command:

KCPP fname [ftype [fmode] ] [( KJUMP ]

This uses the CMS file "fname ftype fmode" as input. The filetype defaults to "C", and the filemode defaults to "*". The KJUMP option specifies the use of the key cache. KCPP expects as input a standard C program with intermixed key invocation statements and KEY and STRING declarations. Any text in columns 73-80 will be removed. The output of KCPP is the CMS file "fnameÊCXÊA1".

- To compile the output of KCPP with the Waterloo C compiler, enter this CMS command:

CW fname CX [fmode] [( options ]

The CWC EXEC can be used to both run KCPP to produce preprocessor output and then run the Waterloo C compiler. If there is an error diagnosed by KCPP, the preprocessor output file is not erased and the C compiler is not executed. Otherwise all intermediate files are erased.

- To run the KCPP preprocessor and compile the result if there are no errors, enter this CMS command:

CWC fname [ftype [fmode] ] [KJUMP] [( options ]

This uses the CMS file "fname ftype fmode" as input. The filetype defaults to "C", and the filemode defaults to "*". The KJUMP option specifies the use of the key cache. The options are described in the Waterloo C User's guide.

- To see a brief list of the Waterloo C compiler options, use this CMS command:

CW ?

Linkage

A C object can be linked either in CMS or KeyKOS.

Building the Full Function Environment

The linkage described here applies only to the "standard" C runtime environment. This environment is the most common and allows full use of the C language. There are two basic options to select when building an object using this environment. The object can be linked in CMS using the LC command or the object can be linked in KeyKOS using the Binder.

Linking in CMS

To link a C object in CMS use the LC EXEC. Options for the LC EXEC are the same as for the GLINK EXEC. To see a list of the GLINK options, type the CMS command

GLINK ?

After the resulting CMS module is exported to KeyKOS as a segment, the PCS command system's CFACT command is used to produce an object factory. For example:

CFACT <factory_name> <module> <akt> S0=USER.SYS.CDESTROY

The primary reason for using this command is that it builds a virtual copy segment (VCS) for the memory tree of the object. As a result of using the CFACT command, component 9 contains a data key with the time zone and start address of the stack/heap.

Memory after the code portion has the following layout:: global register area (default 4K),
run-time stack (default 32K),
remaining memory up to 8M, or the limit declared in SETUP C (which can be used for dynamic memory allocation).

Currently, component 0 must be specified. This is the key to the read-only page which contains destroy logic for the C domain (available in USER.SYS.CDESTROY). If a C object linked in CMS returns from the main() routine or calls the exit() function, then its memory tree is replaced by the read-only page containing destroy logic which was installed as component 0 of the factory. The memory segment is then released and the domain destroyed.

Linking in KeyKOS

To link a C object in KeyKOS, first export the CMS text deck to KeyKOS as a segment. The USER.SYS.KKOSCLIB. directory contains all C library functions. SLOAD can be used to link a C object under KeyKOS.

The following is an example of how a C object can be linked in KeyKOS using SLOAD and the PCS command system:

KC USER.SYS.SYSPF 0 (,SB,M,SWITCHER) (,SYSP)
KC USER.SYS.SLOAD 0 (,SB,M,SB) (,CO)
*
*   Include CSTART to initialize the run-time environment
*
KC CO 0 (%ECSTART,USER.SYS.KKOSCLIB.CSTART,SYSP)
*
*   Include the C program's text deck
*
KC CO 0 (%E<name>,USER.<text>,SYSP)
*
*   Include the C run-time stack
*
KC CO 0 (%ESTACK,USER.CSTACK,SYSP)
*
*   Resolve remaining external references
*   and finish loading
*
KC CO 1 (,SYSP,USER.SYS.KKOSCLIB.) (%E%X,LSF,BINDER)
KC CO 0
*
*   Build the factory
*
FACTORY <factory_name> LSF 99

Building the Early Object Environment

Compile the program using CWC as in the Full Function Environment. Remember to use <keykos1.h> and <keykos2.> and not have and read/write global variables and do not use the Key Cache. If you violate any of these restrictions your object will crash attempting to store on a read/only page.

Link the program using the LC command. The binder may not be used with this environment. Either of the LC commands below is correct. The second LC command has the advantage of having a constant starting address (x'10'). LC is smart enough to generate the correct module name in either case.

LC program CFSTART  othertextdecknames
LC CFSTART program  othertextdecknames

Export the module file and use the FACTORY command to build the object. No components are required and all components are available for to user to specify.

FACTORY Factoryname segmentname AKT [ord] S|H|Fn=

Debugging

Debugging a C object is similar to debugging a PL/I object. To debug a C object:

Use the functions dotrace(), trace(), _trace(), and notrace() to enable or disable debug tracing to a specified output KEY. These functions are similar to the functions printf() and fprintf() (see Waterloo C User's Guide). Output can either be directed to a terminal via a SOK key, or written to an entry sequenced record collection, or both.
Compile the C object with the ASMSRC option. This will produce an assembler source file (with filetype "ASSEMBLE") in which the C source lines are included as comments. Be sure to use the same DBG options as used without the ASMSRC option as the compiler generates different code based on the DBG option.
If an object was linkedited under CMS, the map file (with filetype "MAP") is available which contains not only addresses of subroutines but also addresses of all external variables.
If an object was linked in KeyKOS, BINDQRY may be used to obtain the same information.
When a key invocation statement is executed, besides examining exit and entry masks, certain information can be extracted by examining two fields, referred to as "xtype" and "ntype", that contain descriptions of the exit and entry blocks, respectively. R12 points to a stack and the first 4 words on it contain the following:

xtype value, address of exit block, ntype value, address of entry block.
The bits of the high-order byte of xtype and ntype are set up in the following way:
- Bit 0: 1 if some of the keys are constant keys.
- Bit 1: 1 if some of the keys are variables.
- Bit 2: 1 if the key cache was specified during compilation.
- Bit 3: 1 if CHAR/STRUCT is specified and only 2 parameters are passed.
- Bit 4: 1 if CHAR/STRUCT is specified and 3 parameters are passed.
- Bit 5: 1 if STRING is specified.
The rest of the bits are turned off. Bits 3 through 5 are always turned off for xtype.

Chapter 3. Compiling and Linking in CMS