=;The OpenVMS Frequently Asked Questions (FAQ)D

The OpenVMS Frequently Asked Questions (FAQ)



 r \ ^  
PreviousContentsIndex




M

Chapter 10
OpenVMS Programming Information


A

If you are searching for something here, please (consider using the text-format FAQ.

x

10.1 Modular Programming, Facility Prefixes and Symbol Naming?



DPlease first review the OpenVMS Programming Concepts Manual and the DGuide to Modular Programming manuals. Both are available within the EOpenVMS documentation set, and provide details of the expected norms for OpenVMS programs.



BOpenVMS provides a registry for facility prefixes and for MESSAGE Hmessage compiler codes. To request a prefix and a message facility code Cfor a product you distributinng to other customer sites, send your 'request in a mail message addressed to Dproduct[-at-sign-]hylndr.sqp.zko.dec.com, requesting the submission -form and details of the registration process.



/  
Note

HPlease do not request facility prefixes for products that local to your Cbusiness, your site, or your system. Facility prefixes and message Gcodes and the facility registration process are intended solely for HP Hproducts and Partner Products (and yes, even OpenVMS Freeware packages) Hthat will be distributed across multiple OpenVMS customer sites.


CFor a list of common coding bugs, please see the remainder of this ksection of the FAQ and specifically Section 10.22, please also see the AAsk The Wizard topic (1661), and for information on debugging an -OpenVMS application, please see topic (7552).



HFor additional information on the OpenVMS Ask The Wizard (ATW) area and Bfor a pointer to the available ATW Wizard.zip archive, please see iSection 3.8. ATW has been superceded (for new questions) by the ITRC <discussion forums; the area remains available for reference.k

10.2 Can I have a source code example of calling...?



HPlease use the available SEARCH command on OpenVMS, and please remember Gto search the available resources, including the support databases and Ethe newsgroup archives. Please also realize that most OpenVMS system Cservices use similar calling sequences, meaning that an example of @calling sys$getjpi can be used as an example for sys$getsyi and >sys$getdvi. Students: please do not expect folks to write your*homework for you. As for search resources:



BOpenVMS programming documentation, including the numerous example Aprograms found in recent versions of the OpenVMS Programming #Concepts manual, is available:



EAs for details of argument passing, most OpenVMS system services and BRTL routines pass string arguments by descriptor. Languages which Csupport native string data types create descriptors automatically; Ethose which do not (eg., C) require that you set them up explicitly. DFor further details on using descriptors and particularly for using Rdescriptors from C, please see Section 10.13.

GThere is extensive information available on how to call OpenVMS system Fservices and OpenVMS Run-Time Library routines, including examples in <numerous languages. Among the best available references are:



CIn addition, you can also locate answers, source code examples and Arelated discussions in the James Search Assistant (formerly NLSA B(Natural Language Search Assistant), itself formerly known as Ask Compaq (AskQ)) database:



CIn this area, you will find the source code of programming examplesCfor calls to many of the OpenVMS system services (and from various Hprogramming languages), including calls to core services sys$getjpi[w], Hsys$getsyi[w] and sys$qio[w], as well as source code examples for calls Ato many other system services and run-time library routines, and Bexamples of one of the more difficult calling interfaces found on 5OpenVMS systems, that of the smg$create_menu routine.

DArne Vajhøj has put together a collection of OpenVMS example programs. It can be found at:



BAdditional information and examples for OpenVMS are available via:



HFor additional information on the OpenVMS Ask The Wizard (ATW) area and Bfor a pointer to the available ATW Wizard.zip archive, please see iSection 3.8. ATW has been superceded (for new questions) by the ITRC <discussion forums; the area remains available for reference.and via:

m

10.3 How do I get the arguments from the command line?



HIf you're writing a program and want to accept arguments from a foreign Gcommand, you can use LIB$GET_FOREIGN to get the command line and parse Eit yourself, or if you're programming in C, use the normal argc/argv method.

2To write an application which uses the normal DCL Gverb/qualifier/parameter syntax for invocation, see the description of Ethe CLI$ routines in the OpenVMS Callable Utility Routines Reference Manual.

GIt is possible to write an application which can be used both ways; if Fa DCL verb isn't used to invoke the image, the application parses the Gcommand 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.

8See also Section 8.2.q

10.4 How do I get a formatted error message in a variable?



EUse the SYS$PUTMSG system service with an action routine that stores Gthe message line(s) in the variable of your choice. Be sure the action Aroutine returns a "false" (low bit clear) function value so that SYS$PUTMSGEdoesn't then try to display the message (unless you want it to.) See Gthe description of $PUTMSG in the System Services Reference Manual for &an example of using an action routine.x

10.5 How do I link against SYS$SYSTEM:SYS.STB on an Alpha system?



GLINK/SYSEXE is the OpenVMS Alpha equivalent of linking against SYS.STB.5This links against the base image: SYS$BASE_IMAGE.EXE

iAlso see Section 10.11, particularly for pointers to the details on ishareable images and shareable image creation, and see Section 10.22 ?for details of inner-mode floating point requirements, of data @alignment, requirements for use of /NOSYSLIB, and other related minner-mode programming details, and see Section 10.11 for image-related information.l

10.6 How do I do a SET DEFAULT from inside a program?



EThe problem is that SYS$SETDDIR only changes the default directory - DNOT the default disk. The default disk is determined by the logical HSYS$DISK. If you want to change the default disk within a program, then Fcall LIB$SET_LOGICAL to change the logical SYS$DISK. You will need to Fcall both LIB$SET_LOGICAL and SYS$SETDDIR to change both default disk and the default directory!|

10.7 How do I turn my Fortran COMMON into a shareable image on Alpha?



BYou need to add SYMBOL_VECTOR=(<common-name>=PSECT) to your Goptions file. On OpenVMS VAX all OVR/REL/GBL psects were automatically Dexported into the shareable image's Global Symbol Table. On OpenVMS FAlpha you have to tell the linker that you want this done by means of >the PSECT keyword in the SYMBOL_VECTOR options file statement.

GThis has several advantages over OpenVMS VAX. First, you don't have to Cworry about the address of the psect when you try to create a new, Dupwardly compatible version of the shareable image. Second, you can Econtrol which psects, if any, are made visible outside the shareable image.

FBy default, COMMON PSECTs in HP Fortran for OpenVMS Alpha (as well as Gmost other OpenVMS Alpha compilers) are NOSHR. On VAX, the default was FSHR which required you to change the attribute to NOSHR if you wanted Cyour 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 




Fin the Fortran source code (the CDEC$ must be begin in column 1) or a Alinker options file PSECT_ATTR statement to set the COMMON PSECT attribute to SHR.

/For further information, see the Linker manual.p

10.8 How do I convert between IEEE and VAX floating data?



GIn OpenVMS V6.1 and later, the routine CVT$CONVERT_FLOAT is documented Hin the LIB$ Run-Time Library Reference Manual, and can perform floating Gpoint conversions between any two of the following floating datatypes: EVAX (F,D,G,H), little-endian IEEE (single, double, quad), big-endian :IEEE (single, double, quad), CRAY and IBM System\370, etc.

DHP Fortran (all OpenVMS platforms) has a feature which will perform Eautomatic conversion of unformatted data during input or output. See Dthe HP Fortran documentation for information on "non-native data in -I/O" and the CONVERT= OPEN statement keyword.

GThere are floating-point conversion source code packages available for various platforms.

4For further floating-point related information, see:

q

10.9 How do I get the argument count in a Fortran routine?



FOn VAX, many programmers would use a MACRO routine which accessed the AP registerDof the caller to get the address of the argument list and hence the Dargument count. This was not guaranteed to work on VAX, but usually Fdid. However, it doesn't work at all on OpenVMS Alpha, as there is no BAP register. On Alpha systems, you must use a language's built-in Dfunction to retrieve the argument count, if any. In Fortran this is AIARGCOUNT, which is also available in DEC Fortran on OpenVMS VAX.

HNote that omitting arguments to Fortran routines is non-standard and is Gunsupported. It will work in many cases - read the DEC Fortran release !notes for additional information.u

10.10 How do I get a unique system ID for licensing purposes?



?Many software developers desire to use a unique hardware ID to E"lock" a given copy of their product to a specific system. =Most VAX and Alpha systems do not have a unique hardware-set D"system ID" that can be used for this purpose. HP OpenVMS Cproducts do not use hardware IDs in the licensing methods, as many @users consider a hardware-based licensing scheme to be negative .attribute when considering software purchases.

FHP OpenVMS uses a software-based system called the License Management GFacility (LMF). This provides for software keys (Product Authorization FKeys or PAKS) which support capacity and user-based license checking. DHP offers an LMF PAK Generator to DSPP (formerly CSA) members---see kSection 2.8.3 for general details on the DSPP offerings, and on the GDSPP-provided Freeware PAKGEN PAK that is available for those that are Einterested in details. (Sorry, no; you can't use the Freeware PAKGEN DPAK to generate any PAK you might want. Folks at HP also thought of that one, too.)

[For information on licensing, please see Section 12.4.

HHowever, if a hardware-based method is required, the most common method Eis based on an Ethernet adaptor hardware address. Sample source code &for implementing this is available at:



HFor additional information on the OpenVMS Ask The Wizard (ATW) area and Bfor a pointer to the available ATW Wizard.zip archive, please see iSection 3.8. ATW has been superceded (for new questions) by the ITRC <discussion forums; the area remains available for reference.u

10.11 What is an executable, shareable, system or UWSS image?



GExecutable code in OpenVMS typically resides in an image---an image is Ca file---the file extension is typically .EXE---that contains this Bcode. Common types of images include executable images, shareable 3images, system images, and protected (UWSS) images.

DExecutable images are programs that can be directly executed. These 5images can grant enhanced privileges, with an INSTALLJ of the image with /PRIVILEGE, or can grant enhanced access with the M specification of a subsystem identifier on the ACL associated with the image.

DShareable images contain code executed indirectly, these images are Freferenced from executable images and/or from other shareable images. EThese images can not grant enhanced privileges, even with the use of INSTALL with /PRIVILEGEL 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.H (See `protected images' for information on `privileged shareable  images'.)

?System images are intended to run directly on the VAX or Alpha Fhardware---these are normally used for the kernel code that comprises an operating system.

CProtected images---also refered to as User-Written System Services F(UWSS), or as privileged shareable images---are similiar in some ways Cto a standard shareable images, but these images include a `change Dmode' handler, and execute in an `inner' processor mode (privileged Bmode; executive or kernel), and code executing in inner modes has Fimplicit SETPRV privilege. Must be INSTALLed with /PROTECT. Note that Binner-mode code has restrictions around calling library routines, Haround calling various system services, and around calling code located 'in other protected or shareable images.

FLoadable images and device drivers are images that can be used to add Gcode into the OpenVMS kernel. Pseudo-device drivers are a particularly Fconvenient way to add executable code, with associated driver-defined Hdata 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.

FA cookbook approach to creating OpenVMS shareable images is available at the URL:



HFor additional information on the OpenVMS Ask The Wizard (ATW) area and Bfor a pointer to the available ATW Wizard.zip archive, please see iSection 3.8. ATW has been superceded (for new questions) by the ITRC <discussion forums; the area remains available for reference.e

10.12 How do I do a file copy from a program?



DThere are several options available for copying files from within a >program. Obvious choices include using lib$spawn(), system(), Hsys$sndjbc() or sys$creprc() to invoke a DCL COPY command. Other common Halternatives include using the callable convert routines and the BACKUP 3application programming interface (V7.1 and later).S

10.13 What is a descriptor?



FA descriptor is a data structure that describes a string or an array. DEach descriptor contains information that describes the type of the Ddata being referenced, the size of the data, and the address of the Gdata. It also includes a description of the storage used for the data, Atypically static or dynamic. Descriptors are passed by reference.

HThe following are examples of creating and using descriptors in C, with Athe use of the angle brackets normally expected by the C include 5statements 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; 




HStatic descriptors reference storage entirely under application program Bcontrol, and the contents of the descriptor data structure can be Cmodified as required (by the application). OpenVMS routines do not Bmodify the contents of a static descriptor, nor do they alter the Daddress 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.)

HDynamic descriptors reference storage under the control of the run-time Hlibrary, and the contents of a dynamic descriptor data structure---once Einitialized---can only be modified under control of run-time library Froutines. The dynamic storage referenced by the dynamic descriptor is Callocated and maintained by the run-time library routines. Various >OpenVMS routines do alter the contents of the descriptor data Dstructure, changing the value for the amount and the address of the Fstorage associated with the dynamic descriptor, as required. Routines Fcan obviously access and alter the contents of the storage referenced by the descriptor.

AOpenVMS languages that include support for strings or arrays are Gexpected to use descriptors for the particular structure. Most OpenVMS ?languages, such as Fortran and BASIC, use descriptors entirely Ftransparently. Some, like DEC C, require the programmer to explicitly #create and maintain the descriptor.

CFor further information on string descriptors, see the OpenVMS HProgramming Concepts manual, part of the OpenVMS documentation set.

DFortran defaults to passing integers by reference and characters by Ddescriptor. The following sites discuss mixing Fortran and C source code in the same application:

o

10.14 How do I create a process under another username?



HMany server processes can operate within the context of the target user Gusing privileges, using calls such as sys$chkpro and (more commonly in Fthis context) sys$check_access as needed to determine if access would Fbe permitted for the specified user within the current security model.

9With OpenVMS V6.2 and later, the persona system services C(SYS$PERSONA_*) can be used to assume the persona of the specified Euser---these allow the server to operate as the specified user, in a Dcontrolled fashion. The persona services can be used as a "wrapper" Haround a sys$creprc process creation call, as well---this will create a 4seperate process entirely under the assumed persona.

FInformation on the persona system services is included in the OpenVMS CV6.2 new features documentation, and in the OpenVMS V7.1 and later Csystem services documentation. These system services exist and are -supported in OpenVMS V6.2 and later releases.

ATypical mechanisms for creating a process under another username include:



DThere are likely a few other mechanisms around... There are various Ftools available from DECUS and other sources that allow various forms 9of user impersonation, as well. These tools will require Fversion-dependent kernel code and enhanced privileges for some of (or all of) their operations.




 r Y \ ^  
PreviousNextContentsIndex