VMS Help PSM Routines, PSM$REPORT  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The PSM$REPORT routine reports to the print symbiont the
    completion status of an asynchronous operation initiated by a
    user routine.

    Such a user routine must return the completion status PSM$_
    PENDING. PSM$REPORT must be called exactly once for each time
    a user routine returns the status PSM$_PENDING.

    Format

      PSM$REPORT  request_id [,status]

1 - Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. Most utility routines return a
    condition value in R0. The condition value that this routine
    can return is listed under Condition Value Returned.

2 - Arguments

 request_id

    OpenVMS usage:address
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Request identifier supplied by the symbiont to the user routine
    at the time the symbiont called the user routine with the service
    request. The user routine must return the completion status PSM$_
    PENDING on the call for this service request. The request_id
    argument is the address of a longword containing the request
    identifier value.

    The symbiont calls the user routine with a request code that
    specifies the function that the symbiont expects the user
    routine to perform. In the call, the symbiont also supplies a
    request identifier, which serves to identify the request. If the
    user routine initiates an asynchronous operation, a mechanism
    is required for notifying the symbiont that the asynchronous
    operation has completed and for providing the completion status
    of the operation.

    The PSM$REPORT routine conveys the above two pieces of
    information. In addition, PSM$REPORT returns to the symbiont
    (in the request_id argument) the same request identifier value
    as that supplied by the symbiont to the user routine that
    initiated the operation. In this way, the symbiont synchronizes
    the completion status of an asynchronous operation with that
    invocation of the user routine that initiated the operation.

    Any user routine that initiates an asynchronous operation must,
    therefore, copy the request identifier value that the symbiont
    supplies (in the request_id argument) when it calls the user
    routine. The user routine will later need to supply this value to
    PSM$REPORT.

    In addition, when the user routine returns, which it does before
    the asynchronous operation has completed, the user routine must
    return the status PSM$_PENDING.

 status

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Completion status of the asynchronous operation that has
    completed. The status argument is the address of a longword
    containing this completion status. The status argument is
    optional; if it is not specified, the symbiont assumes the
    completion status SS$_NORMAL.

    The user routine that initiates the asynchronous operation
    must test for the completion of the operation and must supply
    the operation's completion status as the status argument to
    the PSM$REPORT routine. The Description section describes this
    procedure in greater detail.

    If the completion status specified by status has the low bit
    clear, the symbiont aborts the task.

3 - Description

    An asynchronous operation is an operation that, once initiated,
    executes "off to the side" and need not be completed before other
    operations can begin to execute. Asynchronous operations are
    common in symbiont applications because a symbiont, if it is
    multithreaded, must handle concurrent I/O operations.

    One example of a user routine that performs an asynchronous
    operation is an output routine that calls the $QIO system service
    to write a record to the printing device. When the user output
    routine completes execution, the I/O request queued by $QIO might
    not have completed. In order to synchronize this I/O request,
    that is, to associate the I/O request with the service request
    that initiated it, you should use the following mechanism:

    1. In making the call to $QIO, specify the astadr and iosb
       arguments. The astadr argument specifies an AST routine to
       execute when the queued output request has completed, and the
       iosb argument specifies an I/O status block to receive the
       completion status of the I/O operation. Step 3 describes some
       functions that your AST routine will need to do.

    2. Have the user output routine return the status PSM$_PENDING.

    3. Write the AST routine to perform the following functions:

       a. Copy the completion status word from the I/O status block
          to a longword location that you will specify as the status
          argument in the call to PSM$REPORT.

       b. Call PSM$REPORT. Specify as the request_id argument the
          request identifier that was supplied by the print symbiont
          in the original call to the user output routine.

4 - Condition Value Returned

    SS$_NORMAL         Normal successful completion.