HP OpenVMS Systems Documentation

OpenVMS Programming Concepts Manual

1. The module $SYSSRVNAM in the FORTRAN system default library FORSYSDEF.TLB contains INTEGER and EXTERNAL declarations for each of the system services, so you need not explicitly provide these declarations in your program. Module $LNMDEF defines constants and data structures used when calling the logical name services, and module LIB$ROUTINES contains declarations for the LIB$ Run-Time Library routines.
2. The structure of an OpenVMS 3-longword item list is declared and then used to define the record variable ITEM_LIST. The second element will be used for the terminator.
3. The VOLATILE declaration is required for variables that are modified by means other than a direct assignment or as an argument in a routine call.
4. Return status variables should always be declared as longword integers.
5. The LEN intrinsic function returns the allocated length of EQUIV_NAME. The %LOC built-in function returns the address of its argument.
6. By default, FORTRAN passes arguments by reference, except for strings which are passed by CLASS_S descriptor. Arguments are omitted in FORTRAN by leaving the comma as a placeholder. All arguments must be specified or explicitly omitted.
7. A condition value can be tested for success or failure by a true/false test. For more information on testing return statuses, see the OpenVMS FORTRAN documentation.

[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

1. The Pascal environment file STARLET.PEN defines OpenVMS system services, data structures and constants. PASCAL$LIB_ROUTINES declares the LIB$ Run-Time Library routines.
2. The structure of an item list entry is defined using a variant record type.
3. The VARYING OF CHAR type is a variable-length character string with two components: a word-integer length and a character string body, which in this example is 255 bytes long. The VOLATILE attribute is required for variables that are modified by means other than a direct assignment or as an argument in a routine call.
4. The functions SIZE and IADDRESS obtain the allocated size of the string body and the address of the string body and length. The returned length will be stored into the length field of the varying string Translated_Name, so that it will appear to be the correct size.
5. The definition of the SYS$TRNLNM routine in STARLET.PEN contains specifications of the passing mechanism to be used for each argument; thus, it is not necessary to specify the mechanism here.
6. The IF statement performs a logical test following the function reference to see if the service completed successfully. If an error or warning occurs during the service call, the error is signaled.

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

1. The input character string descriptor argument is defined using the .ASCID directive.
2. The name of the table to search is defined using the .ASCID directive.
3. Enough bytes to hold the output data are allocated for an output character string argument.
4. The MACRO directive .BLKW reserves a word to hold the output length.
5. A routine name and entry mask show the beginning of executable code in a routine or subroutine.
6. A macro name that has the suffix _S or _G calls the service.
   You can specify arguments either by keyword (as in this example) or by positional order. (Keyword names correspond to the names of the arguments shown in lowercase in the system service format descriptions in the OpenVMS System Services Reference Manual.) If you omit any optional arguments (if you accept the defaults), you can omit them completely if you specify arguments by keyword. If you specify arguments by positional order, however, you must specify the comma for each missing argument.
   Use the number sign (#) to indicate a literal value for an argument.
7. The BLBC instruction causes a branch to a subroutine named ERROR (not shown) if the low bit of the condition value returned from the service is clear (low bit clear = failure or warning). You can use a BSBW instruction to branch unconditionally to a routine that checks the return status.

This chapter describes the libraries that contain C header files for routines supplied by the OpenVMS Alpha operating system.

21.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 Compaq 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:

• RMS structures
  Previously, the RMS structures FAB, NAM, RAB, XABALL, and so forth, were defined in the appropriate .H files as "struct RAB {...", for example. The .H files supplied in OpenVMS Alpha Version 1.0 define them as "struct rabdef {...". To compensate for this difference, lines of the form "#define RAB rabdef" have been added. However, there is one situation where a source change is required because of this change. If you have a private structure that contains a pointer to one of these structures and your private structure is defined (but not used) before the RMS structure has been defined, you will receive compile-time errors similar to the following:

  %CC-E-PASNOTMEM, In this statement, "rab$b_rac" is not a member of "rab".

  
  This error can be avoided by reordering your source file so that the RMS structure is defined before the private structure. Typically, this involves moving around "#include" statements.
• LIB (privileged interface) structures
  Historically, three structures from LIB (NFBDEF.H, FATDEF.H, and FCHDEF.H) have been made available as .H files. These files were shipped as .H files in OpenVMS Alpha Version 1.0 and 1.5 (not in the new SYS$STARLET_C.TLB). As of OpenVMS Alpha Version 1.0, the file SYS$LIB_C.TLB, containing all LIB structures and definitions, has been added. These three .H files are now part of that .TLB and are no longer shipped separately. Source changes may be required, because no attempt has been made to preserve any existing anomalies in these files. The structures and definitions from LIB are for privileged interfaces only and are therefore subject to change.
• Use of "variant_struct" and "variant_union" In the new .H files, variant_struct and variant_union are always used; whereas previously some structures used struct and union. Therefore, the intermediate structure names cannot be specified when referencing fields within data structures.
  For example, the following statement:

  AlignFaultItem.PC[0] = DataPtr->afr$r_pc_data_overlay.afr$q_fault_pc[0];

  
  becomes:

  AlignFaultItem.PC[0] = DataPtr->afr$q_fault_pc[0];

• Member alignment
  Each of the .H files in SYS$STARLET_C.TLB saves and restores the state of "#pragma member_alignment".
• Conventions The .H files in SYS$STARLET_C.TLB adhere to some conventions that were only partly followed in VAXCDEF.TLB. All constants (#defines) have uppercase names. All identifiers (routines, structure members, and so forth) have lowercase names. Where there is a difference from VAXCDEF.TLB, the old symbol name is also included for compatibility, but users are encouraged to follow the new conventions.
• Use of Librarian utility to access the .H files
  During installation of OpenVMS Alpha Version 1.0, the contents of SYS$STARLET_C.TLB are not extracted into the separate .H files. The Compaq C Compiler accesses these files from within SYS$STARLET_C.TLB, regardless of the format of the #include statement. If you want to inspect an individual .H file, you can use the Librarian utility, as in the following example:

  $ LIBRARY /EXTRACT=AFRDEF /OUTPUT=AFRDEF.H SYS$LIBRARY:SYS$STARLET_C.TLB

• Additional .H files included in SYS$STARLET_C.TLB
  In addition to the .H files derived from STARLET sources, SYS$STARLET_C.TLB includes .H files that provide support for POSIX Threads Library, such as CMA.H.

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.

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 Compaq C command line qualifier or include the definition directly in your source program. For example:

• Define the _NEW_STARLET symbol with the Compaq C command line qualifier as follows:

  /DEFINE=(__NEW_STARLET=1)

  
  or
• Define the _NEW_STARLET symbol in your C source program before including the SYS$STARLET_C.TLB header files:

  #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 Compaq 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( &region, request_size, 0, 0, &p2_va, &length );
    ...

}

Table 21-1 lists the data structures that are used by the new function protypes.

This chapter describes the different I/O programming capabilities provided by the run-time library and illustrates these capabilities with examples of common I/O tasks. This chapter contains the following sections:

Section 22.1 describes the input and output operations within a program.

Section 22.2 describes using SYS$INPUT and SYS$OUTPUT.

Section 22.3 describes using LIB$GET_INPUT and LIB$PUT_OUTPUT for simple user I/O.

Section 22.4 describes using the SMG$ run-time library routines for managing the appearance of terminal screens.

Section 22.5 describes using screen management input routines and the SYS$QIO and SYS$QIOW system services to perform special actions.

22.1 Choosing I/O Techniques

The operating system and its compilers provide the following methods for completing input and output operations within a program:

• DEC Text Processing Utility
• DECforms software
• Program language I/O statements
• OpenVMS Record Management Services (RMS) and Run-Time Library (RTL) routines
• SYS$QIO and SYS$QIOW system services
• Non-Compaq-supplied device drivers to control the I/O to the device itself

The DEC Text Processing Utility (DECTPU) is a text processor that can be used to create text editing interfaces. DECTPU has the following features:

• High-level procedure language with several data types, relational operators, error interception, looping, case language statements, and built-in procedures
• Compiler for the DECTPU procedure language
• Interpreter for the DECTPU procedure language
• Extensible Versatile Editor (EVE) editing interface which, in addition to the EVE keypad, provides EDT, VT100, WPS, and numeric keypad emulation

In addition, DECTPU offers the following special features:

• Multiple buffers
• Multiple windows
• Multiple subprocesses
• Text processing in batch mode
• Insert or overstrike text entry
• Free or bound cursor motion
• Learn sequences
• Pattern matching
• Key definition

The method you select for I/O operations depends on the task you want to accomplish, ease of use, speed, and level of control you want.

The Compaq DECforms for OpenVMS software is a forms management product for transaction processing. DECforms integrates text and graphics into forms and menus that application programs use as an interface to users. DECforms software offers application developers software development tools and a run-time environment for implementing interfaces.

DECforms software integrates with the Application Control and Management System (ACMS), a transaction process (TP) monitor that works with other Compaq commercial applications to provide complete customizable development and run-time environments for TP applications. An asynchronous call interface to ACMS allows a single DECforms run-time process to control multiple terminals simultaneously in a multithreaded way, resulting in an efficient use of memory. By using the ACMS Remote Access Option, DECforms software can be distributed to remote CPUs. This technique allows the host CPU to offload forms processing and distribute it as closely as possible to the end user.

In contrast to OpenVMS RMS, RTLs, SYS$QIOs, and device driver I/O, program language I/O statements have the slowest speed and lowest level of control, but they are the easiest to use and are highly portable.

OpenVMS RMS and RTL routines can perform most I/O operations for a high-level or assembly language program. For information about OpenVMS RMS, see the OpenVMS Record Management Services Reference Manual.

System services can complete any I/O operation and can access devices not supported within OpenVMS RMS. See Chapter 23 for a description of using I/O system services.

Writing a device driver provides the most control over I/O operations, but can be more complex to implement. For information about device drivers for VAX systems, see the OpenVMS VAX Device Support Manual. The OpenVMS VAX Device Support Manual has been archived but is available on the OpenVMS Documentation CD-ROM.

Several types of I/O operations can be performed within a program, including the following:

• RTL routines allow you either to read simple input from a user or send simple output to a user. One RTL routine allows you to specify a string to prompt for input from the current input device, defined by SYS$INPUT. Another RTL routine allows you to write a string to the current output device, defined by SYS$OUTPUT. See Section 22.2 and Section 22.3 for more information.
• RTL routines allow you either to read complex input from a user or to send complex output to a user. By providing an extensive number of screen management (SMG$) routines, the RTL allows you either to read multiple lines of input from users or to send complex output to users. The SMG$ routines also allow you to create and modify complicated displays that accept input and produce output. See Section 22.4 for more information.
• RTL routines allow you to use programming language I/O statements to send data to and receive data from files. Program language I/O statements call OpenVMS RMS routines to complete most file I/O. You can also use OpenVMS RMS directly in your programs for accomplishing file I/O. See Chapter 28 for more information.
• The SYS$QIO and SYS$QIOW system services allow you to send data to and from devices with the most flexibility and control. You can use system services to access devices not supported by your programming language or by OpenVMS RMS.
  You can perform other special I/O actions, such as using interrupts, controlling echo, handling unsolicited input, using the type-ahead buffer, using case conversion, and sending sytem broadcast messges, by using SMG$ routines or, for example, by using SYS$BRKTHRU system service to broadcast messages. See Section 22.5 for more information.