[ Previous | Next | Contents | Glossary | Home | Search ]
The graPHIGS Programming Interface : Subroutine Reference

GPRVST - Retrieve Structures

GPRVST (arid, number, lstrid)

Purpose

Use GPRVST to retrieve one or more structures from the specified open archive file and place them into the currently selected structure store.

If any of the specified structures do not exist in the specified archive file and the specified structure identifier does not exist in the current structure store, then the graPHIGS API issues a warning and creates an empty structure. If any of the specified structures do not exist in the specified archive file and the specified structure identifier does exist in the current structure store and the conflict resolution flag is set to 3=UPDATE , then the graPHIGS API empties the structure.

If one of the specified structures already exists in the structure store, then the graPHIGS API resolves the conflict according to the value of the archive conflict resolution flag specified by the Set Conflict Resolution (GPCNRS) subroutine.

Note:

The graPHIGS API empties the structure in the target structure store before it copies the source structure. If an error occurs (such as the copying of a structure cannot be completed), then the original structure cannot be reconstructed.
When you retrieve a structure that is an open structure, the structure is closed, emptied, retrieved, and reopened and the graPHIGS API maintains all references to the structure. The result is as though you had issued the following:

  1. GPCLST - Close Structure

  2. GPEST - Empty Structure

  3. GPRVST - Retrieve Structures

  4. GPOPST - Open Structure
    5. If the structure retrieved contains an execute structure-type element that references a non-existing structure, then the graPHIGS API creates an empty structure.

    Currently, the archive file resource and the structure store must reside on the same nucleus. If the two resources are on different nuclei, then the graPHIGS API issues error 1109

    Parameters

    arid -- specified by user, fullword integer

    Archive file identifier.

    number -- specified by user, fullword integer

    Number of structure identifier entries in the list (>=1)

    lstrid -- specified by user, array of fullword integers

    A list of structure identifiers.

    Error Codes

    7
    FUNCTION REQUIRES STATE AROP
    12
    FUNCTION REQUIRES STATE SSSL
    120
    WARNING, ONE OR MORE STRUCTURES DO NOT EXIST
    128
    STRUCTURE CONFLICT OCCURS WHEN RESOLUTION FLAG IS ABANDON
    134
    NUMBER OF ENTRIES IN LIST < ONE
    220
    SPECIFIED ARCHIVE FILE DOES NOT EXIST
    594
    DATA EXCEEDS CONNECTION BUFFER SIZE
    614
    UNKNOWN ELEMENT FOUND IN STRUCTURE n1
    1109
    FUNCTION NOT SUPPORTED

    Related Subroutines

    GPCNRS
    Set Conflict Resolution
    GPRVAS
    Retrieve All Structures
    GPRVSN
    Retrieve Structure Networks

    RCP code

    201348615 (X'0C005607')

    [ Previous | Next | Contents | Glossary | Home | Search ]