|
HP OpenVMS Systems Documentation |
|
OpenVMS Utility Routines ManualOrder Number: AA--PV6EF--TK
June 2002
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.3. Software Version: OpenVMS Alpha Version 7.3-1 OpenVMS VAX Version 7.3
© 2002 Compaq Information Technologies Group, L.P. Compaq, the Compaq logo, Alpha, OpenVMS, Tru64, VAX, VMS, and the DIGITAL logo are trademarks of Compaq Information Technologies Group, L.P., in the U.S. and/or other countries. All other product names mentioned herein may be 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.
PrefaceIntended AudienceThis manual is intended for programmers who want to invoke and use the functions provided by OpenVMS utilities. What's New in This Version?This version of the manual includes the following new information:
Document StructureChapter 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 following utility routine sets:
Related DocumentsFor additional information about Compaq OpenVMS products and services, access the Compaq website at the following location:
Reader's CommentsCompaq welcomes your comments on this manual. Please send comments to either of the following addresses:
How To Order Additional DocumentationVisit the following World Wide Web address for information about how to order additional documentation:
ConventionsIn 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:
Chapter 1
|
| Utility or Editor | Utility Routines |
|---|---|
| Access control list editor | ACL editor routine |
| Backup application programming interface | Backup API routine |
| Command Definition Utility | CLI routines |
| Common File Qualifier routines | UTIL$CQUAL routines |
| Convert and Convert/Reclaim utilities | CONVERT routines |
| Data Compression/Expansion (DCX) facility | DCX routines |
| DEC Text Processing Utility | DECTPU routines |
| DIGITAL Distributed Time Service (DECdts) portable applications programming interface | DECdts API routines |
| EDT editor | EDT routines |
| File Definition Language facility | FDL routines |
| Librarian utility | LBR routines |
| Lightweight Directory Access Protocol (LDAP) application programming interface | LDAP API routines |
| LOGINOUT callout routines | LGI routines |
| Mail utility | MAIL routines |
| National Character Set utility | NCS routines |
| Print Symbiont Modification (PSM) facility | PSM routines |
| Symbiont/Job Controller Interface facility | SMB 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 |
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:
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:
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
|
This section describes the ACL editor routine.
The ACLEDIT$EDIT routine creates and modifies an access control list (ACL) associated with any protected object.
ACLEDIT$EDIT item_list
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.
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.
|
||||||||||||
| 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:
If both OBJTYP and CLSNAM are omitted, the object is assumed to belong to the FILE class. |
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.
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.
| Next | Contents | Index |