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