OpenVMS Record Management Services Reference Manual Order Number: AA–PV6RE–TK June 2002 This reference manual contains general information intended for use in any OpenVMS programming language, as well as specific information on writing programs that use OpenVMS Record Management Services (OpenVMS RMS). Revision/Update Information: This manual supersedes the OpenVMS Record Management Services Reference Manual, OpenVMS Alpha Version, 7.3 and OpenVMS VAX Version, 7.3 Software Version: OpenVMS Alpha Version, 7.3–1 OpenVMS VAX Version, 7.3 Compaq Computer Corporation Houston, Texas © 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. Motif, OSF/1, and UNIX are trademarks of The Open Group 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. ZK4523 The Compaq OpenVMS documentation set is available on CD-ROM. This document was prepared using DECdocument, Version 3.3-1b. Contents Preface ............................................................ xv Part I OpenVMS RMS—General Information 1 Introduction to RMS 1.1 RMS Functions ............................................. 1–1 1.2 Passing Arguments to RMS .................................... 1–3 1.2.1 Record Management Services and Control Blocks . ............... 1–3 1.2.2 Control Blocks for File Services .............................. 1–4 1.2.3 Control Blocks for Record Services ............................ 1–5 1.2.4 Dual Purpose of Control Blocks .............................. 1–5 2 RMS Program Interface 2.1 RMS Run-Time Environment . ................................ 2–1 2.2 Conventions for Naming Fields . ................................ 2–2 2.3 RMS Calling Sequence ........................................ 2–4 2.4 Service Completion . ........................................ 2–5 2.4.1 Illformed Calls to RMS .................................... 2–5 2.4.2 Setting Synchronous or Asynchronous Option ................... 2–5 2.4.3 Synchronous Completion . ................................ 2–6 2.4.4 Asynchronous Completion . ................................ 2–6 2.4.5 Status Code Testing ....................................... 2–7 2.4.6 Types of Errors . ........................................ 2–8 2.5 Allowable Program Execution Modes ............................. 2–9 2.6 Access-Mode Protected Memory . ................................ 2–9 2.7 Reserved Event Flags ........................................ 2–9 2.8 DEC Multinational Character Set ............................... 2–10 3 Implementing RMS from C Programs 3.1 Creating, Accessing, and Deaccessing a File ....................... 3–1 3.1.1 Example of Copying Records from One File to Another File . ....... 3–2 3.2 Program to Illustrate Record Operations . ....................... 3–5 3.3 Program to Show Index Root Levels ............................. 3–8 3.4 Program to Illustrate Using NAML Blocks (Alpha Only) ............. 3–9 3.5 Program to Illustrate Using the RAB64 Structure ................... 3–12 iii Part II RMS Control Blocks 4 File Access Block (FAB) 4.1 Summary of Fields ........................................... 4–1 4.2 FAB$B_ACMODES Field . .................................... 4–3 4.3 FAB$L_ALQ Field ........................................... 4–3 4.4 FAB$B_BID Field ........................................... 4–3 4.5 FAB$B_BKS Field ........................................... 4–3 4.6 FAB$B_BLN Field ........................................... 4–4 4.7 FAB$W_BLS Field ........................................... 4–5 4.8 FAB$V_CHAN_MODE Subfield ................................. 4–5 4.8.1 Override Value........................................... 4–5 4.8.2 Channel Access Mode Function . ............................ 4–6 4.9 FAB$L_CTX Field ........................................... 4–6 4.10 FAB$W_DEQ Field .......................................... 4–6 4.11 FAB$L_DEV Field ........................................... 4–7 4.12 FAB$L_DNA Field ........................................... 4–9 4.13 FAB$B_DNS Field ........................................... 4–9 4.14 FAB$B_FAC Field ........................................... 4–9 4.15 FAB$L_FNA Field ........................................... 4–11 4.16 FAB$B_FNS Field ........................................... 4–12 4.17 FAB$L_FOP Field ........................................... 4–12 4.18 FAB$B_FSZ Field ........................................... 4–19 4.19 FAB$W_GBC Field .......................................... 4–19 4.20 FAB$W_IFI Field ............................................ 4–21 4.21 FAB$B_JOURNAL Field . .................................... 4–21 4.22 FAB$V_LNM_MODE Subfield .................................. 4–22 4.23 FAB$L_MRN Field ........................................... 4–22 4.24 FAB$W_MRS Field .......................................... 4–22 4.25 FAB$L_NAM Field .......................................... 4–24 4.26 FAB$B_ORG Field ........................................... 4–24 4.27 FAB$B_RAT Field ........................................... 4–25 4.28 FAB$B_RFM Field ........................................... 4–27 4.29 FAB$B_RTV Field ........................................... 4–28 4.30 FAB$L_SDC Field ........................................... 4–28 4.31 FAB$B_SHR Field ........................................... 4–28 4.32 FAB$L_STS Field ............................................ 4–31 4.33 FAB$L_STV Field ........................................... 4–31 4.34 FAB$L_XAB Field ........................................... 4–31 5 Name Block (NAM) 5.1 Summary of Fields ........................................... 5–1 5.2 File Specification Component Descriptors ......................... 5–3 5.3 NAM$B_BID Field ........................................... 5–4 5.4 NAM$B_BLN Field .......................................... 5–4 5.5 NAM$B_DEV and NAM$L_DEV Fields ........................... 5–4 5.6 NAM$W_DID Field .......................................... 5–4 5.7 NAM$B_DIR and NAM$L_DIR Fields ............................ 5–4 5.8 NAM$T_DVI Field ........................................... 5–5 5.9 NAM$L_ESA Field ........................................... 5–5 5.10 NAM$B_ESL Field ........................................... 5–5 5.11 NAM$B_ESS Field ........................................... 5–5 iv 5.12 NAM$W_FID Field . ........................................ 5–5 5.13 NAM$W_FIRST_WILD_DIR Field ............................... 5–5 5.14 NAM$L_FNB Field . ........................................ 5–6 5.15 NAM$W_LONG_DIR_LEVELS Field ............................. 5–7 5.16 NAM$B_NAME and NAM$L_NAME Fields ....................... 5–7 5.17 NAM$B_NMC .............................................. 5–8 5.18 NAM$B_NODE and NAM$L_NODE Fields . ....................... 5–8 5.19 NAM$B_NOP Field . ........................................ 5–8 5.20 NAM$L_RLF Field . ........................................ 5–9 5.21 NAM$L_RSA Field . ........................................ 5–10 5.22 NAM$B_RSL Field . ........................................ 5–10 5.23 NAM$B_RSS Field . ........................................ 5–10 5.24 NAM$B_TYPE and NAM$L_TYPE Fields . ....................... 5–10 5.25 NAM$B_VER and NAM$L_VER Fields ........................... 5–10 5.26 NAM$L_WCC Field . ........................................ 5–11 6 Long Name Block (NAML) 6.1 Using the NAM and NAML Block ............................... 6–1 6.2 Summary of Fields . ........................................ 6–2 6.3 Validating the NAML Block .................................... 6–5 6.4 NAML$B_BID Field . ........................................ 6–5 6.5 NAML$B_BLN Field . ........................................ 6–5 6.6 NAML$L_FILESYS_NAME Field ............................... 6–5 6.7 NAML$L_FILESYS_NAME_ALLOC Field . ....................... 6–5 6.8 NAML$L_FILESYS_NAME_SIZE Field ........................... 6–6 6.9 NAML$L_INPUT_FLAGS Field . ................................ 6–6 6.10 NAML$L_LONG_DEFNAME and NAML$L_LONG_DEFNAME_SIZE Fields ..................................................... 6–6 6.11 NAML$L_LONG_DEV and NAML$L_LONG_DEV_SIZE Fields . ....... 6–7 6.12 NAML$L_LONG_DIR and NAML$L_LONG_DIR_SIZE Fields . ....... 6–7 6.13 NAML$L_LONG_EXPAND Field ................................ 6–7 6.14 NAML$L_LONG_EXPAND_ALLOC Field . ....................... 6–7 6.15 NAML$L_LONG_EXPAND_SIZE Field ........................... 6–8 6.16 NAML$L_LONG_FILENAME and NAML$L_LONG_FILENAME_SIZE Fields ..................................................... 6–8 6.17 NAML$L_LONG_NAME and NAML$L_LONG_NAME_SIZE Fields ..... 6–8 6.18 NAML$L_LONG_NODE and NAML$L_LONG_NODE_SIZE Fields