VMS Help System Services, $UPDSEC  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    Writes all modified pages in an active private or global section
    back into the section file on disk. One or more I/O requests are
    queued, based on the number of pages that have been modified.

    Format

      SYS$UPDSEC  inadr ,[retadr] ,[acmode] ,[updflg] ,[efn] ,[iosb]

                  ,[astadr] ,[astprm]

    C Prototype

      int sys$updsec  (struct _va_range *inadr, struct _va_range

                      *retadr, unsigned int acmode, char updflg,

                      unsigned int efn, struct _iosb *iosb, void

                      (*astadr)(__unknown_params), int astprm);

    Arguments

 inadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference-array reference or descriptor
    Starting and ending virtual addresses of the pages that are to
    be written to the section file if they have been modified. The
    inadr argument is the address of a 2-longword array containing,
    in order, the starting and ending process virtual addresses.
    Addresses are adjusted up or down to CPU-specific pages.

    Only the virtual page number portion of each virtual address is
    used; the low-order byte-within-page bits are ignored.

    $UPDSEC scans pages starting at the address contained in the
    first longword specified by inadr and ending at the address
    contained in the second longword. Within this range, $UPDSEC
    locates read/write pages that have been modified and writes
    them (contiguously, if possible) to the section file on disk.
    Unmodified pages are also written to disk if they share the same
    cluster with modified pages.

    If the starting and ending virtual addresses are the same, a
    single page is written to the section file if the page has been
    modified.

    The address specified by the second longword might be smaller
    than the address specified by the first longword.

 retadr

    OpenVMS usage:address_range
    type:         longword (unsigned)
    access:       write only
    mechanism:    by reference-array reference or descriptor
    Addresses of the first and last pages that were actually queued
    for writing, in the first $QIO request, back to the section file
    on disk. The retadr argument is the address of a 2-longword array
    containing, in order, the addresses of the first and last pages.
    Addresses always are adjusted up or down to fall on CPU-specific
    boundaries.

    If $UPDSEC returns an error condition value in R0, each longword
    specified by retadr contains the value -1. In this case, an event
    flag is not set, no asynchonous system trap (AST) is delivered,
    and the I/O status block is not written to.

 acmode

    OpenVMS usage:access_mode
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Access mode on behalf of which the service is performed. The
    acmode argument is a longword containing the access mode. The
    $PSLDEF macro defines the symbols for the four access modes.

    The most privileged access mode used is the access mode of the
    caller. A page cannot be written to disk unless the access mode
    used by $UPDSEC is equal to or more privileged than the access
    mode of the owner of the page to be written.

 updflg

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Update specifier for read/write global sections. The updflg
    argument is a longword value. The value 0 (the default) specifies
    that all read/write pages in the global section are to be written
    to the section file on disk, whether or not they have been
    modified. The value 1 specifies that the caller is the only
    or the last process having the global section mapped for write
    access and that only modified pages should be written to the
    section file on disk.

 efn

    OpenVMS usage:ef_number
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Event flag to be set when the section file on disk is actually
    updated. The efn argument is a longword specifying the number of
    the event flag; however, $UPDSEC uses only the low-order byte.

    If you do not specify efn, event flag 0 is used.

    When you invoke $UPDSEC, the specified event flag or event flag 0
    is cleared; when the update operation is complete, the event flag
    is set.

 iosb

    OpenVMS usage:io_status_block
    type:         quadword (unsigned)
    access:       write only
    mechanism:    by reference
    I/O status block to receive the final completion status of the
    updating operation. The iosb argument is the address of the
    quadword I/O status block.

    When you invoke $UPDSEC, the I/O status block is cleared. After
    the update operation is complete, that is, when all I/O to the
    disk is complete, the I/O status block is written as follows:

    o  The first word contains the condition value returned by $QIO,
       indicating the final completion status.

    o  The first bit in the second word is set only if an error
       occurred during the I/O operation and the error was a hardware
       write error. The remaining bits of the second word are zeros.

    o  The second longword contains the virtual address of the first
       page that was not written.

    Though this argument is optional, Compaq strongly recommends that
    you specify it for the following reasons:

    o  If you are using an event flag to signal the completion of
       the service, you can test the I/O status block for a condition
       value to be sure that the event flag was not set by an event
       other than service completion.

    o  If you are using $SYNCH to synchronize completion of the
       service, the I/O status block is a required argument for
       $SYNCH.

    o  The condition value returned in R0 and the condition value
       returned in the I/O status block provide information about
       different aspects of the call to $UPDSEC. The condition
       value returned in R0 gives you information about the success
       or failure of the service call itself; the condition value
       returned in the I/O status block gives you information about
       the success or failure of the service operation. Therefore,
       to accurately assess the success or failure of the call to
       $UPDSEC, you must check the condition values returned in both
       R0 and the I/O status block.

 astadr

    OpenVMS usage:ast_procedure
    type:         procedure value
    access:       call without stack unwinding
    mechanism:    by reference-procedure reference or descriptor
    AST routine to be executed when the section file has been
    updated. The astadr argument is the address of this routine.

    If you specify astadr, the AST routine executes at the access
    mode from which the section file update was requested.

 astprm

    OpenVMS usage:user_arg
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    AST parameter to be passed to the AST routine. The astprm
    argument is this longword parameter.