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

Chapter 14. Inquire Subroutines

Inquiry programming subroutines allow application programs to obtain information such as the following:

Note:

The graPHIGS API returns SET values for both REALIZED and SET output parameters.

General information for C binding inquiry subroutines

The graPHIGS API often requires a store parameter of type Pstore as input. See the Create Store ( CREATE STORE (PHOP,*,*,*)) subroutine for details on how the graPHIGS API uses this parameter on inquiries.

start_ind is an input parameter for inquiries that request simple lists. An index of zero specifies the first element in the graPHIGS API list, therefore, zero is a valid value for parameter start_ind. start_ind indicates the element in the graPHIGS API list that you want copied into index zero of the application's list.

General information for FORTRAN binding inquiry subroutines

If the nth list element that you requested is unavailable, then the graPHIGS API returns the error 2002 in the error indicator parameter and also returns the implementation's list length.

If you request the 0th list element, then the list element is undefined, but the graPHIGS API generates no error and returns the implementation's list length.

ELEMENT SEARCH (PHOP,*,*,*)

Purpose

Use Element Search to search through a specified structure for an element that matches a given criteria. The search starts at a specified element position and searches in a designated direction (BACKWARD or FORWARD) until the graPHIGS API either finds an element that matches the criteria or reaches the limits of the structure.

Search criteria: The graPHIGS API selects an element if the type of the element is in the element inclusion list and not in the element exclusion list.

Element exclusion: The graPHIGS API excludes an element if the element type is either not in the inclusion list or it is in the exclusion list.

Starting search position: The search starts at element position of zero if the specified starting position is less than zero. The search starts with the last element in the structure, if the specified starting position is larger than the number of elements in the structure.

If the search is successful, then the application sets the status indicator to SUCCESS, and the graPHIGS API returns the element position in the position parameter. Otherwise, the application sets the status indicator to FAILURE and the value returned in the position parameter is unpredictable.

If the information is available, then the graPHIGS API sets the error indicator to zero and returns the values in the output parameters. If the information is unavailable, then the values returned in the output parameters are unpredictable and the graPHIGS API sets the error indicator to one of the following errors:

2
Function Requires State (PHOP,*,*,*)
201
Specified Structure Does Not Exist

Language Bindings

C

pelem_search (struct_id, start_elem, dir, incl, excl, err_ind, status, found_elem_ptr);

Input Parameters

Pint struct_id
Structure identifier.

Pint start_elem
Starting element position (>=0).

Psearch_dir dir
Search direction (0=PDIR_BACKWARD, 1=PDIR_FORWARD).

const Pelem_type_list *incl
Element inclusion list (0=PELEM_ALL, 1=PELEM_NIL, 2=PELEM_POLYLINE3, 3=PELEM_POLYLINE, 4=PELEM_POLYMARKER3, 5=PELEM_POLYMARKER, 6=PELEM_TEXT3, 7=PELEM_TEXT, 8=PELEM_ANNO_TEXT_REL3, 9=PELEM_ANNO_TEXT_REL, 10=PELEM_FILL_AREA3, 11=PELEM_FILL_AREA, 12=PELEM_FILL_AREA_SET3, 13=PELEM_FILL_AREA_SET, 14=PELEM_CELL_ARRAY3, 15=PELEM_CELL_ARRAY, 16=PELEM_GDP3, 17=PELEM_GDP, 18=PELEM_LINE_IND, 19=PELEM_MARKER_IND, 20=PELEM_TEXT_IND, 21=PELEM_INT_IND, 22=PELEM_EDGE_IND, 23=PELEM_LINETYPE, 24=PELEM_LINEWIDTH, 25=PELEM_LINE_COLR_IND, 26=PELEM_MARKER_TYPE, 27=PELEM_MARKER_SIZE, 28=PELEM_MARKER_COLR_IND, 29=PELEM_TEXT_FONT, 30=PELEM_TEXT_PREC, 31=PELEM_CHAR_EXPAN, 32=PELEM_CHAR_SPACE, 33=PELEM_TEXT_COLR_IND, 34=PELEM_CHAR_HT, 35=PELEM_CHAR_UP_VEC, 36=PELEM_TEXT_PATH, 37=PELEM_TEXT_ALIGN, 38=PELEM_ANNO_CHAR_HT, 39=PELEM_ANNO_CHAR_UP_VEC, 40=PELEM_ANNO_PATH, 41=PELEM_ANNO_ALIGN, 42=PELEM_ANNO_STYLE, 43=PELEM_INT_STYLE, 44=PELEM_INT_STYLE_IND, 45=PELEM_INT_COLR_IND, 46=PELEM_EDGE_FLAG, 47=PELEM_EDGETYPE, 48=PELEM_EDGEWIDTH, 49=PELEM_EDGE_COLR_IND, 50=PELEM_PAT_SIZE, 51=PELEM_PAT_REF_POINT_VECS, 52=PELEM_PAT_REF_POINT, 53=PELEM_ADD_NAMES_SET, 54=PELEM_REMOVE_NAMES_SET, 55=PELEM_INDIV_ASF, 56=PELEM_HLHSR_ID, 57=PELEM_LOCAL_MODEL_TRAN3, 58=PELEM_LOCAL_MODEL_TRAN, 59=PELEM_GLOBAL_MODEL_TRAN3, 60=PELEM_GLOBAL_MODEL_TRAN, 61=PELEM_MODEL_CLIP_VOL3, 62=PELEM_MODEL_CLIP_VOL, 63=PELEM_MODEL_CLIP_IND, 64=PELEM_RESTORE_MODEL_CLIP_VOL, 65=PELEM_VIEW_IND, 66=PELEM_EXEC_STRUCT, 67=PELEM_LABEL, 68=PELEM_APPL_DATA, 69=PELEM_GSE, 70=PELEM_PICK_ID).

const Pelem_type_list *excl
Element exclusion list (Enumerated types are the same as that of the element inclusion list).

Output Parameters

Pint *err_ind
Error indicator.

Psearch_status *status
Search status indicator (0=PSEARCH_STATUS_FAILURE, 1=PSEARCH_STATUS_SUCCESS).

Pint *found_elem_ptr
Found element position.

FORTRAN

PELS (strid, strtep, srcdir, eisn, eis, eesn, ees, errind, status, fndep)

Input Parameters

integer strid
Structure identifier.

integer strtep
Start element position(>=0).

integer srcdir
Search direction (0=PBWD, 1=PFWD).

integer eisn
Number of elements in the element inclusion set.

integer eis(eisn)
Element inclusion set (0=PEALL, 1=PENIL, 2=PEPL3, 3=PEPL, 4=PEPM3, 5=PEPM, 6=PETX3, 7=PETX, 8=PEATR3, 9=PEATR, 10=PEFA3, 11=PEFA, 12=PEFAS3, 13=PEFAS, 14=PECA3, 15=PECA, 16=PEGDP3, 17=PEGDP, 18=PEPLI, 19=PEPMI, 20=PETXI, 21=PEII, 22=PEEDI, 23=PELN, 24=PELWSC, 25=PEPLCI, 26=PEMK, 27=PEMKSC, 28=PEPMCI, 29=PETXFN, 30=PETXPR, 31=PECHXP, 32=PECHSP, 33=PETXCI, 34=PECHH, 35=PECHUP, 36=PETXP, 37=PETXAL, 38=PEATCH, 39=PEATCU, 40=PEATP, 41=PEATAL, 42=PEANST, 43=PEIS, 44=PEISI, 45=PEICI, 46=PEEDFG, 47=PEEDT, 48=PEEWSC, 49=PEEDCI, 50=PEPA, 51=PEPRPV, 52=PEPARF, 53=PEADS, 54=PERES, 55=PEIASF, 56=PEHRID, 57=PELMT3, 58=PELMT, 59=PEGMT3, 60=PEGMT, 61=PEMCV3, 62=PEMCV, 63=PEMCLI, 64=PERMCV, 65=PEVWI, 66=PEEXST, 67=PELB, 68=PEAP, 69=PEGSE, 70=PEPKID).

integer eesn
Number of elements in the element exclusion set.

integer ees(eesn)
Element exclusion set (Enumerated types are the same as that of the element inclusion set).

Output Parameters

integer errind
Error indicator.

integer status
Status indicator (0=PFAIL, 1=PSUCC).

integer fndep
Found element position.

Errors

None

Related Subroutines

  • None

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