[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Record Management Services Reference Manual


Previous Contents Index


$XABFHC

The $XABFHC macro allocates and initializes a XABFHC. No value is returned for this assembly-time operation.

Format

$XABFHC NXT=next-xab-address


Arguments


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.


$XABFHC_STORE

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.

Format

$XABFHC_STORE XAB=xabfhc-address,


NXT =next-xab-address

Arguments


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.


$XABITM

The $XABITM macro allocates and initializes a XABITM. No value is returned for this assembly-time operation.

Format

$XABITM ITEMLIST=item-list-address,


MODE ={sensemode|setmode},
NXT =next-xab-address

Arguments


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.


$XABKEY

The $XABKEY macro allocates and initializes a XABKEY. No value is returned for this assembly-time operation.

Format

$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,...>

Arguments


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=10 

This 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=CHG 

In 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=size 

or


POS=<position0,...,position7> 
   .
   .
   .
SIZ=<size0,...,size7> 

You must include the angle brackets for multiple argument key positions and sizes.


$XABKEY_STORE

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.

Format

$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,...>

Arguments


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.


$XABPRO

The $XABPRO macro allocates and initializes a XABPRO. No value is returned for this assembly-time operation.

Format

$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>

Arguments


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:

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.


$XABPRO_STORE

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.

Format

$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

Arguments


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:

Note that R0 is usually used by the $XABPRO_STORE macro; thus, R0 is not preserved and does not contain a return status.


$XABRDT

The $XABRDT macro allocates and initializes a XABRDT. No value is returned for this assembly-time operation.

Format

$XABRDT NXT=next-xab-address


Arguments


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.


$XABRDT_STORE

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.

Format

$XABRDT_STORE XAB=xabrdt-address,


RDT =#revision-date-time,
RVN =#revision-number,
NXT =next-xab-address

Arguments


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.


$XABSUM

The $XABSUM macro allocates and initializes a XABSUM. No value is returned for this assembly-time operation.

Format

$XABSUM NXT=next-xab-address


Arguments


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.


$XABSUM_STORE

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.

Format

$XABSUM_STORE XAB=xabsum-address,


NXT =next-xab-address

Arguments


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.


$XABTRM

The $XABTRM macro allocates and initializes a XABTRM. No value is returned for this assembly-time operation.

Format

$XABTRM ITMLST=item-list-address,


ITMLST _LEN=item-list-length,
NXT =next-xab-address

Arguments


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.


$XABTRM_STORE

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.

Format

$XABTRM_STORE XAB=xabtrm-address,


ITMLST =item-list-address,
ITMLST _LEN=#item-list-length,
NXT =next-xab-address

Arguments


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.


Appendix B
VAX MACRO Programming Information and Examples

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.

Table B-1 User Control Blocks
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


1The variable xxx represents a 3-character mnemonic.

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.

Table B-2 Record Management Services
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


1This service is not supported for DECnet for OpenVMS operations involving remote file access between two OpenVMS systems.


Previous Next Contents Index

[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
[OpenVMS documentation]

Copyright © Compaq Computer Corporation 1998. All rights reserved.

Legal
4523PRO_036.HTML