VMS Help MACRO, /MIGRATION, Locking Pages into a Working Set  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Five macros are provided for locking pages into a working set.
    These macros reside in SYS$LIBRARY:LIB.MLB.

    Three macros are used for image initialization-time lockdown, and
    two macros are used for on-the-fly lockdown.

                                   NOTE

       If the code is being locked because the IPL will be raised
       above 2, where page faults cannot occur, make sure that
       the delimited code does not call run-time library or other
       procedures. The VAX MACRO compiler generates calls to
       routines to emulate certain VAX instructions. An image that
       uses these macros must link against the system base image so
       that references to these routines are resolved by code in a
       nonpageable executive image.

1 - Image Initialization-Time Lockdown

    The three macros for image initialization-time lockdown follow:

    o  $LOCK_PAGE_INIT

    o  $LOCKED_PAGE_END

    o  $LOCKED_PAGE_START

 1.1 - $LOCK PAGE INIT

    Required in the initialization routines of an image that is using
    $LOCKED_PAGE_START and $LOCKED_PAGE_END to delineate areas to be
    locked at initialization time.

    Format

      $LOCK_PAGE_INIT  [error]

 1. 1.1 - Parameters

 [error]

    Address to which to branch if one of the $LKWSET calls fail. If
    this address is reached, R0 reflects the status of the failed
    call, and R1 contains 0 if the call to lock the code failed, or 1
    if that call succeeded but the call to lock the linkage section
    failed.

 1. 1.2 - Description

    $LOCK_PAGE_INIT creates the necessary psects and issues the
    $LWKSET calls to lock into the working set the code and linkage
    sections that were declared by $LOCKED_PAGE_START and $LOCKED_
    PAGE_END. R0 and R1 are destroyed by this macro.

    The psects locked by this macro are $LOCK_PAGE_2 and $LOCK_
    LINKAGE_2. If code sections in other modules, written in other
    languages, use these psects, they will be locked by an invocation
    of this macro in a VAX MACRO module.

 1.2 - $LOCKED PAGE END

    Marks the end of a section of code that may be locked at image
    initialization time by the $LOCK_PAGE_INIT macro.

    Format

      $LOCKED_PAGE_END  [link_sect]

 1. 2.1 - Parameters

 [link_sect]

    Psect to return to if the linkage psect in effect when the
    $LOCKED_PAGE_START macro was executed was not the default linkage
    psect, $LINKAGE.

 1. 2.2 - Description

    $LOCKED_PAGE_END is used with $LOCKED_PAGE_START to delineate
    code that may be locked at image initialization time by the
    $LOCK_PAGE_INIT macro. The code delineated by these macros must
    contain complete routines-execution cannot fall through either
    macro, nor can you branch into or out of the locked code. Any
    attempt to branch into or out of the locked code section or to
    fall through the macros will be flagged by the compiler with an
    error.

 1.3 - $LOCKED PAGE START

    Marks the start of a section of code that may be locked at image
    initialization time by the $LOCK_PAGE_INIT macro.

    Format

      $LOCKED_PAGE_START

    There are no parameters for this macro.

 1. 3.1 - Description

    $LOCKED_PAGE_START is used with $LOCKED_PAGE_END to delineate
    code that may be locked at image initialization time by the
    $LOCK_PAGE_INIT macro. The code delineated by these macros must
    contain complete routines-execution may not fall through either
    macro, nor may the locked code be branched into or out of. Any
    attempt to branch into or out of the locked code section or to
    fall through the macros will be flagged by the compiler with an
    error.

2 - On-the-Fly Lockdown

    The two macros for on-the-fly lockdown follow:

    o  $LOCK_PAGE

    o  $UNLOCK_PAGE

 2.1 - $LOCK PAGE

    Marks the beginning of a section of code to be locked on the fly.

    Format

      $LOCK_PAGE  [error]

 2. 1.1 - Parameters

 [error]

    Address to branch to if one of the $LKWSET calls fail.

 2. 1.2 - Description

    This macro is placed inline in executable code and must be
    followed by the $UNLOCK_PAGE macro. The $LOCK_PAGE/$UNLOCK_PAGE
    macro pair creates a separate routine in a separate psect. $LOCK_
    PAGE locks the pages and linkage section of this separate routine
    into the working set and JSRs to it. All code between this macro
    and the matching $UNLOCK_PAGE macro is included in the locked
    routine and is locked down.

    All registers are preserved by this macro unless the error
    address parameter is present and one of the calls fail. If that
    happens, R0 reflects the status of the failed call. R1 then
    contains 0 if the call to lock the code failed or 1 if that call
    succeeded but the call to lock the linkage section failed.

    If the ERROR parameter is used, the ERROR label must be placed
    outside the scope of the $LOCK_PAGE and $UNLOCK_PAGE pair. This
    is because the error routine is branched to before calling the
    subroutine that the $LOCK_PAGE and $UNLOCK_PAGE routines create.

    Note that since the locked code is made into a separate routine,
    any references to local stack storage within the routine will
    have to be changed, as the stack context is no longer the same.
    Also, you cannot branch into or out of the locked code from the
    rest of the routine.

 2.2 - $UNLOCK PAGE

    Marks the end of a section of code to be locked on the fly.

    Format

      $UNLOCK_PAGE  [error][,LINK_SECT]

 2. 2.1 - Parameters

 [error]

    An error address to which to branch if one of the $ULKWSET calls
    fail.

 [link_sect]

    Linkage psect to return to if the linkage psect in effect when
    the $LOCK_PAGE macro was executed was not the default linkage
    psect, $LINKAGE.

 2. 2.2 - Description

    $UNLOCK_PAGE returns from the locked routine created by the
    $LOCK_PAGE and $UNLOCK_PAGE macro pair and then unlocks the pages
    and linkage section from the working set. This macro is placed
    inline in executable code after a $LOCK_PAGE macro.

    All registers are preserved by this macro unless the error
    address parameter is present and one of the calls fail. If that
    happens, R0 reflects the status of the failed call. R1 then
    contains 0 if the call to unlock the code failed or 1 if that
    call succeeded but the call to unlock the linkage section failed.

    If the error parameter is used, the error label must be placed
    outside the scope of the $LOCK_PAGE and $UNLOCK_PAGE pair. This
    is because the error routine is branched to after returning
    from the subroutine created by the $LOCK_PAGE and $UNLOCK_PAGE
    routines.