| Previous | Contents | Index |
There are several options available for copying files from within a
program. Obvious choices include using lib$spawn(), system(),
sys$sndjbc() or sys$creprc() to invoke a DCL COPY command. Other common
alternatives include using the callable convert routines and the BACKUP
application programming interface (V7.1 and later).
10.13 What is a descriptor?
A descriptor is a data structure that describes a string or an array. Each descriptor contains information that describes the type of the data being referenced, the size of the data, and the address of the data. It also includes a description of the storage used for the data, typically static or dynamic. Descriptors are passed by reference.
The following are examples of creating and using descriptors in C, with the use of the angle brackets normally expected by the C include statements deliberately altered in deference to HTML:
#include {descrip.h}
#include {lib$routines.h}
#include {stsdef.h}
int RetStat;
char TxtBuf[TXTSIZ]
struct dsc$descriptor StaticDsc =
{ 0, DSC$K_DTYPE_T, DSC$K_CLASS_S, NULL };
struct dsc$descriptor DynDsc =
{ 0, DSC$K_DTYPE_T, DSC$K_CLASS_D, NULL };
int DynDscLen = 255;
$DESCRIPTOR( ConstDsc, "This is a string" );
/* finish setting up a static descriptor */
StaticDsc.dsc$w_length = TXTSIZ;
StaticDsc.dsc$a_pointer = (void *) TxtBuf;
/* finish setting up a dynamic descriptor */
RetStat = lib$sget1_dd( &DynDscLen, &DynDsc );
if ( !$VMS_STATUS_SUCCESS( RetStat ) )
return RetStat;
/* release the dynamic storage */
RetStat = lib$sfree1_dd( &DynDsc );
if (!$VMS_STATUS_SUCCESS( RetStat ))
return RetStat;
|
Static descriptors reference storage entirely under application program control, and the contents of the descriptor data structure can be modified as required (by the application). OpenVMS routines do not modify the contents of a static descriptor, nor do they alter the address or length values stored in the static descriptor. (The term "static" refers to the descriptor data structure, and not necessarily to the storage referenced by the descriptor.)
Dynamic descriptors reference storage under the control of the run-time library, and the contents of a dynamic descriptor data structure---once initialized---can only be modified under control of run-time library routines. The dynamic storage referenced by the dynamic descriptor is allocated and maintained by the run-time library routines. Various OpenVMS routines do alter the contents of the descriptor data structure, changing the value for the amount and the address of the storage associated with the dynamic descriptor, as required. Routines can obviously access and alter the contents of the storage referenced by the descriptor.
OpenVMS languages that include support for strings or arrays are expected to use descriptors for the particular structure. Most OpenVMS languages, such as Fortran and BASIC, use descriptors entirely transparently. Some, like DEC C, require the programmer to explicitly create and maintain the descriptor.
For further information on string descriptors, see the OpenVMS Programming Concepts manual, part of the OpenVMS documentation set.
Fortran defaults to passing integers by reference and characters by descriptor. The following sites discuss mixing Fortran and C source code in the same application:
Many server processes can operate within the context of the target user using privileges, using calls such as sys$chkpro and (more commonly in this context) sys$check_access as needed to determine if access would be permitted for the specified user within the current security model.
With OpenVMS V6.2 and later, the persona system services (SYS$PERSONA_*) can be used to assume the persona of the specified user---these allow the server to operate as the specified user, in a controlled fashion. The persona services can be used as a "wrapper" around a sys$creprc process creation call, as well---this will create a seperate process entirely under the assumed persona.
Information on the persona system services is included in the OpenVMS V6.2 new features documentation, and in the OpenVMS V7.1 and later system services documentation. These system services exist and are supported in OpenVMS V6.2 and later releases.
Typical mechanisms for creating a process under another username include:
There are likely a few other mechanisms around... There are various
tools available from DECUS and other sources that allow various forms
of user impersonation, as well. These tools will require
version-dependent kernel code and enhanced privileges for some of (or
all of) their operations.
10.15 Why do lib$spawn, lib$set_symbol fail in detached processes?
The processing within run-time library (RTL) calls such as lib$attach, lib$disable_ctrl, lib$do_command, lib$enable_ctrl, lib$get_symbol, lib$run_program, lib$set_symbol, lib$set_logical, and lib$spawn, is dependent on and requires the presence of a command language interpreter (CLI), such as DCL. Without a CLI present in the current process, these calls will fail with a "NOCLI, no CLI present to perform function" error.
Detached processes typically do not have a CLI present.
In place of lib$spawn, sys$creprc can often be used. The context of the parent process (symbols and logical names) will not be propogated into the subprocess when sys$creprc is used, though when there is no CLI present in the process this (lack of) propogation is moot.
To create a detached process with a CLI, you must specify LOGINOUT as the target image as discussed elsewhere in the FAQ, or only use these calls (and any other calls requiring a CLI) from images that are running in an "interactive", "batch", or "other" mode process.
Also note that the lib$spawn and the C system call will fail in a
CAPTIVE login environment. The lib$spawn call can be gotten to work in
this environment with the specification of the TRUSTED flag.
10.16 Where can I obtain Bliss, and the libraries and supporting files?
The Bliss language compilers and documentation are available on the OpenVMS Freeware distributions.
Bliss language source code that contains the following statement:
LIBRARY 'SYS$LIBRARY:STARLET.L32'; |
or similar requires the presence of the Bliss libraries. These libraries are created on the target system using the Bliss require files, and are built using the following Bliss commands:
STARLET.L32 contains the public interfaces to OpenVMS:
$ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]STARLET.L32 -
SYS$LIBRARY:STARLET.REQ
|
LIB.L32 contains both the public and private interfaces to OpenVMS:
$ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]LIB.L32 -
SYS$LIBRARY:LIB.REQ+SYS$LIBRARY:STARLET.REQ
|
The equivilent files for Bliss64 are created with:
$ BLISS/A64/LIBRARY=SYS$COMMON:[SYSLIB]LIB.L64 -
SYS$LIBRARY:LIB.R64+STARLET.REQ+STARLET.R64
$ BLISS/A64/LIBRARY=SYS$COMMON:[SYSLIB]STARLET.L64 -
SYS$LIBRARY:STARLET.R64
|
Some Bliss code may also require the OpenVMS VAX architecture flags. The following is the equivilent of the Alpha ARCH_DEFS.REQ module:
!
! This is the OpenVMS VAX version of ARCH_DEFS.REQ, and
! contains the architectural definitions for conditionally
! compiling OpenVMS Bliss sources for use on VAX systems.
! (If you should encounter compilation errors here, please
! seriously consider upgrading your Bliss compiler.)
!
MACRO VAXPAGE = 1%;
MACRO BIGPAGE = 0%;
!
MACRO VAX = ! = 1 if compiled BLISS/VAX
%BLISS(BLISS32V)%; ! = 0 if not compiled BLISS/VAX
MACRO EVAX = ! = 1 if compiled BLISS/E* (Obsolete, old name)
(%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /Inn
MACRO ALPHA = ! = 1 if compiled BLISS/E* (New arch name)
(%BLISS(BLISS32E) OR %BLISS(BLISS64E))%; ! = 0 if compiled /VAX /Inn
MACRO IA64 = ! = 1 if compiled BLISS/I* (New arch name)
(%BLISS(BLISS32I) OR %BLISS(BLISS64I))%; ! = 0 if compiled /VAX or /Ann
MACRO ADDRESSBITS =
%BPADDR%; ! = 32 or 64 based on compiler used
|
Some Bliss code may require the definition files for the OpenVMS older LIBRTL routine lib$tparse, or the newer lib$table_parse call:
$ BLISS /LIBRARY=SYS$COMMON:[SYSLIB]TPAMAC.L32 -
SYS$LIBRARY:TPAMAC.REQ
|
When creating a file, it is often useful to allow other applications and utilities---such as TYPE---to share read access to the file. This permits you to examine the contents of a log file, for instance.
A C source example that demonstrates how to do this is available in topic (2867) in the OpenVMS Ask The Wizard area:
For additional information on the OpenVMS Ask The Wizard (ATW) area and for a pointer to the available ATW Wizard.zip archive, please see Section 3.9.
Depending on the environment, you may need to use C calls such as fsync
and fflush, and---in specific cases---the setvbuf(_IONBF) call.
10.18 How can I have common sources for messages, constants?
Use the GNM tools on the OpenVMS Freeware to have common sources for
MSG (message) files and SDML (Document) documentation files. Use the
DOCUMENT command to convert the SDML documentation into the necessary
formats (Text, Postscript, HTML, etc). Use the MESSAGE/SDL tool (latent
in OpenVMS) to create an SDL file based on the messages. Then use the
SDL tool (available on the OpenVMS Freeware) to convert the SDL file
into language-specific definitions. (There is also a converter around
to convert SDL into SDML, if you want to get pictures of the data
structures for your documentation.)
10.19 How do I activate the OpenVMS Debugger from an application?
#include {lib$routines.h}
#include {ssdef.h}
#include {string.h}
main()
{
char ascic_debug_commands[128];
char *dbgcmd = "*show calls;go;exit";
strcpy( ascic_debug_commands, dbgcmd );
ascic_debug_commands[0] = (char) strlen( dbgcmd ) - 1;
lib$signal(SS$_DEBUG,1,ascic_debug_commands);
return 1;
}
|
OpenVMS on VAX, OpenVMS on Alpha and OpenVMS on Intel IA-64 platforms (as well as all Microsoft Windows implementations and platforms) all support and all use the little-endian byte ordering. Certain Alpha microprocessors and certain Intel Itanium processors can be configured to operate in big-endian and potentially in bi-endian mode. HP-UX typically operates big-endian.
With little-endian byte order, the least significant byte is always the first byte; the byte at the lowest address. With big-endian byte ordering, the byte storage order in memory is dependent on the size of the data (byte, word, longword) that is being referenced.
Endian-ness is a problem has been solved many times before. Some of the
typical solutions include htonl/htons and ntohl/ntohs in the standard C
library and the TCP/IP Services XDR (eXternal Data Representation)
libraries. One of the more recently introduced network formats, and one
that is seeing extensive press and marketing coverage, is XML.
10.21 How to resolve LINK-I-DATMISCH errors?
The message LINK-I-DATMISCH is informational, and indicates that the version of the specified shareable image found in the system shareable image directory does not match the version of the shareable image that was originally loaded into IMAGELIB.OLB, one of the OpenVMS libraries typically searched by the LINKER.
From a privileged username, you can usually completely repair this via the following DCL command:
$ LIB/REPLACE/SHARE SYS$LIBRARY:IMAGELIB.OLB SYS$SHARE:LIBRTL.EXE |
This command assumes that the shareable image that was found in the
SYS$SHARE: area is valid and upward-compatiable, and that the image has
simply replaced an older version without also updating IMAGELIB.
10.22 HP C and other OpenVMS C Programming Considerations?
VAX C V3.2 was released for OpenVMS VAX systems in 1991. DEC C V4.0 replaced VAX C V3.2 in 1993 as the HP C compiler for OpenVMS VAX systems. HP C is the ANSI C compiler for OpenVMS Alpha systems. VAX C predates the ANSI C standards, and has various areas that are not compliant with ANSI C requirements. HP C is an ANSI C compiler, and can also compile most VAX C code when /STANDARD=VAXC is specified. Versions of this compiler between V3.2 and V6.5 (exclusive) were known as DEC C, DIGITAL C, and Compaq C.
Both compilers can be installed at the same time on the same OpenVMS VAX system, allowing a migration from VAX C to DEC C, and allowing the same DEC C code to be used on OpenVMS VAX and OpenVMS Alpha.
The system manager can choose the system default C compiler when HP C is installed on a system with VAX C, and a C programmer can explicitly select the required compiler for a any particular compilation.
A current "C" license PAK allows access to both VAX C and HP C on the same OpenVMS VAX system.
Various HP C versions can be installed on OpenVMS VAX V5.5-2 and later. OpenVMS VAX releases such as V5.5-2 and V6.0 will require the installation of a HP C RTL kit, a kit that is included with the HP C compiler. OpenVMS VAX versions V6.1 and later do not require a seperate RTL kit, but HP C RTL ECO kits are available to resolve problems found with the C RTL on various OpenVMS releases.
With HP C, for automatic resolution of the standard C library routines by the LINKER utility, use the /PREFIX qualifier, such as /PREFIX=ALL_ENTRIES. If a particular application program replaces an existing C library routine, use /PREFIX=(ALL_ENTRIES,EXCEPT=(...)). (VAX C required explicit specification of an RTL shareable image or C object library during the link.)
When the /PREFIX is requested, the compiler generates a "decc$" prefix on the specified symbols. This prefix allows the LINKER to resolve the external symbols against the symbols present in the DECC$SHR library. The DECC$SHR library is included in the IMAGELIB.OLB shareable image library, and IMAGELIB is searched by default when any program (written in any language) is LINKed. Because the standard C library routine names are very likely to match application routines written in other languages, a prefix "decc$" is added to the C symbol names to assure their uniqueness; to prevent symbol naming conflicts. C programs, however, can sometimes have private libraries for various purposes, and the external routines share the same names as the library routines. (This is not recommended, but there are applications around that use this technique.) Thus the need to explicity specify whether or not the "decc$" prefix should be prepended to the external symbol names by the compiler.
The qualifiers, and most (all?) with associated pragmas, that may be of interest when migrating VAX C code to HP C include:
#ifdef __DECC #pragma message save #pragma message disable /* insert message tag here */ #endif |
Permit structure members to be naturally aligned whenever possible, and avoid using /NOMEMBER_ALIGNMENT. If you need to disable member alignment, use the equivilent #pragma to designate the specific structures. The alignment of structure members normally only comes into play with specific unaligned data structures---such as the sys$creprc quota itemlist---and with data structures that are using data that was organized by a system using byte or other non-member alignment.
Versions of HP C such as V6.0 include the capability to extract the contents of the standard header libraries into directories such as SYS$SYSROOT:[DECC$LIB...], and provide various logical names that can be defined to control library searches. With HP C versions such as V6.0, the default operations of the compiler match the expectations of most OpenVMS programmers, without requiring any definitions of site-specific library-related logical names. (And logical names left from older DEC C versions can sometimes cause the compiler troubles locating header files.)
HP C V5.6 and later include a backport library, a mechanism by which HP C running on older OpenVMS releases can gain access to newer RTL routines added to the RTL in later OpenVMS releases---the language RTLs ship with OpenVMS itself, and not with the compilers.
Example C code is available in SYS$EXAMPLES:, in DECW$EXAMPLES (when the DECwindows examples are installed), in TCPIP$SERVICES (or on older releases, UCX$EXAMPLES) when HP TCP/IP Services is installed), on the Freeware CD-ROMs, and at web sites such as
For additional information on the OpenVMS Ask The Wizard (ATW) area and
for a pointer to the available ATW Wizard.zip archive, please see
Section 3.9.
10.22.1 Other common C issues
The localtime() function and various other functions maintain the number of years since 1900 in the "struct tm" structure member tm_year. This field will contain a value of 100 in the year 2000, 101 for 2001, etc., and the yearly incrementation of this field is expected to continue.
The C epoch typically uses a longword (known as time_t) to contain the number of seconds since midnight on 1-Jan-1970. At the current rate of consumption of seconds, this longword is expected to overflow (when interpreted as a signed longword) circa 03:14:07 on 19-Jan-2038 (GMT), as this time is circa 0x7FFFFFFF seconds since the C base date. (The most common solution is to ensure that time_t is an unsigned.)
If C does not correctly handle the display of the local system time, then check the UTC configuration on OpenVMS---the most common symptom of this is a skew of one hour (or whatever the local daylight savings time change might be). This skew can be caused by incorrect handling of the "is_dst" setting in the application program, or by an incorrect OpenVMS UTC configuration on the local system. (See section Section 4.3.)
Floating point is prohibited in OpenVMS Alpha inner-mode (privileged) code, and in any process or other execution context that does not have floating point enabled. C programmers developing and working with OpenVMS Alpha high-IPL kernel-mode code such as device drivers will want to become familiar with the floating point processing available in the environment, and with the C compiler qualifier /INSTRUCTION_SET=[NO]FLOATING_POINT. Device drivers and other similar kernel-mode C code must be compiled with /INSTRUCTION_SET=FLOATING_POINT and /EXTERN_MODEL=STRICT_REFDEF.
Additionally, the SYS$LIBRARY:SYS$LIB_C.TLB/LIBRARY parameter will be needed to be appended to the module specification or declared via the C compiler's include library logical name mechanism when the C compiler is resolving kernel-mode data structures and definitions. This library contains OpenVMS kernel-mode and other system declaractions, and particularly a mixture of undocumented definitions and declarations, and particularly definitions and declarations that are subject to change (and that can accordingly lead to requirements for the recompilation of application code).
In addition to the user-mode C Run-Time Library (RTL) mentioned in the OpenVMS C RTL documentation and referenced over in Section 3.11, there is a second and parallel kernel-mode RTL accessable to device drivers and other kernel code on OpenVMS Alpha and OpenVMS I64. The most common time this second C library is noticed is when C code is (erroneously) linked with /SYSEXE/SYSLIB, and duplicate symbol errors typically then arise. As code running in supervisor-, executive- or kernel-mode context cannot call out a user-mode RTL or other user-mode library, you will want to respecify the command as LINK /SYSEXE/NOSYSLIB. This will eliminate the duplicate symbol errors, since only the kernel-mode library will be referenced, and it will also avoid calling out into the user-mode libraries.
When sharing variables with other languages, here is some example HP C code...
...
#pragma extern_model save
#pragma extern_model strict_refdef
extern int VMS$GL_FLAVOR;
#pragma extern_model restore
...
|
and here is some associated example Bliss code...
...
EXTERNAL
VMS$GL_FLAVOR,
....
|
| Previous | Next | Contents | Index |