Advanced C on OpenVMS
CETS2001 session 1130
Stephen Hoffman
OpenVMS Engineering
Audience
•	Familiarity with general C programming
•	Unfamiliarity with OpenVMS C programming
Roadmap
•	Basic data structures and definitions
•	System and RTL calls
•	Memory and cache management
•	Security and IP networking
•	Standard library extensions for OpenVMS
•	Building your application
•	Summary
Using OpenVMS Features
Descriptors, system services, etc
Descriptors
•	Defined by descrip.h
•	Core Fields
–	Length
–	Class
–	Data Type
–	Buffer Address
Descriptors
•	Descriptor Class
–	Static (DSC$K_CLASS_S)
–	Dynamic (DSC$K_CLASS_D)
Descriptors
•	Descriptor Type
–	String (DSC$K_DTYPE_T)
–	Various Arrays
–	Various Integers
Descriptors
•	Descriptor Type
–	struct dsc$descriptor FooDsc;
–	$DESCRIPTOR( FooDsc, "Constant" );
System Services, RMS, RTLs
•	Arcane distinction
–	Underlying implementation
•	Part of the operating system kernel...
•	...or shareable layered onto the kernel
–	Permissible processor calling modes
•	Do not call RTL APIs from inner modes
System Services
•	Implementation
–	Part of the operating system kernel
–	Privileged Shareable Image
•	User Written System Service (UWSS)
•	SYS$EXAMPLES:UWSS*.*
•	entry point definitions: starlet.h
RMS services
•	Part of the operating system kernel
•	Definitions
–	starlet.h
–	rmsdef.h
•	Example code:
–	Freeware [SRH_EXAMPLES]
Run-Time Library (RTL) routines
•	Implemented by shareable images
•	Include file definitions:
–	lib$routines.h
–	str$routines.h
–	cli$routines.h
–	*$routines.h
System Definition Files
•	SYS$STARLET_C.TLB
•	SYS$LIB_C.TLB
•	DECC$RTLDEF.TLB
System Definition Files
•	Structure Definition Language
–	SDL
–	SDL/NOPARSE
–	STARLETSD.TLB
Errors and Signals
Conditions, traps, faults, signals...
Condition values
•	Success is odd
•	definitions in stsdef.h

if (!$VMS_STATUS_SUCCESS( RetStat ))
    lib$signal( RetStat );
Signaling...
•	Mechanism for centralizing (and simplifying) application error handling

C Signals
•	Standard C signal mechanisms available

OpenVMS Signals
•	Native OpenVMS signals available
–	definitions in chfdef.h
–	SigArgs, MechArgs arrays
–	Used to implement C signals
–	32 bit vs. 64 bit formats

OpenVMS Signals
•	Favorite (OpenVMS) Signals
–	lib$signal( SS$_PRCDMP );
–	lib$signal( SS$_DEBUG, 1, AscicString );
Asynchronous System Traps (ASTs)
•	Asynchronous event notification
–	Timers ($setimr)
–	Events ($qio, locks)
•	Beware volatility, re-entrancy
–	more on this in a bit

Memory Management
Alignment, Barriers, Reentrancy...
Shared Memory
•	system services
–	sys$crmpsc, sys$mgblsc
–	code examples: Ask The Wizard (ATW)
•	mmap
–	ATW
Managing shared memory
•	Interlock Primitives
–	bitlocks
–	queues
•	Memory Cache
–	Controls sequencing of reads and writes
–	Memory Barriers
–	Target Address Space
•	Memory Space
•	I/O Space
Volatility and Re-entrancy
•	Lifetime of Asynchronous Calls
–	Active stack frames
–	Pool (heap)
Volatility and Re-entrancy
•	Re-entrancy
–	Threads
–	ASTs
–	Mix Threads and ASTs with care
–	ATW topics (1661), (2681), (6099)
Data Alignment
•	Memory page sizes
–	512 bytes (VAX)
–	8 KB (to 64 KB on Itanium™)?
•	Disk block sizes
–	512 bytes
Data Alignment
•	Naturally align for performance
•	#pragma [no]member_align
•	Default Padding
–	VAX: Byte Alignment
–	Alpha: Natural Alignment
•	favorite example of alignment trouble:
–	$creprc quota array argument
Supporting Interfaces
Security, IP networking, Time, etc
Use OpenVMS Security APIs
•	Security Services
–	$chkpro
–	$check_access
–	Best: Try it, and handle failures
•	Per-thread Security
Use OpenVMS Security APIs
•	Assigning Privileges
–	Don't
–	Don't
–	Don't
–	Subsystem Identifiers
–	Installled Images
–	Captive Logins, Server Processes
–	Assign Privileges to Individuals
IP Network Implementation
•	TCP/IP Services
–	C socket interface into TCP/IP Services
•	Documentation in C manual appendix
–	$qio interface into TCP/IP Services drivers
•	Documentation in TCP/IP Services manuals
Symbol Naming
•	Use symbol prefixes to avoid collisions
•	Symbol format recommendations documented
–	Longword: fac$l_symbol
–	Constant: fac$k_symbol
–	Text: fac$t_symbol
–	Size fac$s_symbol
Time
•	C RTL uses OpenVMS timekeeping, TDF
•	If your C code's time is off by an hour...
–	the TDF is set incorrectly
–	the is_dst field is set incorrectly
–	the OpenVMS time is set incorrectly
•	Please see the FAQ

The standard C library
Extensions to the standard library...
C File I/O on OpenVMS
•	Extensions to standard I/O calls
–	creat(x,y,...)
–	fopen(x,y,...)
C File I/O on OpenVMS
•	Common (extension) keywords
–	acc
•	FAB and RAB
–	shr
•	FAQ
C File I/O on OpenVMS
•	Symbols and Logical Names
–	Set Symbol/Logical
•	setenv
•	lib$set_logical, lib$set_symbol
•	sys$trnlnm
–	Get Symbol/Logical
•	getenv
•	lib$get_logical, lib$get_symbol
•	sys$crelnm
Building
Compiling and Building Applications
Compilation considerations
•	C Library Symbol Prefixes (decc$)
–	/PREFIX=ALL
•	Symbol Name Case Preservation
–	Compiler and LINKER
Compilation considerations
•	Alpha compiler code generation
–	/OPTIMIZE=TUNE=GENERIC
–	/ARCHITECTURE=EV56
–	See the FAQ
Compilation considerations
•	Optimizer
–	Use the static keyword liberally
•	Key to routine-level optimizations
–	Use volatile keyword to flush from registers
LINK Considerations
•	Unresolved C library symbols?
–	CC/PREFIX=keyword

LINK Considerations
•	Duplicate Symbols?
–	Check for use of a reserved keyword
–	Both C Libraries referenced?
•	Beware the kernel-mode C RTL
–	LINK/SYSEXE/NOSYSLIB
LINK Considerations
•	Shareable Images
–	Use shareable images
–	Use privileged shareable images with care
•	Cookbook is available at the Ask The Wizard site
Build and Supporting Tools
•	Tools
–	mms, mmk, gmake, imake, etc
–	gcc, Compaq C (DEC C), VAX C
–	sdl, zip, tar, lex/yacc/flex/bison, etc
–	Enterprise Toolkit
•	CSA program
•	OpenVMS FAQ
Summary
The common questions, 
and the available resources...
Where to go for help?
http://www.openvms.compaq.com/
FAQ, Roadmap, Ask The Wizard, 
OpenVMS Documentation, Books (including: Writing OpenVMS Device Drivers in C)
The Fine Print
Copyright 2001 Compaq Computer Corporation All rights reserved.
While Compaq  believes the information included in this presentation is correct as of the date produced, it is subject to change without notice.
All trademarks and registered trademarks are the property of their respective holders.  Itanium™ and IA-64™ are trademarks of Intel.
Presentation void where taxed or prohibited by law.
Recommended for technical and engineering ranks ages 12 and up.  Ask for special pointy-haired-boss toy.
Known Glaze-on hazard, please keep this and all other similar presentations away from known-sensitive members of engineering, marketing and management.

OpenVMS Technical Update
CETS2001 session 1130