OpenVMS Utility Routines Manual

Document revision date: 30 March 2001

OpenVMS Utility Routines Manual

Order Number: AA--PV6EE--TK

April 2001

This manual describes the OpenVMS utility routines, a set of routines that provides a programming interface to various OpenVMS utilities.

Revision/Update Information: This manual supersedes the OpenVMS Utility Routines Manual, OpenVMS Version 7.2.

Software Version: OpenVMS Alpha Version 7.3 OpenVMS VAX Version 7.3

Compaq Computer Corporation
Houston, Texas

Compaq, VAX, VMS, and the Compaq logo Registered in U.S. Patent and Trademark Office.

OpenVMS is a trademark of Compaq Information Technologies Group, L.P. in the United States and other countries.

All other product names mentioned herein may be the trademarks or registered trademarks of their respective companies.

Confidential computer software. Valid license from Compaq required for possession, use, or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is provided "as is" without warranty of any kind and is subject to change without notice. The warranties for Compaq products are set forth in the express limited warranty statements accompanying such products. Nothing herein should be construed as constituting an additional warranty.

ZK4493

The Compaq OpenVMS documentation set is available on CD-ROM.

Contents Index

Preface

Intended Audience

This manual is intended for programmers who want to invoke and use the functions provided by OpenVMS utilities.

Document Structure

Chapter 1 introduces the utility routines and lists the documentation format used to describe each set of utility routines, as well as the individual routines in each set. Each subsequent chapter contains an introduction to a set of utility routines, a programming example to illustrate the use of the routines in the set, and a detailed description of each routine.

This manual presents the utility routine sets as follows:

Access Control List (ACL) editor routine
Backup (BACKUP) routine
Command Language Interface (CLI) routines
Common File Qualifier routines
Convert (CONVERT) routines
Data Compression/Expansion (DCX) routines
DEC Text Processing Utility (DECTPU) routines
EDT routines
File Definition Language (FDL) routines
Librarian (LBR) routines
Lightweight Directory Access Protocol (LDAP) routines

Note
Because the LDAP routines are a C language interface, this chapter is formatted differently than the other chapters.
LOGINOUT (LGI) routines
Mail utility (MAIL) routines
National character set (NCS) utility routines
Print Symbiont Modification (PSM) routines
Symbiont/Job Controller Interface (SMB) routines
Sort/Merge (SOR) routines

Reader's Comments

Compaq welcomes your comments on this manual. Please send comments to either of the following addresses:

Internet openvmsdoc@compaq.com

Mail Compaq Computer Corporation
OSSG Documentation Group, ZKO3-4/U08
110 Spit Brook Rd.
Nashua, NH 03062-2698

How To Order Additional Documentation

Use the following World Wide Web address to order additional documentation:

http://www.openvms.compaq.com/

If you need help deciding which documentation best meets your needs, call 800-282-6672.

Conventions

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

The following conventions are also used in this manual:

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.

[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 elements. 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 indicate a required choice of options; you must choose one of the options listed.

bold text Bold text represents the introduction of a new term or the name of an argument, an attribute, or a reason.

italic text Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (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.

Monospace text Monospace type indicates code examples and interactive screen displays.
In the C programming language, monospace type in text identifies the following 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 at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.

numbers All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

Chapter 1
Introduction to Utility Routines

A set of utility routines performs a particular task or set of tasks. For example, you can use the Print Symbiont Modification (PSM) routines to modify the print symbiont and the EDT routines to invoke the EDT editor from a program.

Some of the tasks performed by utility routines can also be performed at the Digital Command Language (DCL) level (for example, the DCL command EDIT invokes the EVE editor). While DCL commands invoke utilities that let you perform tasks at your terminal, you can perform some of these tasks at the programming level through the use of the utility routines.

When using a set of utility routines that performs the same tasks as the related utility, you should read the documentation for that utility; doing so will provide additional information about the tasks the routines can perform as a set. The following table lists utilities and their corresponding routines:

Utility or Editor Utility Routines

Access control list editor ACL editor routine

Backup application programming interface (API) Backup API routine

Command Definition Utility CLI routines

Common File Qualifier routines UTIL$CQUAL routines

Convert and Convert/Reclaim utilities CONVERT routines

EDT editor EDT routines

DEC Text Processing Utility DECTPU routines

File Definition Language facility FDL routines

LOGINOUT callouts LGI routines

Librarian utility LBR routines

Mail utility MAIL routines

National character set utility NCS routines

Sort/Merge utility SOR routines

Utility or Editor	Utility Routines
Access control list editor	ACL editor routine
Backup application programming interface (API)	Backup API routine
Command Definition Utility	CLI routines
Common File Qualifier routines	UTIL$CQUAL routines
Convert and Convert/Reclaim utilities	CONVERT routines
EDT editor	EDT routines
DEC Text Processing Utility	DECTPU routines
File Definition Language facility	FDL routines
LOGINOUT callouts	LGI routines
Librarian utility	LBR routines
Mail utility	MAIL routines
National character set utility	NCS routines
Sort/Merge utility	SOR routines

When a set of utility routines performs functions that you cannot perform by invoking a utility, the functions provided by that set of routines is termed a facility. The following facilities have no other user interface except the programming interface provided by the utility routines described in this manual:

Facility Utility Routines

Data Compression/Expansion facility DCX routines

Print Symbiont Modification facility PSM routines

Symbiont/Job Controller Interface facility SMB routines

Facility	Utility Routines
Data Compression/Expansion facility	DCX routines
Print Symbiont Modification facility	PSM routines
Symbiont/Job Controller Interface facility	SMB routines

Like all other system routines in the OpenVMS environment, the utility routines described in this manual conform to the OpenVMS Calling Standard. Note that for stylistic purposes, the calling syntax illustrated for routines documented in this manual is consistent. However, you should consult your programming language documentation to determine the appropriate syntax for calling these routines.

Each chapter of this book documents one set of utility routines. Each chapter has the following major components, documented as a major heading:

An introduction to the set of utility routines. This component discusses the utility routines as a group and explains how to use them.
One or more programming examples that illustrate how the utility routines are used.
A series of descriptions of each utility routine in the set.

Chapter 2
Access Control List (ACL) Editor Routine

This chapter describes the access control list editor (ACL editor) routine, ACLEDIT$EDIT. User-written applications can use this callable interface of the ACL editor to manipulate access control lists (ACLs).

2.1 Introduction to the ACL Editor Routine

The ACL editor is a utility that lets you create and maintain access control lists. Using ACLs, you can limit access to the following protected objects available to system users:

Devices
Files
Group global sections
Logical name tables
System global sections
Capabilities (VAX only)
Common event flag clusters
Queues
Resource domains
Security classes
Volumes

The ACL editor provides one callable interface that allows the application program to define an object for editing.

Note that the application program should declare referenced constants and return status symbols as external symbols; these symbols will be resolved upon linking with the utility shareable image.

See the OpenVMS Programming Concepts Manual for fundamental conceptual information on the creation, translation, and maintenance of access control entries (ACEs).

2.2 Using the ACL Editor Routine: An Example

Example 2-1 shows a VAX BLISS program that calls the ACL editor routine.

Example 2-1 Calling the ACL Editor with a VAX BLISS Program

MODULE MAIN (LANGUAGE (BLISS32), MAIN = STARTUP) = BEGIN LIBRARY 'SYS$LIBRARY:LIB'; ROUTINE STARTUP = BEGIN LOCAL STATUS, ! Routine return status ITMLST : BLOCKVECTOR [6, ITM$S_ITEM, BYTE]; ! ACL editor item list EXTERNAL LITERAL ACLEDIT$V_JOURNAL, ACLEDIT$V_PROMPT_MODE, ACLEDIT$C_OBJNAM, ACLEDIT$C_OBJTYP, ACLEDIT$C_OPTIONS; EXTERNAL ROUTINE ACLEDIT$EDIT : ADDRESSING_MODE (GENERAL), ! Main routine CLI$GET_VALUE, ! Get qualifier value CLI$PRESENT, ! See if qualifier present LIB$PUT_OUTPUT, ! General output routine STR$COPY_DX; ! Copy string by descriptor ! Set up the item list to pass back to TPU so it can figure out what to do. CH$FILL (0, 6*ITM$S_ITEM, ITMLST); ITMLST[0, ITM$W_ITMCOD] = ACLEDIT$C_OBJNAM; ITMLST[0, ITM$W_BUFSIZ] = %CHARCOUNT ('YOUR_OBJECT_NAME'); ITMLST[0, ITM$L_BUFADR] = $DESCRIPTOR ('YOUR_OBJECT_NAME'); ITMLST[1, ITM$W_ITMCOD] = ACLEDIT$C_OBJTYP; ITMLST[1, ITM$W_BUFSIZ] = 4; ITMLST[1, ITM$L_BUFADR] = UPLIT (ACL$C_FILE); ITMLST[2, ITM$W_ITMCOD] = ACLEDIT$C_OPTIONS; ITMLST[2, ITM$W_BUFSIZ] = 4; ITMLST[2, ITM$L_BUFADR] = UPLIT (1 ^ ACLEDIT$V_PROMPT_MODE OR 1 ^ ACLEDIT$V_JOURNAL); RETURN ACLEDIT$EDIT (ITMLST); END; ! End of routine STARTUP END ELUDOM

2.3 ACL Editor Routine

This section describes the ACL editor routine.

ACLEDIT$EDIT

The ACLEDIT$EDIT routine creates and modifies an access control list (ACL) associated with any protected object.

Format

ACLEDIT$EDIT item_list

RETURNS

OpenVMS usage: cond_value

type: longword (unsigned)

access: write only

mechanism: by value

Longword condition value. Most utility routines return a condition value in R0. Condition values that this routine can return are listed under Condition Values Returned.

Argument

item_list

OpenVMS usage: item_list_3

type: longword (unsigned)

access: read only

mechanism: by descriptor

Item list used by the callable ACL editor. The item_list argument is the address of one or more descriptors of arrays, routines, or longword bit masks that control various aspects of the editing session.
Each entry in an item list is in the standard format shown in the following figure:

The following table provides a detailed description of each item list entry:

Item Identifier Description

ACLEDIT$C_OBJNAM Specifies the name of the object whose ACL is being edited.

ACLEDIT$C_OBJTYP A longword value that specifies the object type code for the type or class of the object whose ACL is being edited. These type codes are defined in $ACLDEF. The default object type is FILE (ACL$C_FILE).

ACLEDIT$C_OPTIONS Represents a longword bit mask of the various options available to control the editing session.

Flag Function

ACLEDIT$V_JOURNAL Indicates that the editing session is to be journaled.

ACLEDIT$V_RECOVER Indicates that the editing session is to be recovered from an existing journal file.

ACLEDIT$V_KEEP_RECOVER Indicates that the journal file used to recover the editing session is not to be deleted when the recovery is complete.

ACLEDIT$V_KEEP_JOURNAL Indicates that the journal file used for the editing session is not to be deleted when the session ends.

ACLEDIT$V_PROMPT_MODE Indicates that the session is to use automatic text insertion (prompting) to build new access control list entries (ACEs).

ACLEDIT$C_BIT_TABLE Specifies a vector of 32 quadword string descriptors of strings that define the names of the bits present in the access mask. (The first descriptor defines the name of bit 0; the last descriptor defines the name of bit 31.) These descriptors are used in parsing or formatting an ACE. The buffer address field of the item descriptor contains the address of this vector.

ACLEDIT$C_CLSNAM A string descriptor that points to the class name of the object whose ACL is being modified. The following are valid class names:

CAPABILITY+
COMMON_EVENT_FLAG_CLUSTER
DEVICE
FILE
GROUP_GLOBAL_SECTION
LOGICAL_NAME_TABLE
QUEUE
RESOURCE_DOMAIN
SECURITY_CLASS
SYSTEM_GLOBAL_SECTION
VOLUME

If both OBJTYP and CLSNAM are omitted, the object is assumed to belong to the FILE class.

+VAX specific.

Description

Use the ACLEDIT$EDIT routine to create and modify an ACL associated with any security object.
Under normal circumstances, the application calls the ACL editor to modify an object's ACL, and control is returned to the application when you finish or abort the editing session.
If you also want to use a customized version of the ACL editor section file, the logical name ACLEDT$SECTION should be defined. See the OpenVMS System Management Utilities Reference Manual for more information.

Condition Values Returned

SS$_NORMAL Normal successful completion.

RMS$_xxx See the OpenVMS Record Management Services Reference Manual for a description of OpenVMS RMS status codes.

TPU$_xxx See Chapter 8 for a description of the TPU-specific condition values that may be returned by ACLEDIT$EDIT.

Contents

Index

privacy and legal statement

4493PRO.HTML

Internet	openvmsdoc@compaq.com
Mail	Compaq Computer Corporation OSSG Documentation Group, ZKO3-4/U08 110 Spit Brook Rd. Nashua, NH 03062-2698

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.
`[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 elements. 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 indicate a required choice of options; you must choose one of the options listed.
bold text	Bold text represents the introduction of a new term or the name of an argument, an attribute, or a reason.
italic text	Italic text indicates important information, complete titles of manuals, or variables. Variables include information that varies in system output (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.
`Monospace text`	Monospace type indicates code examples and interactive screen displays. In the C programming language, monospace type in text identifies the following 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 at the end of a command format description, command line, or code line indicates that the command or statement continues on the following line.
numbers	All numbers in text are assumed to be decimal unless otherwise noted. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated.

OpenVMS usage:	cond_value
type:	longword (unsigned)
access:	write only
mechanism:	by value

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by descriptor

SS$_NORMAL	Normal successful completion.
RMS$_xxx	See the OpenVMS Record Management Services Reference Manual for a description of OpenVMS RMS status codes.
TPU$_xxx	See Chapter 8 for a description of the TPU-specific condition values that may be returned by ACLEDIT$EDIT.