graPHIGS Programming Interface: Subroutine Reference

The graPHIGS Programming Interface : Subroutine Reference

GPRVSN - Retrieve Structure Networks

GPRVSN (arid, number, lstrid)

Purpose

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

If any of the specified root 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 root 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 any of the specified structures in the structure networks 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:

GPCLST - Close Structure

GPEST - Empty Structure

GPRVST - Retrieve Structures

GPOPST - Open Structure

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 root structure identifier entries in the list (>=1)

lstrid -- specified by user, array of fullword integers

A list of root 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
GPRVST: Retrieve Structures

RCP code

201348616 (X'0C005608')