Updated: 11 December 1998 |
OpenVMS Programming Interfaces: Calling a System
Routine
Previous | Contents | Index |
Example 4-8 System Service Call in Pascal |
---|
[INHERIT('SYS$LIBRARY:STARLET', (1) 'SYS$LIBRARY:PASCAL$LIB_ROUTINES')] PROGRAM ORION (OUTPUT); TYPE Item_List_Cell = RECORD CASE INTEGER OF (2) 1:( { Normal Cell } Buffer_Length : [WORD] 0..65535; Item_Code : [WORD] 0..65535; Buffer_Addr : UNSIGNED; Return_Addr : UNSIGNED ); 2:( { Terminator } Terminator : UNSIGNED ); END; Item_List_Template(Count:INTEGER) = ARRAY [1..Count] OF Item_List_Cell; VAR Item_List : Item_List_Template(2); Translated_Name : [VOLATILE] VARYING [255] OF CHAR; (3) Status : INTEGER; BEGIN { Specify the buffer to return the translation } (4) Item_List[1].Buffer_Length := SIZE(Translated_Name.Body); Item_List[1].Item_Code := LNM$_String; Item_List[1].Buffer_Addr := IADDRESS(Translated_Name.Body); Item_List[1].Return_Addr := IADDRESS(Translated_Name.Length); { Terminate the item list } Item_List[2].Terminator := 0; { Translate the CYGNUS logical name } Status := $trnlnm(Tabnam := 'LNM$FILE_DEV', Lognam := 'CYGNUS', (5) Itmlst := Item_List); IF NOT ODD(Status) (6) THEN LIB$SIGNAL(Status) ELSE WRITELN('CYGNUS is equivalent to ',Translated_Name); END. |
Pascal Notes
Example 4-9 System Service Call in VAX MACRO |
---|
CYGDES: .ASCID /CYGNUS/ (1) ; Descriptor for CYGNUS string TBLDES: .ASCID /LNM$FILE_DEV/ (2) ; Logical name table NAMBUF: .BLKB 255 (3) ; Output buffer NAMLEN: .BLKW 1 (4) ; Word to receive length ITEMS: .WORD 255 ; Output buffer length .WORD LNM$STRING ; Item code .ADDRESS - ; Output buffer NAMBUF .ADDRESS - ; Return length NAMLEN .LONG 0 ; List terminator . . . .ENTRY ORION,0 (5) ; Routine entry point & mask $TRNLNM_S - (6) TABNAM=TBLDES, - LOGNAM=CYGDES, - ITMLST=ITEMS BLBC R0,ERROR (7) ; Check for error . . . .END |
VAX MACRO Notes
This chapter describes the libraries that contain C header files for
routines supplied by the OpenVMS Alpha operating system.
5.1 SYS$STARLET_C.TLB Equivalency to STARLETSD.TLB
The SYS$STARLET_C.TLB file, which was introduced in OpenVMS Alpha Version 1.0, contains all the .H files that provide STARLET functionality equivalent to STARLETSD.TLB. The file SYS$STARLET_C.TLB, together with DECC$RTLDEF.TLB that ships with the DEC C Compiler, replaces VAXCDEF.TLB that previously shipped with the VAX C Compiler. DECC$RTLDEF.TLB contains all the .H files that support the compiler and RTL, such as STDIO.H.
If you are running an application from a release prior to OpenVMS Alpha Version 1.0, the following differences may require source changes:
%CC-E-PASNOTMEM, In this statement, "rab$b_rac" is not a member of "rab". |
AlignFaultItem.PC[0] = DataPtr->afr$r_pc_data_overlay.afr$q_fault_pc[0]; |
AlignFaultItem.PC[0] = DataPtr->afr$q_fault_pc[0]; |
$ LIBRARY /EXTRACT=AFRDEF /OUTPUT=AFRDEF.H SYS$LIBRARY:SYS$STARLET_C.TLB |
As of OpenVMS Alpha Version 7.0, SYS$LIBRARY:SYS$STARLET_C.TLB (or STARLET) provides C function prototypes for system services, as well as new and enhanced data structure definitions. The new definitions are more consistent with the OpenVMS C language coding conventions and definitions (typedefs) used in SYS$LIBRARY:SYS$LIB_C.TLB.
In order to maintain source compatibility for existing users of STARLET.H, the "old style" function declarations and definitions are still provided by default. To take advantage of the new system service function prototypes and type definitions, you must explicitly enable them.
You can define the __NEW_STARLET symbol with a DEC C command line qualifier or include the definition directly in your source program. For example:
/DEFINE=(__NEW_STARLET=1) |
#define __NEW_STARLET 1 #include <starlet.h> #include <vadef.h> |
To see the currently available system service function prototypes in STARLET.H, you can use the Librarian utility as shown in the following example:
$ LIBRARY/OUTPUT=STARLET.H SYS$LIBRARY:SYS$STARLET_C.TLB/EXTRACT=STARLET |
The following example shows a new system service function prototype as it is defined in STARLET.H:
#pragma __required_pointer_size __long int sys$expreg_64( struct _generic_64 *region_id_64, unsigned __int64 length_64, unsigned int acmode, unsigned int flags, void *(*(return_va_64)), unsigned __int64 *return_length_64); #pragma __required_pointer_size __short |
For more information about DEC C pointer size pragmas, see the DEC C User's Guide for OpenVMS Systems.
The following source code example shows the sys$expreg_64 function prototype referenced in a program.
#define __NEW_STARLET 1 /* Enable "New Starlet" features */ #include <starlet.h> /* Declare prototypes for system services */ #include <gen64def.h> /* Define GENERIC_64 type */ #include <vadef.h> /* Define VA$ constants */ #include <ints.h> /* Define 64-bit integer types */ #include <far_pointers.h> /* Define 64-bit pointer types */ { int status; /* Ubiquitous VMS status value */ GENERIC_64 region = { VA$C_P2 }; /* Expand in "default" P2 region */ VOID_PQ p2_va; /* Returned VA in P2 space */ uint64 length; /* Allocated size in bytes */ extern uint64 page_size; /* Page size in bytes */ status = sys$expreg_64( ®ion, request_size, 0, 0, &p2_va, &length ); ... } |
Table 5-1 lists the data structures that are used by the new function protypes.
Structure Used by Prototype | Defined by Header File | Common Prefix for Structure Member Names | Description |
---|---|---|---|
struct _cluevthndl | cluevtdef.h | cluevthndl$ | Cluster event handle |
struct _fabdef | fabdef.h | fab$ | File access block |
struct _generic_64 | gen64def.h | gen64$ | Generic quadword structure |
struct _ieee | ieeedef.h | ieee$ | IEEE Floating point control structure |
struct _ile2 1 | iledef.h | ile2$ | Item list entry 2 |
struct _ile3 1 | iledef.h | ile3$ | Item list entry 3 |
struct _iosa | iosadef.h | iosa$ | I/O status area |
struct _iosb | iosbdef.h | iosb$ | I/O status block |
struct _lksb | lksbdef.h | lksb$ | Lock status block |
struct _rabdef | rabdef.h | rab$ | RMS record access block |
struct _secid | seciddef.h | secid$ | Global section identifier |
struct _va_range | va_rangedef.h | va_range$ | 32-bit virtual address range |
This appendix describes the use of generic macros to specify argument lists with appropriate symbols and conventions in the system services interface to MACRO assemblers.
System service macros generate argument lists and CALL instructions to call system services. These macros are located in the system library SYS$LIBRARY:STARLET.MLB. When you assemble a source program, this library is searched automatically for unresolved references.
Knowledge of VAX MACRO rules for assembly language programming is required for understanding the material presented in this appendix. The VAX MACRO and Instruction Set Reference Manual contains the necessary prerequisite information.
Each system service has four macros associated with it. These macros allow you to define symbolic names for argument offsets, construct argument lists for system services, and call system services. Table A-1 lists the generic macros and the functions they serve.
Macro | Function |
---|---|
$ nameDEF | Defines symbolic names for the argument list offsets. |
$ name | Defines symbolic names for the argument list offsets and constructs the argument list. |
$ name_S | Calls the system service and constructs the argument list. |
$ name_G | Calls the system service and uses the argument list constructed by $ name macro. |
A.1 Using Macros to Construct Argument Lists
You can use two generic macros for constructing argument lists for
system services:
The macro you use depends on which macro you are going to use to call
the system service. If you use the $name_G macro to call a
system service, you should use the $name macro to construct
the argument list. If you use the $name_S macro to call a
system service, you can also use it to construct the argument list.
A.1.1 Specifying Arguments with the $name_S Macro and the $name Macro
When you use the $name_S or the $name macro to construct an argument list for a system service, you can specify arguments in any one of three ways:
For example, $MYSERVICE can have the following format:
$MYSERVICE arga ,[argb] ,[argc] ,argd |
For purposes of this example, assume that arga and argb require you to specify numeric values and that argc and argd require you to specify addresses.
Examples A-1 and A-2 show valid ways of writing the $name_S macro to call $MYSERVICE.
Example A-1 Using Keywords with the$ name_S Macro |
---|
MYARGD: .LONG 100 . . . $MYSERVICE_S ARGB=#0,ARGC=0,ARGA=#1,ARGD=MYARGD |
Example A-2 Specifying Arguments in Positional Order with the$ name_S Macro |
---|
MYARGD: .LONG 100 . . . $MYSERVICE_S #1,,,MYARGD |
The argument list is pushed on the stack, as follows:
PUSHAL MYARGD PUSHL #0 PUSHL #0 PUSHL #1 |
Note that all arguments, whether specified positionally or with keywords, must be valid assembler expressions because they are used as source operands in instructions.
Examples A-3 and A-4 show valid ways of writing a $name macro to construct an argument list for a later call to $MYSERVICE.
Example A-3 Using Keywords with the$ name Macro |
---|
LIST: $MYSERVICE - ARGB=0, - ARGC=0, - ARGA=1, - ARGD=MYARGD |
Example A-4 Specifying Arguments in Positional Order with the$ name Macro |
---|
LIST: $MYSERVICE - 1,,,MYARGD |
Both methods generate the following:
LIST: .LONG 4 .LONG 1 .LONG 0 .LONG 0 .ADDRESS - MYARGD |
Note that all arguments, whether specified positionally or by keyword, must be expressions that the assembler can evaluate to generate .LONG or .ADDRESS data directives. Contrast this to the arguments for the $name_S macro, which must be valid assembler expressions because they are used as source operands in instructions.
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
5843PRO_007.HTML
|