OpenVMS Record Management Services Reference Manual

Document revision date: 15 July 2002

OpenVMS Record Management Services Reference Manual

Contents

Index

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

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.

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

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.

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

Control block initialization macros initialize a control block at assembly time. This type of macro performs five separate actions:
- Allocates space within the program image for the specified control block
- Defines the symbolic names associated with a control block
- Initializes certain control block fields with internally used values
- Initializes specified control block fields with user-specified values
- Initializes certain fields with system-supplied defaults (does not apply to all control block macros)
As an alternative to using this type of macro, an application program would have to allocate each control block needed with its correct length, initialize the internally used fields with the correct values, and initialize or set user-specified values in the appropriate fields. It is strongly recommended that you use these macros for VAX MACRO programs.
Control block symbol definition macros define control block symbolic names at assembly time without allocating and initializing the control block. These macros are needed only when the corresponding initialization macro is not used and the symbols are not defined.
Control block store macros store user-specified field values in control blocks at run time. Alternatively, you can store values in control block fields at run time using VAX MACRO instructions, such as the MOVx and MOVAx instructions. RMS accesses control block fields using the symbolic names that represent field offsets from the start of the control block.
Service macros invoke record management services at run time. When a service is invoked, one or more control blocks are examined for required field values. Values are also returned in one or more control blocks, including condition codes. Record management services conform to the OpenVMS calling standard and can be invoked directly, if needed, without the calling program having to use the service macro. However, the appropriate control block must be present with the appropriate field values set for the requested operation.

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 ¹ Allocates and initializes a XAB

$XABxxxDEF Defines symbolic offsets for a XABxxx

$XABxxx_STORE Moves specified values into a previously specified and allocated XABxxx

**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 ¹	Allocates and initializes a XAB
	$XABxxxDEF	Defines symbolic offsets for a XABxxx
	$XABxxx_STORE	Moves specified values into a previously specified and allocated XABxxx

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

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

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

Contents

Index

privacy and legal statement

4523PRO_038.HTML

OpenVMS Record Management Services Reference Manual

$XABPRO

Format

Arguments

$XABPRO_STORE

Format

Arguments

$XABRDT

Format

Arguments

$XABRDT_STORE

Format

Arguments

$XABSUM

Format

Arguments

$XABSUM_STORE

Format

Arguments

$XABTRM

Format

Arguments

$XABTRM_STORE

Format

Arguments

Appendix BVAX MACRO Programming Information and Examples

B.1 RMS Macros

B.1.1 Conventions for Naming RMS Macros

Appendix B
VAX MACRO Programming Information and Examples