RETRIEVE STRUCTURES(3P) — SUNPHIGS LIBRARY

NAME

RETRIEVE STRUCTURES − retrieve specified structures from an archive file

SYNOPSIS

C Syntax

void
pretrievestruct ( archive_id, struct_ids )
Pintarchive_id;archive identifier
Pintlst∗struct_ids;list of structure identifiers

FORTRAN Syntax

SUBROUTINE prest ( AFID, N, LSTRID )
INTEGERAFIDarchive file identifier
INTEGERNnumber of structure identifiers in the list
INTEGERLSTRID(N)list of structure identifiers

Required PHIGS Operating States

(PHOP, ∗, ∗, AROP)

DESCRIPTION

Purpose

Use RETRIEVE STRUCTURES to retrieve a list of structures from the specified open archive file into the Central Structure Store.

C Input Parameters

archive_id
The archive identifier specifying the open archive file to read from.

struct_ids
A pointer to a Pintlst structure containing the list of structure identifiers to be retrieved. The Pintlst structure is defined in phigs.h as follows:

typedef struct {
Pintnumber;/∗ number of Pints in list ∗/
Pint∗integers;/∗ list of integers ∗/
} Pintlst;

The number component specifies the number of structure identifiers in the list. The integers component is a pointer to a list, number long, of the structure identifiers.

FORTRAN Input Parameters

AFIDThe archive identifier specifying the open archive file to read from.

NThe number of structure identifiers to be retrieved.

LSTRID
An array of integers containing the structure identifiers to be retrieved.

Execution

The specified structures are copied from the indicated open archive file into the Central Structure Store. If any of the structures to be retrieved currently exist in the Central Structure Store, the conflict is resolved as follows:

• If the retrieval conflict resolution flag is MAINTAIN, the conflicting structure will not be copied into the Central Structure Store (its contents are maintained) • If the retrieval conflict resolution flag is UPDATE, the conflicting structure in the Central Structure Store will be overwritten (its contents are updated) • If the retrieval conflict resolution flag is ABANDON, no structures will be copied to the Central Structure Store at all.

The retrieval conflict resolution flag is set by the SET CONFLICT RESOLUTION subroutine.

If the currently open structure must be overwritten because of a conflict while the retrieval conflict resolution flag is UPDATE, it is closed, its contents are overwritten, and it is re-opened. The element pointer will be set to point to the last element.

If any of the structures to be retrieved do not exist in the archive file, an empty structure is created in the Central Structure Store, a warning is generated, and the retrieval operation continues for the remaining structures.

ERRORS

007Ignoring function, function requires state (PHOP, ∗, ∗, AROP)

404Ignoring function, the specified archive file is not open

405Ignoring function, name conflict occurred while conflict resolution flag has value ABANDON

408Warning, some of the specified structures do not exist on the archive file. PHIGS will create empty structures in their places

Museum