HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.