[eric@tardis.HQ.ileaf.com]There is a lot of information available on how to call system services and Run-Time Library routines, including examples in numerous languages.
[Steve Lionel]Arne Vajhøj has put together a collection of OpenVMS example programs. It can be found at:
[Arne Vajhøj]Additional information and examples for OpenVMS are available via:
[Steve Hoffman]
To write an application which uses the normal DCL verb/qualifier/parameter syntax for invocation, see the description of the CLI$ routines in the OpenVMS Callable Utility Routines Reference Manual.
It is possible to write an application which can be used both ways; if a DCL verb isn't used to invoke the image, the application parses the command line itself. One way to do this is to call CLI$GET_VALUE for a required parameter. If it is not present (or you get an error), call LIB$GET_FOREIGN to get the command line and do the manual parse.
See also question DCL1.
Also see PROG11, particularly for pointers to the details on shareable images and shareable image creation.
[Arne Vajhøj]
SYMBOL_VECTOR=(FOO=PROCEDURE, BAR=PROCEDURE)
The Linker manual has more details on this.
This has several advantages over OpenVMS VAX. First, you don't have to worry about the address of the psect when you try to create a new, upwardly compatible version of the shareable image. Second, you can control which psects, if any, are made visible outside the shareable image.
By default, COMMON PSECTs in DEC Fortran for OpenVMS Alpha (as well as most other OpenVMS Alpha compilers) are NOSHR. On VAX, the default was SHR which required you to change the attribute to NOSHR if you wanted your COMMON to be in a shareable image but not write-shared by all processes on the system. If you do want write-sharing, use: CDEC$ PSECT common-name=SHR in the Fortran source code (the CDEC$ must be begin in column 1) or a linker options file PSECT_ATTR statement to set the COMMON PSECT attribute to SHR.
For further information, see the Linker manual.
DEC Fortran (all platforms) has a feature which will perform automatic conversion of unformatted data during input or output. See the DEC Fortran documentation for information on "non-native data in I/O" and the CONVERT= OPEN statement keyword.
There are floating-point conversion source code packages available for various platforms.
http://www.hhs.dk/anonymous/pub/vms/collection/ieee.zip
Note that omitting arguments to Fortran routines is non-standard and is unsupported. It will work in many cases - read the DEC Fortran release notes for additional information.
Compaq OpenVMS uses a software-based system called the License Management Facility or LMF. This provides for software keys (Product Authorization Keys or PAKS) which support capacity and user-based license checking. Compaq offers an LMF PAK Generator to CSA members - See VMS16.
However, if a hardware-based method is required, the most common method is
based on an Ethernet adaptor hardware address. Sample source code for
implementing this is available at:
http://www.openvms.compaq.com/wizard/
Executable images are programs that can be directly executed. These images can grant enhanced privileges, with an INSTALL of the image with /PRIVILEGE, or can grant enhanced access with the specification of a subsystem identifier on the ACL associated with the image.
Shareable images contain code executed indirectly, these images are referenced from executable images and/or from other shareable images. These images can not grant enhanced privileges, even with the use of INSTALL with /PRIVILEGE or a subsystem identifier. These shareable images can be dynamically activated (a LINK that occurs at run-time) via the LIB$FIND_IMAGE_SYMBOL run-time library (RTL) routine. (See "protected images" for information on "privileged shareable images".)
System images are intended to run directly on the VAX or Alpha hardware - these are normally used for the kernel code that comprises an operating system.
Protected images - also refered to as User-Written System Services (UWSS), or as privileged shareable images - are similiar in some ways to a standard shareable images, but these images include a "change mode" handler, and execute in an "inner" processor mode (privileged mode; executive or kernel), and code executing in inner modes has implicit SETPRV privilege. Must be INSTALLed with /PROTECT. Note that inner-mode code has restrictions around calling library routines, around calling various system services, and around calling code located in other protected or shareable images.
Loadable images and device drivers are images that can be used to add code into the OpenVMS kernel. Pseudo-device drivers are a particularly convenient way to add executable code, with associated driver-defined data structures, into the kernel. The pseudo-device driver includes the UCB and DDB data structures, and a calling interface with support for both privileged and unprivileged access to the driver code via sys$qio[w] calls.
A cookbook approach to creating OpenVMS shareable images is
available at the (admittedly overly long) URL:
http://www.openvms.compaq.com/wizard/
[Steve Hoffman]
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).
[Steve Hoffman]
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:
#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.
[Steve Hoffman]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:
http://www.hhs.dk/anonymous/pub/vms/misc/FORTRAN_C_CALL.COM
ftp://ftp.hhs.dk/pub/vms/misc/FORTRAN_C_CALL.COM
[Arne Vajhoej]
Under OpenVMS VAX and OpenVMS Alpha, the disk volume block size is consistent, with each block containing 512 bytes.
The minimum disk allocation granularity actually permissible (in the ODS-2 and ODS-5 volume structures commonly used on OpenVMS) is determined on a per-volume basis, and is typically based on a combination of the total number blocks on the disk volume and the total size of the volume storage bitmap. The allocation granularity is known as the volume cluster factor - the cluster factor is the number of blocks in a disk cluster, and it is the smallest number of blocks that can be allocated on a particular disk volume.
Prior to OpenVMS V7.2, the maximum permissible size of the bitmap requires larger cluster factors as volume sizes increase. Starting with V7.2, the bitmap can be larger, and cluster factors as small as one block can be used.
The number of bytes in a file can be determined by multiplying the number of blocks allocated for the file times the number of bytes in a block. For sequential files (only), the FFB (XAB$W_FFB, in the File Header XAB) value can be used to find out how much of the last (XAB$L_EBK) block is used. FFB and EBK are meaningful only for sequential files, and only in a limited context - partial block allocations are not permitted. For other file formats, the EOF marker is not meaningful.
Disk allocations always occur only in units of the cluster factors, which can be from one block up to (potentially) clusters of eighteen blocks or more, depending on the volume cluster factor.
OpenVMS assumes that the device driver and the underlying storage device will present the file system with addressable units of storage of 512 bytes in size, or the appearance of same. Various third-party CD-ROM devices, for instance, support only 2048 byte blocks, and such devices are incompatible with the standard OpenVMS device drivers.
To determine the number of bytes required for a file from DCL, one option uses the F$FILE_ATTRIBUTES item EOF, multiplied by the size of a block in bytes (512). This does not account for the unused space in the last block of a sequential file, but it also does not have to differentiate sequential files from other files.
[Steve Hoffman]
A memory page is the minimum unit of memory allocation in OpenVMS. With OpenVMS VAX, the memory page size matches the disk block size: it is always 512 bytes.
With OpenVMS Alpha, the memory page size is variable, and it can range from 8192 bytes (8 kilobytes) up to 64 kilobytes. The current system page size can be determined using the sys$getsyi or f$getsyi PAGE_SIZE item. Programs with hardcoded constants for the memory page size (or page alignment) should always assume a page size of 64 kilobytes.
On OpenVMS Alpha, a 512 byte area of memory - equivAlent in size to an OpenVMS VAX memory page - is refered to as a pagelet.
[Steve Hoffman]
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:
[Steve Hoffman]
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 propagated into the subprocess when sys$creprc is used, though when there is no CLI present in the process this (lack of) propagation 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.
[Stephen Hoffman]
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.BLI module:
!
! This is the OpenVMS VAX version of ARCH_DEFS.BLI, and
! contains the architectural definitions for conditionally
! compiling OpenVMS Bliss sources for use on VAX systems.
!
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*
!
! A more appropriate definition can only be used with versions
! of the Bliss compilers that understand the 32E/64E flags.
! %BLISS(BLISS32E) OR %BLISS(BLISS64E)%; ! = 0 if compiled /VAX
NOT %BLISS(BLISS32V)%; ! = 0 if compiled /VAX
MACRO ADDRESSBITS =
%BPADDR%; ! = 32 or 64 based on compiler used
[Stephen Hoffman]
A C source example that demonstrates how to do this is available in topic 2867 in the OpenVMS Ask The Wizard area:
http://www.openvms.compaq.com/wizard/
Depending on the environment, you may need to use C calls
such as fsync and fflush, and - in specific cases - the
setvbuf(_IONBF) call.
[Stephen Hoffman]
| Next | Back |