RETRIEVE STRUCTURE IDENTIFIERS(3P) — SUNPHIGS LIBRARY

NAME

RETRIEVE STRUCTURE IDENTIFIERS − retrieve a list of structure identifiers from an archive file

SYNOPSIS

C Syntax

void
pretrievestructids ( archive_id, max_ids, start, ids, actual_ids )
Pintarchive_id;archive identifier
Pintmax_ids;size of appl. archive id list
Pintstart;start position of ids
Pintlst∗ids;OUT list of structure ids
Pint∗actual_ids;OUT actual number of ids in PHIGS

FORTRAN Syntax

SUBROUTINE prsid ( AFID, ILSIZE, N, LSTRID )
INTEGERAFIDarchive file identifier
INTEGERILSIZEsize of the list (LSTRID)
INTEGERNOUT number of structure identifiers in the list
INTEGERLSTRID(∗)OUT list of structure identifiers

Required PHIGS Operating States

(PHOP, ∗, ∗, AROP)

DESCRIPTION

Purpose

Use RETRIEVE STRUCTURE IDENTIFIERS to retrieve a list of the identifiers of all structures archived in the specified open archive file.

C Input Parameters

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

max_ids
The number of integers items in the ids output parameter for which the application has allocated memory. max_ids is the number of list elements (archive structure identifiers) that the system can return in ids−>integers. If a value of 0 is used here, no data will be returned in the ids−>integers list, but the total number of structure identifiers in the archive file will be returned in actual_ids.

startStarting position in the list of archive structure identifiers at which to begin the inquiry. The elements of the list of structure identifiers, beginning with the item number specified by start, are copied sequentially into ids−>integers until ids−>integers is full or all the structure identifiers have been copied.

C Output Parameters

idsA pointer to a Pintlst structure in which the list of structure identifiers in the specified open archive file is returned. 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. The application must allocate memory for max_ids elements in the ids−>integers list.

actual_ids
A pointer to an integer in which the total number of structure identifiers in the specified archive file is returned. This is the value required for max_ids if all structure identifiers are to be returned.

FORTRAN Input Parameters

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

ILSIZE
The size of the LSTRID array. ILSIZE is the number of list elements (archive structure identifiers) that the system can return in LSTRID. If this value is smaller than the actual number of archive structure identifiers (N), no data will be returned in the LSTRID array, but N will be set to indicate the array size required. If you call this function with an array size of zero, N is returned with the required array size. Error 2001 is returned if ILSIZE is too small, but not if it’s zero.

FORTRAN Output Parameters

NThe number of archive structure identifiers returned in the LSTRID array.

LSTRID
An array of integers in which the list of structure identifiers in the specified archive file is returned.

ERRORS

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

404Ignoring function, the specified archive file is not open

Museum