HP OpenVMS Systems Documentation
Content starts here

DECwindows Motif for OpenVMS Guide to Non-C Bindings

DECwindows Motif for OpenVMS Guide to Non-C Bindings

January 1994

This guide supplies non-C bindings for programmers developing DECwindows Motif for OpenVMS applications in languages other than C. Pascal and Fortran are supported. Programmers can choose from among OSF/Motif and ancillary widgets supplied by Digital.

Revision/Update Information: This is a revised manual.

Operating System: OpenVMS AXP Version 1.5 VMS Version 5.5--2

Software Version: DECwindows Motif Version 1.2 for OpenVMS AXP DECwindows Motif Version 1.2 for OpenVMS VAX

Digital Equipment Corporation
Maynard, Massachusetts

January 1994

The information in this document is subject to change without notice and should not be construed as a commitment by Compaq Computer Corporation. Compaq Computer Corporation assumes no responsibility for any errors that may appear in this document.

The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license.

Copyright ©1994

The following are trademarks of Compaq Computer Corporation: Alpha AXP, AXP, Bookreader, DECwindows, Digital, OpenVMS, VAX, VAX DOCUMENT, VMS, and the DIGITAL logo.

The following are third-party trademarks:

Open Software Foundation is a trademark, and OSF/Motif and Motif are registered trademarks of the Open Software Foundation, Inc.

X Window System is a trademark of the Massachusetts Institute of Technology.

All other trademarks and registered trademarks are the property of their respective holders.

ZK5636

This document is available on CD-ROM.

This document was prepared using DECdocument, Version V3.3-1e.

Contents Index

Preface

Intended Audience

This manual is intended for programmers who develop DECwindows Motif applications in languages other than C. Use this guide in conjunction with the following reference manuals:

  • X Window System, third edition, provides detailed descriptions of each Xlib routine, as well as the Inter-Client Communication Conventions Manual (ICCCM), the X Logical Font Description Conventions, and the X Window System Protocol.
  • X Window System Toolkit provides reference information on the Intrinsics.
  • OSF/Motif Programmer's Reference provides reference information on the Motif Toolkit.
  • DECwindows Extensions to Motif provides reference information on the Digital extensions to Motif.

Document Structure

The bindings are presented in alphabetical order, followed by the associated routines in a separate chapter. This guide is divided into four parts and contains the following chapters:

Chapter 1---Introduction
Part 1 contains the following:
Chapter 2---Xlib Routines
Chapter 3---Xlib Data Structures and Error Codes
Part 2 contains the following:
Chapter 4---Intrinsics Routines
Chapter 5---Intrinsics Data Structures
Part 3 contains the following:
Chapter 6---OSF/Motif Toolkit Routines
Chapter 7---OSF/Motif Toolkit Data Structures
Part 4 contains the following:
Chapter 8---DECwindows Toolkit Extensions Routines
Chapter 9---DECwindows Toolkit Extensions Data Structures

Associated Documents

In addition to the reference information, see also:

  • X and Motif Quick Reference Guide provides quick reference information on Xlib, Intrinsics, and the Motif Toolkit.
  • DECwindows Motif Guide to Application Programming describes how to program with the Digital extensions to the Motif Toolkit. It supplements the OSF/Motif Programmer's Guide.
  • Porting XUI Applications to Motif describes how to port an existing XUI DECwindows application to Motif.
  • VMS DECwindows Guide to Xlib (Release 4) Programming: MIT C Binding describes how to program with Xlib using MIT C bindings.
  • VMS DECwindows Guide to Xlib (Release 4) Programming: VAX Binding describes how to program with Xlib using VAX bindings.
  • OSF/Motif Style Guide describes style guidelines for applications based on the Motif Toolkit.
  • OSF/Motif Programmer's Guide describes how to program with the Motif Window Manager, Motif Toolkit, and the Motif User Interface Language (UIL).

Conventions

The following conventions are used in this manual:

In this manual, every use of DECwindows and DECwindows Motif refers to DECwindows Motif for OpenVMS software.

In this manual, every use of OpenVMS AXP means the OpenVMS AXP operating system, every use of OpenVMS VAX means the OpenVMS VAX operating system, and every use of OpenVMS means both the OpenVMS AXP operating system and the OpenVMS VAX operating system.

Ctrl/ x A sequence such as Ctrl/ x indicates that you must hold down the key labeled Ctrl while you press another key or a pointing device button.
PF1 x A sequence such as PF1 x indicates that you must first press and release the key labeled PF1 and then press and release another key or a pointing device button.
GOLD x A sequence such as GOLD x indicates that you must first press and release the key defined as GOLD and then press and release another key. GOLD key sequences can also have a slash (/), dash (--), or underscore (_) as a delimiter in EVE commands.

The GOLD key definition is often mapped to the PF1 key on the keypad.

[Return] In examples, a key name enclosed in a box indicates that you press a key on the keyboard. (In text, a key name is not enclosed in a box.)
... Horizontal ellipsis points in examples indicate one of the following possibilities:
  • Additional optional arguments in a statement have been omitted.
  • The preceding item or items can be repeated one or more times.
  • Additional parameters, values, or other information can be entered.
.
.
. 		Vertical ellipsis points indicate the omission of items from a code example or command format; the items are omitted because they are not important to the topic being discussed.
( ) In command format descriptions, parentheses indicate that, if you choose more than one option, you must enclose the choices in parentheses.
[ ] In command format descriptions, brackets indicate optional elem You can choose one, none, or all of the options. (Brackets are not optional, however, in the syntax of a directory name in an OpenVMS file specification or in the syntax of a substring specification in an assignment statement.)
{ } In command format descriptions, braces surround a required choice of options; you must choose one of the options listed.
boldface text Boldface text represents the introduction of a new term or the name of an argument, an attribute, or a reason (user action that triggers a callback).

Boldface text is also used to show user input in Bookreader versions of the manual.

italic text Italic text emphasizes important information and indicates complete titles of manuals and variables. Variables include information that varies in system messages (Internal error number), in command lines (/PRODUCER= name), and in command parameters in text (where device-name contains up to five alphanumeric characters).
UPPERCASE TEXT Uppercase text indicates a command, the name of a routine, the name of a file, or the abbreviation for a system privilege.
struct Monospace type in text identifies the following C programming language elements: keywords, the names of independently compiled external functions and files, syntax summaries, and references to variables or identifiers introduced in an example.
- A hyphen in code examples indicates that additional arguments to the request are provided on the line that follows.
numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, oc hexadecimal---are explicitly indicated.
mouse The term mouse refers to any pointing device, such as a mouse, a puck, or a stylus.
MB1, MB2, MB3 MB1 indicates the left mouse button, MB2 indicates the middle mouse button, and MB3 indicates the right mouse button. (The user can redefine the buttons.)
PB1, PB2, PB3, PB4 PB1, PB2, PB3, and PB4 indicate buttons on the puck.
SB1, SB2, SB3 SB1, SB2, and SB3 indicate buttons on the stylus.

Chapter 1
Introduction

This manual provides OpenVMS documentation required by DECwindows programmers using languages other than C. This chapter outlines each section and element in the routine templates.

There are two separate routine templates, one for each binding format:

  • Standard OpenVMS bindings are supplied for Xlib routines; the template is described in Section 1.1.
  • The Intrinsics, OSF/Motif Toolkit, and Digital Extension Routines are in generic form; the language bindings files supply the language-specific form of each entry. The template for these routines is described in Section 1.2.

1.1 Xlib Routine Template

This section describes each element in the Xlib Routine template.

Routine Name

The generic name of the routine.

OpenVMS Format

The OpenVMS routine call format. The format syntax is summarized in Table 1-1.

Table 1-1 General Rules of Syntax
Element Syntax Rule
Routine entry point name The name is shown in all capital letters with the prefix X. The routine entry point name is required.
Equal sign For specific return values, the equal sign is required.
Parentheses Open and close parentheses surround the argument list in a routine call. Parentheses are required.
Argument names Argument names, including names of return arguments, are always shown in lowercase characters. All arguments not enclosed by brackets ([]) are required. Argument names must be listed in the same order in your program as they appear in the format.
Spaces A line break follows the entry point name and the arguments. A comma, followed by a space separate each argument. Spaces are not required.
Brackets Brackets ([]) surround optional arguments. Commas that appear inside brackets are optional and appear only when the optional argument appears. Brackets are not required.
Commas Commas must appear between required arguments. When commas appear inside brackets ([]), they appear only when the optional argument appears.

Argument Information

A table follows the OpenVMS format listing. The table lists, in order, each argument name, usage, data type, access, and mechanism.

Usage

The Usage column specifies the general OpenVMS binding argument type. For example, if the argument is a resource identifier, the Usage field is "identifier." This field provides additional information about the argument that is helpful when declaring the argument within a program. See Table 1-2 for a list of usage entries used in Xlib routines.

Table 1-2 OpenVMS Usage Entries
Entry Description
address An unsigned longword containing the virtual address of data or code, but not of a procedure entry mask (which is a procedure entry).
any An unsigned longword containing either data or a pointer to data.
array An array with the specific description of its elements provided in the argument description.
Boolean An unsigned longword with the predefined values of 1 for true and 0 for false.
byte A signed byte integer.
uns byte An unsigned byte integer.
char string A string of 0 to 65,535 8-bit characters.
cond value Unsigned longword specifying that a predefined condition value will be returned in R0.

The cond value status return is SS$_NORMAL for success; the return value can be either zero or an OpenVMS condition code for failure.

identifier A value used to refer to a resource. It is originally returned by the system. In the OpenVMS binding, an identifier is a longword integer (unsigned).
longword A signed longword integer.
uns longword An unsigned longword integer.
mask longword An unsigned longword interpreted as a bit mask.
procedure An entry mask to a procedure.
record A data structure with the specific description of the structure provided in the argument description.
word A signed word integer.
uns word An unsigned word integer.

Data Type

The Data Type column specifies the standard OpenVMS data type of the argument. For example, if the argument is a resource identifier, the data type is "longword (unsigned)." If the argument has a predefined value, it is provided in the description of the argument.

The following OpenVMS data type entries are used in the Xlib routines:

  • byte
  • character string
  • longword
  • longword (unsigned), notated as uns longword
  • proc entry mask
  • vector (unsigned) longword, notated as v uns longword
  • vector (unsigned) byte, notated as v uns byte
  • word (signed)
  • word (unsigned), notated as uns word
  • Name of an OpenVMS data structure. These are valid OpenVMS data structure names that can appear in this column (see Chapter 3 for more information about OpenVMS data structures):
    x$any_event x$keyboard_control
    x$arc x$keyboard_state
    x$button_event x$keymap_event
    x$char_2b x$map_event
    x$char_struct x$map_request_event
    x$circ_request_event x$mapping_event
    x$circulate_event x$modifier_keymap
    x$class_hint x$motion_event
    x$clie_message_event x$no_expose_event
    x$color x$point
    x$colormap_event x$property_event
    x$compose_status x$rectangle
    x$conf_request_event x$reparent_event
    x$configure_event x$resource_req
    x$creat_window_event x$resz_request_event
    x$crossing_event x$rm_value
    x$depth x$screen
    x$destr_window_event x$screen_format
    x$display x$segment
    x$error_event x$sel_request_event
    x$event x$select_clear_event
    x$expose_event x$selection_event
    x$ext_codes x$set_win_attributes
    x$ext_data x$size_hints
    x$focus_change_event x$standard_colormap
    x$font_prop x$text_item
    x$font_struct x$text_item_16
    x$frame x$text_property
    x$gc_struct x$time_coord
    x$gc_values x$unmap_event
    x$graph_expose_event x$visibility_event
    x$gravity_event x$visual
    x$host_address x$visual_info
    x$icon_size x$window_attributes
    x$image x$window_changes
    x$key_event x$wm_hints

Access

The Access column specifies the way in which the called routine accesses the argument. For example, when the argument is passed as input, the access is "read only" for both bindings and when the argument is returned by the routine, the access is "write only" for both bindings. See Table 1-3 for a list of access entries used in the Xlib routines.

Table 1-3 Access Entries
Entry Description
read Input data required by the routine to perform its operation must be readable. When an argument specifies input data, the access entry is readable. The routine cannot write data back to this argument.
write Output data returned by the routine to a specific location. When an argument specifies output data, the access entry is writable. The routine does not read the contents of the location either before or after it writes into the location.
modify The routine reads the input data, which it uses in its operation, and then overwrites the input data with the results (the output data) of the operation. Thus, when the routine completes execution, the input data specified by the argument is lost.

Mechanism

The Mechanism column specifies the passing mechanism used by the called routine. For example, when the argument is the value itself, the mechanism is "by value"; when the argument is a pointer to the value, the mechanism is "by reference." See Table 1-4 for a complete list of mechanism entries used in the Xlib routines.

Table 1-4 Mechanism Entries
Entry Description
value The argument contains the actual data to be used by the routine. Note that because an argument is only one longword in length, only data that can be represented in one longword can be passed by value.
reference The argument contains the address of the data to be used by the routine. The argument is a pointer to the actual data.
descriptor The argument contains the address of a descriptor. A descriptor consists of two or more longwords (depending on the type of descriptor used), which describes the location, length, and the OpenVMS standard data type of the data to be used by the called routine. The argument is a pointer to a descriptor that itself is a pointer to the actual data.

Next Contents Index