The graPHIGS Programming Interface: Understanding Concepts

Chapter 8. Structure Editing

In Chapter 3. "Structures" you learned how to define structure content. The graPHIGS API also provides powerful subroutine calls that enable your application to edit the content (elements) of those structures. In addition to discussing those subroutines, this chapter discusses the operations that affect entire structures.

As you read this chapter, keep in mind that structure content editing operations require an open structure. Operations that affect entire structures do not require an open structure.

Structure Content Editing

When an application program opens a structure, the element pointer points to the last element of the structure. In an empty structure, the element pointer points to the null element, conceptually element zero.

Your application can add elements one after another, because the graPHIGS API automatically increments the element pointer to each new element.

Inserting Structure Elements

In order to edit an element within a structure, your application must position the element pointer. When processing a subroutine call that creates an element, the system either inserts that element into the structure after the current element pointer or replaces the element pointed to by the element pointer. The Set Edit Mode (GPEDMO) subroutine controls whether the elements are inserted or replaced. The default Edit Mode is 1=INSERT_MODE Therefore, to insert an element, your application must position the element pointer at the element immediately before the insertion location.

The graPHIGS API provides the Set Element Pointer GPEP subroutine to position the element pointer at any element position within a structure.

If your application specifies a negative number or a zero, in the GPEP subroutine, the system sets the element pointer at conceptual element zero.

If your application specifies a number in the GPEP subroutine that is greater than the last element's number, the system sets the element pointer at the last element.

The figure, "Inserting Elements," depicts a scenario in which your application inserts two label elements into an existing structure. Notice that your application could have chosen to insert any other valid structure element instead.

The graPHIGS API provides the Insert Label (GPINLB) subroutine in order to create a label element within a structure. Your application assigns an integer identifier to each label. These integer identifiers do not need to be unique.

A label is a type of structure element. It may be used for anything. It has no graphical effect. The graPHIGS API provides labels so your application can more easily edit structure content.

With labels, your application can delineate an element or group of elements, then later find that element or element group by advancing the element pointer to a specified label.

In the figure, "Inserting Elements," your application opens the structure with the GPOPST subroutine. After opening the structure, the current element pointer points to the last element in the structure.

In this scenario, your application uses the GPEP subroutine to position the element pointer immediately before the desired insertion point.

Your application then inserts a label "d", using the GPINLB subroutine. After the insertion, the system positions the current element pointer at the inserted element, and renumbers the following elements.

Next, your application uses the Offset Element Pointer (GPOEP) subroutine to position the element pointer forward or backward in the structure. The system adds the positive or negative offset value specified in the GPOEP subroutine to the current element pointer value. If the resulting value would move the element pointer outside of the structure, the system moves the element pointer to the nearest end of the structure, and issues a warning.

After your application uses the GPINLB subroutine to insert another label "g", the system renumbers the following elements.

Another way to position the element pointer is by using one of the following subroutines:

Set Element Pointer at Label (GPEPLB)
Set Element Pointer at Pick Identifier (GPEPPK)
Locate Element Pointer at Element Code (GPEPCD)

GPEPLB lets your application position the element pointer at any label element within an open structure. GPEPPK does the same for PICK identifier elements. GPEPCD positions the element pointer for any structure element based on the element's identifier code.

Your application locates a label, PICK identifier, or element code by specifying its integer identifier. The system searches for the next label that has the specified integer identifier, starting at the element immediately after the current element pointer. When it finds the identifier, it moves the element pointer to that position in the structure.

If the system encounters the end of a structure, it resets the element pointer to the first element and continues searching for the integer identifier until it finds it or reaches the start element.

Structures can contain more than one label with the same integer identifier. When they do, invoking GPEPLB advances the element pointer to the next label containing the specified integer identifier. GPEPPK operates in an identical fashion.

Deleting Structure Elements

The graPHIGS API lets your application program delete elements or groups of elements in the following ways:

By deleting an individual element
By deleting the elements within a specified range
By deleting the elements between two labels.

Whenever your application deletes an element, or group of elements, the system sets the element pointer to the element before the deleted element or group of elements using method one or two. This lets your application add new elements into the deleted location without moving the element pointer. When using method three, your application can leave the element pointer at either label.

Deleting Individual Elements

To delete an individual element, your application sets the element pointer to the desired element, then deletes that element using the Delete Element (GPDLE) subroutine. After deletion, the API sets the element pointer to the element preceding the deleted element. The figure, "Deleting One Element," depicts the results of deleting one element.

Deleting Elements within a Specified Range

To delete a range of elements, your application specifies a range of element numbers with the Delete Range (GPDLER) subroutine. The system deletes all elements within the range, including the specified range elements.

If either number specified in the GPDLER subroutine is outside of the structure's range, the system maps that number to the closest end of the structure. For example, if the structure has 20 elements and your application tries to delete the elements between 12 and 30, the system deletes the elements between 12 and 20.

In addition, your application program can specify the numbers in either order. Deleting elements between 12 and 30 has the same effect as deleting elements between 30 and 12.

After deleting the elements, the system moves the element pointer to the element immediately before the deleted range, regardless of element pointer's previous position.

The figure, "Results of Deleting a Range of Elements," depicts the results of deleting a range of elements.

Deleting Elements between Labels

To delete elements between two labels, your application specifies two labels by using a Delete Element Between Labels (GPDELB) or Delete Element Group (GPDLEG) subroutines.

When your application issues a GPDELB subroutine, the system initiates a search for the first occurrence of label one, starting at the element pointer's current position. If the search reaches the end of the structure, it continues from the beginning of the structure. After finding the first label, the system searches for label two in the same manner, including starting at the same original element pointer position. The same label structure element will not match both labels if the same label id is specified.

When the system finds both labels, it deletes all elements between, but not including the labels. Notice that the order in which your application specifies the labels affects the position of the element pointer after the deletion. The system resets the element pointer to the first label specified in the GPDELB subroutine. This allows your application to delete the same range and leave the element pointer in either location.

If the system does not find either label, it reports an error.

The function of the GPDLEG subroutine is similar to the GPDELB subroutine in that two labels are specified to delineate a group of elements to be deleted. GPDLEG differs from GPDELB in the following ways

If the system does not find either label from the start of the search to the end of the structure, an error is generated and the search is discontinued.
The search for the second label starts at the position of the first label.
Either, both, or neither of the search labels can optionally be deleted as part of the element group.

The figure, "Deleting Elements Between Labels," depicts the results of deleting elements between specified labels using the GPDELB subroutine. In the figure, elements "j" and "m" are labels.

The graPHIGS API lets your application specify duplicate labels within structures. However, you should exercise caution when deleting elements between duplicate labels.

Copying and Moving Structure Elements

The Copy Structure (GPCPST) subroutine lets your application copy the entire contents of one structure into another. The system copies all of the elements of a specified structure into the currently open structure at the location immediately following the current element pointer. The API then moves the current element pointer to the last inserted element. The figure, "Copying a Structure," depicts how a copy structure instruction from your application is handled. Note that the copied elements are inserted into the structure even if the structure Edit Mode is set to 2=REPLACE_MODE

The Copy Element Range (GPCPER) subroutine copies a range of elements from the specified structure, into the open structure following the current element pointer. The API then moves the current element pointer to the last inserted element.

Using the current element pointer, the Move Element Range (GPMVER) subroutine lets your application move a range of elements to the the location following the element pointer. The API then moves the current element pointer to the last element that was moved.

Closing Structures

The graPHIGS API lets your application close an open structure. When your application finishes editing the open structure, it must close the structure before opening another structure. It closes the currently open structure by using the Close Structure (GPCLST) subroutine.

Modified Sample Program 1
Modifying the sample program according to the following statements will enable you to interactively edit the house structure. In the `DECLARE VARIABLES` section, add the following statements: INTEGERx4 ACTNUM,ACTLEN,CDATA(2),TERM In this same section, modify the data length and data of the choice input device initialization parameters. First, modify the dimension of the *variable Data* You should have `DATA(4)` Change it to `DATA(7)` Then modify the `DATA` statements as follows: DATA DATA /28/ DATA DATA /4,0,0,2,1,1,2/ These changes will light the first and fourth Lighted Program Function Key (LPFK). In this same section, change the `DATA` statement to indicate that the linetype attribute is set to `INDIVIDUAL` : DATA ATFLAG /1,1,2/ to DATA ATFLAG /2,1,2/ In the `DATA CREATION` section, modify the the code which creates the second structure as follows: CALL GPOPST(STRID(2)) CALL GPMLX2(TRANSD,POST) CALL GPINLB(1) CALL GPLT(6) CALL GPPLCI(6) CALL GPPL2(5,2,DOOR) CALL GPCLST In the INPUT SUBROUTINES section, after the statement: IF(CHOICE.EQ.1) GOTO 200 add the following statements: IF(CHOICE.EQ.4) THEN CALL GPOPST(STRID(2)) CALL GPEDMO(2) CALL GPEPLB(1) CALL GPOEP(1) CALL GPQED(1,32,ERRIND,ACTNUM,ACTLEN,CDATA,TERM) IF(ERRIND.NE.0) GOTO 200 IF(CDATA(2).EQ.6) CALL GPLT(1) IF(CDATA(2).EQ.1) CALL GPLT(6) CALL GPCLST CALL GPUPWS(WSID,2) ENDIF

Modified Sample Program 1

Modifying the sample program according to the following statements will enable you to interactively edit the house structure.

In the DECLARE VARIABLES section, add the following statements:
```
INTEGERx4 ACTNUM,ACTLEN,CDATA(2),TERM
```
In this same section, modify the data length and data of the choice input device initialization parameters. First, modify the dimension of the variable Data You should have DATA(4) Change it to DATA(7) Then modify the DATA statements as follows:
```
DATA DATA /28/
      DATA DATA /4,0,0,2,1,1,2/
```
These changes will light the first and fourth Lighted Program Function Key (LPFK).
In this same section, change the DATA statement to indicate that the linetype attribute is set to INDIVIDUAL :
```
DATA ATFLAG /1,1,2/
        to
      DATA ATFLAG /2,1,2/
```

In the DATA CREATION section, modify the the code which creates the second structure as follows:

CALL GPOPST(STRID(2))
      CALL GPMLX2(TRANSD,POST)
      CALL GPINLB(1)
      CALL GPLT(6)
      CALL GPPLCI(6)
      CALL GPPL2(5,2,DOOR)
      CALL GPCLST

In the INPUT SUBROUTINES section, after the statement:

IF(CHOICE.EQ.1) GOTO 200

add the following statements:

IF(CHOICE.EQ.4) THEN
        CALL GPOPST(STRID(2))
        CALL GPEDMO(2)
        CALL GPEPLB(1)
        CALL GPOEP(1)
        CALL GPQED(1,32,ERRIND,ACTNUM,ACTLEN,CDATA,TERM)
        IF(ERRIND.NE.0) GOTO 200
        IF(CDATA(2).EQ.6) CALL GPLT(1)
        IF(CDATA(2).EQ.1) CALL GPLT(6)
        CALL GPCLST
        CALL GPUPWS(WSID,2)
     ENDIF

After modifying your sample program, compile and run it. The fourth LPFK should be lit. Press it. The Line Type of the door should change from dashed to solid. Press it again. It should change back to dashed.

The instructions you have added modify the door structure by inquiring the structure element type. The application first opens the structure, then editing mode is set to replace, and then the pointer is located at the label. The pointer is then moved one element down and placed where the Line Type element is. Now the application inquires the element type, SOLID_LINE or DASHED , and replaces the element according to the result of the inquire. The structure is then closed and the workstation updated.

Operations on Entire Structures

This section discusses operations that affect entire structures. These operations do not require an open structure. In fact, only the empty structure operation can be done in either the structure open or closed state. For your application to delete structures, the system must be in the structure closed state. The figure, "Sample Structure Network Before Empty and Delete Operations," depicts a structure network. The figures, "Results of an Empty Structure (GPEST) subroutine" and "Results of a Delete Structure (GPDLST) subroutine," depict the results of empty and delete operations applied to the structure network in the figure, "Sample Structure Network Before Empty and Delete Operations."

Emptying a Structure

Your application can delete a structure's content by issuing the Empty Structure (GPEST) subroutine. This lets your application empty open or non-opened structures. If the emptied structure is open, the graPHIGS API resets the element pointer to the conceptual element zero.

The figure, "Results of an Empty Structure (GPEST) subroutine," depicts the results of emptying structure 4. Notice that this does not remove the reference to structure 4 from structures 2 and 3. However, it does disconnect structures 5 and 6 from structures 1, 2, 3, and 4.

Deleting Structures

The graPHIGS API enables your application to delete an individual structure, a group of structures, or all structures.

The Delete Structure (GPDLST) subroutine removes all references to the identified structure, since a structure exists by reference. The figure, "Results of a Delete Structure (GPDLST) subroutine," depicts the results of a Delete Structure subroutine call. Notice that the deletion of structure 4 also implies removing all references to structure 4. Notice also that although structures 5 and 6 still exist, they are no longer connected to structures 1, 2, and 3. Conceptually, deleting an individually identified structure involves deleting "upward" in the hierarchy and also deleting the elements that reference the identified structure.

The Delete Structure Network (GPDLNT) subroutine deletes a specified structure and all structures it references. These include:

all structures referenced directly in the element list of the specified structure
all structures referenced indirectly as part of the network emanating from the specified structure.

The figure, "Results of a Delete Structure Network (GPDLNT) subroutine," shows the results of deleting a structure network--again structure number 4 from the figure, "Sample Structure Network Before Empty and Delete Operations." Notice that the deletion of structure 4 removes not only the references to structure 4, but also the network of all structures that comprise structure 4, including structures 5 and 6.

The Delete Structure Network Conditionally (GPDLNC) subroutine deletes a specified root structure and conditionally deletes all of the structures referenced, both directly and indirectly, by the root structure. Only those structures which are not referenced directly or indirectly by other root structures will be deleted. For example, suppose your application creates the following structure network:

structure A is the root structure which executes structure B
structure B executes structure D
structure C is a root structure which also executes structure D

If your application invokes GPDLNC to conditionally delete the structure network originating at structure A, only structures A and B will be deleted. Structure D will not be deleted because structure C, which is not part of structure A's network, also references structure D

The Delete All Structures (GPDAST) subroutine causes the system to delete all structures, their identifiers, and their contents.