Updated: 11 December 1998 |
OpenVMS Record Management Services Reference
Manual
Previous | Contents | Index |
The $XABFHC macro allocates and initializes a XABFHC. No value is returned for this assembly-time operation.
$XABFHC NXT=next-xab-address
For a description of the control block fields that correspond to the $XABFHC macro arguments, see Chapter 11.Rules applicable to arguments are described in Appendix B.
The $XABFHC_STORE macro moves user-specified values into fields of the specified XABFHC. The expanded $XABFHC_STORE code executes at run time on a previously initialized (allocated) XABFHC, in contrast to the $XABFHC macro, which initializes a XABFHC at assembly time. The $XABFHC_STORE macro must reside in a code program section.
$XABFHC_STORE XAB=xabfhc-address,
NXT =next-xab-address
For a description of the control block fields that correspond to the $XABFHC_STORE macro arguments, see Chapter 11.Arguments fall into several categories: values, addresses, keywords, and the address of the control block to receive the specified arguments. Rules applicable to these argument categories for the control block store macros are described in Appendix B.
The XAB argument xabfhc-address is required for the $XABFHC_STORE macro and is not present for the $XABFHC macro.
Note that R0 may be used by the $XABFHC_STORE macro; thus, R0 is not preserved and does not contain a return status.
The $XABITM macro allocates and initializes a XABITM. No value is returned for this assembly-time operation.
$XABITM ITEMLIST=item-list-address,
MODE ={sensemode|setmode},
NXT =next-xab-address
For a description of the control block fields that correspond to the $XABITM macro arguments, see Chapter 12.Rules applicable to arguments are described in Appendix B.
ITEMLIST defaults to 0 but a valid pointer must be specified when you use a $XABITM macro. MODE defaults to sensemode.
The $XABKEY macro allocates and initializes a XABKEY. No value is returned for this assembly-time operation.
$XABKEY COLTBL=collating-table-address,
DAN =data-bucket-area-number,
DFL =data-bucket-fill-size,
DTP ={BN2|DBN2|BN4|DBN4|BN8|DBN8|IN2 |DIN2|IN4|DIN4|IN8|DIN8|COL|DCOL |PAC|DPAC|STG|DSTG},
FLG =<CHG DAT_NCMPR DUP IDX_NCMPR KEY_NCMPR NUL>,
IAN =index-bucket-area-number,
IFL =index-bucket-file-size,
KNM =key-name-buffer-address,
LAN =lowest-level-index-area-number,
NUL =null-key-value,
NXT =next-xab-address,
POS =<position,...>,
PROLOG =prolog-level,
REF =key-of-reference-value,
SIZ =<size,...>
For a description of the control block fields that correspond to the $XABKEY macro arguments, see Chapter 14.Arguments fall into three categories: values, addresses, and keywords. Rules applicable to these argument categories are described in Appendix B.
Multiple arguments can be specified for the FLG keyword, but the arguments must be enclosed within left angle (<) and right angle (>) brackets. Defaults are applied to the XAB$B_FLG field only if no FLG argument is specified. Consider the following:
KEY_1: $XABKEY REF=1, POS=0, SIZ=10This line specifies the key for alternate index 1. Therefore the macro defaults the XAB$B_FLG field to allow duplicates and changes (the default for alternate keys). However, if an FLG argument is explicitly specified, the results are different, as shown in the following code example.
KEY_2: $XABKEY REF=1, POS=0, SIZ=10, FLG=CHGIn this case, the CHG bit is set in the XAB$B_FLG field and the DUP bit remains clear, to disallow duplicates on this key.
Depending on whether the key being defined is simple or segmented, you would use one of the following two formats for the POS and SIZ arguments:
POS=position . . . SIZ=sizeor
POS=<position0,...,position7> . . . SIZ=<size0,...,size7>You must include the angle brackets for multiple argument key positions and sizes.
The $XABKEY_STORE macro moves user-specified values into fields of the specified XABKEY. The expanded $XABKEY_STORE code executes at run time on a previously initialized (allocated) XABKEY, in contrast to the $XABKEY macro, which initializes the XABKEY at assembly time. The $XABKEY_STORE macro must reside in a code program section.
$XABKEY_STORE XAB=xabkey-address,
COLTBL =#collating-table-address,
DAN =#data-bucket-area-number,
DFL =#data-bucket-fill-size,
DTP ={BN2|DBN2|BN4|DBN4|BN8|DBN8|IN2 |DIN2|IN4|DIN4|IN8|DIN8|COL|DCOL |PAC|DPAC|STG|DSTG},
FLG =<CHG DAT_NCMPR DUP IDX_NCMPR KEY_NCMPR NUL>,
IAN =#index-bucket-area-number,
IFL =#index-bucket-fill-size,
KNM =key-name-buffer-address,
LAN =#lowest-level-index-area-number,
NUL =#null-key-value,
NXT =next-xab-address,
POS =<position,...>,
PROLOG =#prolog-level,
REF =#key-of-reference-value,
SIZ =<size,...>
For a description of the control block fields that correspond to the $XABKEY_STORE macro arguments, see Chapter 14.Arguments fall into several categories: values, addresses, keywords, and the address of the control block to receive the specified arguments. Rules applicable to these argument categories for the control block store macros are described in Appendix B.
The XAB argument xabkey-address is required for the $XABKEY_STORE macro and is not present for the $XABKEY macro. The POS and SIZ arguments can be either symbolic addresses or a list of up to eight values, where each value must be preceded by a number sign (#), and the entire list must be enclosed within left angle and right angle brackets (<#value,...,#value>). The number of POS and SIZ values must be equal. Alternatively, each POS and SIZ value can be specified as an argument, using the following form:
POS0 = #value, POS1 = #value, ..., POS7 = #value
SIZ0 = #value, SIZ1 = #value, ..., SIZ7 = #value
Note that R0 is usually used by the $XABKEY_STORE macro; thus, R0 is not preserved and does not contain a return status.
The $XABPRO macro allocates and initializes a XABPRO. No value is returned for this assembly-time operation.
$XABPRO ACLBUF=ACL-buffer-address,
ACLCTX =<ACL-context>,
ACLSIZ =ACL-buffer-size,
MTACC =magnetic-tape-accessibility,
NXT =next-xab-address,
PRO =<system, owner, group, world>,
PROT _OPT=<PROPAGATE>,
UIC =<group, member>
For a description of the control block fields that correspond to the $XABPRO macro arguments, refer to Chapter 15.Rules applicable to arguments are described in Appendix B.
For the MTACC (magnetic tape accessibility) argument, an ASCII radix indicator is required. For example, the letter Z is entered as the accessibility character with the following macro expression:
$XABPRO MTACC=^A/Z/In this example, the circumflex (^) followed by an uppercase A indicates that ASCII text follows. The two slashes (//) delimit the ASCII text. RMS converts all lowercase characters to uppercase. No other modification is made.
For the PRO argument, the angle brackets are required syntax, and each user class must be separated from the others by a comma. When you omit a class to use the default protection, you must retain the comma to indicate the omission, unless no other class follows.
To allow all system users read and write access, use the default file protection for the file owner (by omission), allow group users read access, and use the default for world users, you would specify <RW,,R>. You may specify all, some, or none of the access characters, and place multiple characters in any order, for each user class.
Here is a listing of the user classes together with the letters used to represent them:
- R---read access
- W---write access
- E---execute access
- D---delete access
The absence of a code specifies that the access associated with the code is denied to the user.
Users are granted the maximum number of access rights for each of the classes to which they belong.
For the UIC argument, the value for the group item must be in the range of 0 to 37777; the value for the member item must from 0 to 177777. Note that the maximum values (37777 and 177777) are reserved for Compaq use only. The group number and member number must be enclosed within angle brackets, placed in the order <group,member>, and be separated by a comma. Each number is interpreted as an octal number.
The $XABPRO_STORE macro moves user-specified values into fields of the specified XABPRO. The expanded $XABPRO_STORE code executes at run time on a previously initialized (allocated) XABPRO, in contrast to the $XABPRO macro, which initializes a XABPRO at assembly time. The $XABPRO_STORE macro must reside in a code program section.
$XABPRO_STORE XAB=xabpro-address,
ACLBUF =ACL-buffer-address,
ACLCTX =#<ACL-context>,
ACLSIZ =#ACL-buffer-size,
MTACC =#magnetic-tape-accessibility,
NXT =next-xab-address,
PRO =<system, owner, group, world>,
PROT _OPT=<PROPAGATE>,
UIC =#uic-value
For a description of the control block fields that correspond to the $XABPRO_STORE macro arguments, see Chapter 15.Arguments fall into several categories: values, addresses, keywords, and the address of the control block to receive the specified arguments. Rules applicable to these argument categories for the control block store macros are described in Appendix B.
The XAB argument xabpro-address is required for the $XABPRO_STORE macro and is not present for the $XABPRO macro. Also, the following arguments do not comply with the general rules:
- The PRO argument (file protection) can be either a symbolic address or a list of keyword values. If you specify a list of keywords, it must be enclosed within left angle (<) and right angle (>) brackets and the number sign (#) must be omitted; for example, PRO=<RWED,RWED,R,R>.
- The UIC argument (group,member) can be either a symbolic address or a list of two data values. If the data values are constants, they must be specified with an octal radix without a preceding number sign (#). This argument can be passed by its symbolic address or by using a VAX MACRO expression.
Note that R0 is usually used by the $XABPRO_STORE macro; thus, R0 is not preserved and does not contain a return status.
The $XABRDT macro allocates and initializes a XABRDT. No value is returned for this assembly-time operation.
$XABRDT NXT=next-xab-address
For a description of the control block fields that correspond to the $XABRDT macro argument, see Chapter 16.Rules applicable to arguments are described in Appendix B.
The $XABRDT_STORE macro moves user-specified values into fields of the specified XABRDT. The expanded $XABRDT_STORE code executes at run time on a previously initialized (allocated) XABRDT, in contrast to the $XABRDT macro, which initializes the XABRDT at assembly time. The $XABRDT_STORE macro must reside in a code program section.
$XABRDT_STORE XAB=xabrdt-address,
RDT =#revision-date-time,
RVN =#revision-number,
NXT =next-xab-address
For a description of the control block fields that correspond to the $XABRDT_STORE macro arguments, see Chapter 16.Arguments fall into several categories: values, addresses, keywords, and the address of the control block to receive the specified arguments. Rules applicable to these argument categories for the control block store macros are described in Appendix B.
The XAB argument xabrdt-address is required for the $XABRDT_STORE macro and is not present for the $XABRDT macro. Also, the RDT argument revision-date-time and RVN argument revision-number are not present in the $XABRDT macro. The RDT argument revision-date-time is usually passed by its symbolic address. However, if a register is used to contain a value for the XAB$Q_RDT field, do not use R12, because two contiguous registers must be used to contain the value of this quadword field.
Note that R0 is usually used by the $XABRDT_STORE macro; thus, R0 is not preserved and does not contain a return status.
The $XABSUM macro allocates and initializes a XABSUM. No value is returned for this assembly-time operation.
$XABSUM NXT=next-xab-address
For a description of the control block fields that correspond to the $XABSUM macro argument, see Chapter 18.Rules applicable to arguments are described in Appendix B.
The $XABSUM_STORE macro moves user-specified values into fields of the specified XABSUM. The expanded $XABSUM_STORE code executes at run time on a previously initialized (allocated) XABSUM, in contrast to the $XABSUM macro, which initializes the XABSUM at assembly time. The $XABSUM_STORE macro must reside in a code program section.
$XABSUM_STORE XAB=xabsum-address,
NXT =next-xab-address
For a description of the control block fields that correspond to the $XABSUM_STORE macro arguments, see Chapter 18.Arguments fall into several categories: values, addresses, keywords, and the address of the control block to receive the specified arguments. Rules applicable to these argument categories for the control block store macros are described in Appendix B.
The XAB argument xabsum-address is required for the $XABSUM_STORE macro and is not present for the $XABSUM macro.
Note that R0 may be used by the $XABSUM_STORE macro; thus, R0 is not preserved and does not contain a return status.
The $XABTRM macro allocates and initializes a XABTRM. No value is returned for this assembly-time operation.
$XABTRM ITMLST=item-list-address,
ITMLST _LEN=item-list-length,
NXT =next-xab-address
For a description of the control block fields that correspond to the $XABTRM macro arguments, see Chapter 19.Rules applicable to arguments are described in Appendix B.
The $XABTRM_STORE macro moves user-specified values into fields of the specified XABTRM. The expanded $XABTRM_STORE code executes at run time on a previously initialized (allocated) XABTRM, in contrast to the $XABTRM macro, which initializes a XABTRM at assembly time. The $XABTRM_STORE macro must reside in a code program section.
$XABTRM_STORE XAB=xabtrm-address,
ITMLST =item-list-address,
ITMLST _LEN=#item-list-length,
NXT =next-xab-address
For a description of the control block fields that correspond to the $XABTRM_STORE macro arguments, see Chapter 19.Arguments fall into several categories: values, addresses, keywords, and the address of the control block to receive the specified arguments. Rules applicable to these argument categories for the control block store macros are described in Appendix B.
The XAB argument xabtrm-address is required for the $XABTRM_STORE macro and is not present for the $XABTRM macro.
Note that R0 is usually used by the $XABTRM_STORE macro; thus, R0 is not preserved and does not contain a return status.
This appendix provides VAX MACRO programmers with information about the
four types of RMS macros used in VAX MACRO programming. It describes
each of the four types of macros, the macro naming conventions, and
macro syntax rules. It then shows you how to use the macros and
includes examples for each of the four types. Note that the term
"macro" refers to a program macro written in the VAX MACRO
language.
B.1 RMS Macros
RMS provides four types of macros used by VAX MACRO programs implementing RMS features. The functions these macros provide are described in the following list.
RMS stores its macros for use by VAX MACRO programs in
SYS$LIBRARY:STARLET.MLB.
B.1.1 Conventions for Naming RMS Macros
The names for the macros that initialize control blocks at assembly time consist of a dollar sign ($) followed by the name of the control block. For example, the name of the macro that initializes a FAB is $FAB; the name of the macro that initializes a XABALL is $XABALL.
The names for the macros that define symbolic offsets without performing control block initialization contain the suffix DEF following the corresponding initialization macro name; for example, $FABDEF and $XABALLDEF.
The names for the macros that set control block field values at run time contain the suffix "_STORE" following the corresponding initialization macro name; for example, $FAB_STORE and $XABALL_STORE.
Table B-1 summarizes the control blocks, their assembly time macro names, and their functions.
Control Block |
Macro Names |
Function |
---|---|---|
FAB | Describes a file and contains file-related information | |
$FAB | Allocates storage for a FAB and initializes certain FAB fields; also defines symbolic offsets for a FAB | |
$FABDEF | Defines symbolic offsets for FAB fields | |
$FAB_STORE | Moves specified values into a previously allocated and initialized FAB | |
NAM | Contains file specification information beyond that in the file access block | |
$NAM | Allocates storage for a NAM and initializes certain NAM fields; also defines symbolic offsets for a NAM | |
$NAMDEF | Defines symbolic offsets for NAM fields | |
$NAM_STORE | Moves specified values into a previously specified and allocated NAM | |
RAB | Describes a record stream and contains record-related information | |
$RAB | Allocates storage for a RAB and initializes certain RAB fields; also defines symbolic offsets for a RAB | |
$RABDEF | Defines symbolic offsets for both RAB and RAB64 fields | |
$RAB_STORE | Moves specified values into a previously specified and allocated RAB | |
$RAB64 | Allocates storage for a RAB64 and initializes certain RAB64 fields; also defines symbolic offsets for a RAB64 | |
$RAB64_STORE | Moves specified values into a previously specified and allocated RAB64 | |
XAB | Supplements file attributes in the file access block; for XABTRM and XABRU, supplements information in the record access block | |
$XABxxx 1 | Allocates and initializes a XAB | |
$XABxxxDEF | Defines symbolic offsets for a XABxxx | |
$XABxxx_STORE | Moves specified values into a previously specified and allocated XABxxx |
Record management services can be called using the OpenVMS calling standard. These services are system services identified by the entry point prefix "SYS$" followed by three or more characters; the "SYS" prefix is omitted in the corresponding VAX MACRO macro name. For example, the Create service has an entry point of SYS$CREATE and a VAX MACRO macro name of $CREATE. A complete description of each service is provided in Part 3.
Table B-2 describes the functions of each service, including the service entry point name and its corresponding VAX MACRO macro name.
Service Name | Macro Name | Description |
---|---|---|
File-Processing and File-Naming Macros | ||
SYS$CLOSE | $CLOSE | Terminates file processing and disconnects all record streams previously associated with the file |
SYS$CREATE | $CREATE | Creates and opens a new file |
SYS$DISPLAY | $DISPLAY | Returns the opened file's attributes to the application program |
SYS$ENTER 1 | $ENTER | Enters a file name into a directory |
SYS$ERASE | $ERASE | Deletes a file and removes its directory entry |
SYS$EXTEND | $EXTEND | Allocates additional space to a file |
SYS$OPEN | $OPEN | Opens an existing file and initiates file processing |
SYS$PARSE | $PARSE | Parses a file specification |
SYS$REMOVE 1 | $REMOVE | Removes a file name from a directory but does not actually delete the file data; compare this with the $ERASE macro |
SYS$RENAME | $RENAME | Assigns a new name to (renames) a file |
SYS$SEARCH | $SEARCH | Searches a directory, or possibly multiple directories, for a file name |
Record-Processing Macros | ||
SYS$CONNECT | $CONNECT | Establishes a record stream by associating a RAB with an open file |
SYS$DELETE | $DELETE | Deletes a record from a relative or indexed file |
SYS$DISCONNECT | $DISCONNECT | Terminates a record stream by disconnecting a RAB from an open file |
SYS$FIND | $FIND | Locates the specified record, establishes it as the current record, and returns the record's RFA to the application program |
SYS$FLUSH | $FLUSH | Writes (flushes) modified I/O buffers and file attributes to the disk before closing a file |
SYS$FREE | $FREE | Unlocks all records previously locked by the record stream |
SYS$GET | $GET | Retrieves a record from a file |
SYS$NXTVOL 1 | $NXTVOL | Causes processing of a magnetic tape file to continue to the next volume of a volume set |
SYS$PUT | $PUT | Writes a new record to a file |
SYS$RELEASE | $RELEASE | Unlocks a record pointed to by the contents of the RAB$W_RFA field |
SYS$REWIND | $REWIND | Establishes the first file record as the current record |
SYS$TRUNCATE | $TRUNCATE | Truncates a sequential file |
SYS$UPDATE | $UPDATE | Deletes and rewrites (updates) an existing file record |
SYS$WAIT | $WAIT | Awaits the completion of an asynchronous record operation |
Block I/O-Processing Macros | ||
SYS$READ | $READ | Retrieves a specified number of bytes from a file, beginning on block boundaries |
SYS$SPACE | $SPACE | Positions forward or backward in a file to a block boundary |
SYS$WRITE | $WRITE | Writes a specified number of bytes to a file, beginning on block boundaries |
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4523PRO_036.HTML
|