HP OpenVMS Systems Documentation

Content starts here

OpenVMS Record Management Services Reference Manual


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