The graPHIGS Programming Interface: Understanding Concepts

Chapter 13. Archiving Structures

Structure archiving allows your application to store structure information in a file for retrieval at a later time. Upon retrieval, this information is read directly into the structure store in the graPHIGS API nucleus, bypassing the shell. This can result in increased performance and less storage capacity used.

Structure store information is archived in a unique binary format (3) called an archive file. An archive file is a graPHIGS API nucleus resource. It must be accessible by the nucleus that is specified on the Open Archive File (GPOPAR) subroutine. If the nucleus cannot find the desired archive file (defined by the file descriptor parameter in the GPOPAR subroutine), then a new archive file is created by the nucleus. Archive file accessibility is only a potential problem when the nucleus has a GAM or SOCKETS connection type. No workstation specific information is included in archive files.

NOTE: On VM, archive files must have a fixed record format with a logical length of 256. On MVS, archive file datasets must have a fixed-blocked record format, a logical record length of 256, and a blocksize of 4096. Any archive files not formatted in this way will cause the message 1205 FILE IS NOT A VALID ARCHIVE FILE to be sent to the application.

Archive Functions

The archive functions allow your application to store archive files, retrieve, and delete them, as well as make inquiries regarding resource identifiers and potential conflicts. These functions can operate on all current structures or archive files, those associated with a list of root structures, or those listed by identifier.

Opening Archive Files

Your application can open an archive file by using the Open Archive File (GPOPAR) subroutine. GPOPAR sets the current archive state to Archive Open (AROP), making all archiving functions available. The Attach Resource (GPATR) subroutine, used with Resource Type 5=ARCHIVE FILE , allows one application to access an archive file opened by another application running in a different graPHIGS API shell.

Archiving Files

Archiving transfers an entire structure from the currently selected structure store to a specified archive file. To archive one or more structures, use the Archive Structure (GPARST) subroutine to specify individual structures in a list of structure identifiers. The Archive Structure Networks (GPARSN) subroutine allows you to specify structures for archiving by root identifier, and the Archive All Structures (GPARAS) subroutine archives all structures in the current structure store.

Closing an Archive File

Use the Close Archive File (GPCLAR) subroutine to close an open archive file. If no other archive files are open, then the current state becomes archive closed (ARCL) and archiving functions are no longer available.

Retrieving Archive Files

To move one or more structures from a specified archive file to the current structure store, use the Retrieve Structures (GPRVST) subroutine. Use the Retrieve Structure Networks (GPRVSN) subroutine for all archive files associated with a specified root structure. To move all structures into the current structure store, use the Retrieve All Structures (GPRVAS) subroutine.

Deleting Archive Files

Use the Delete Structure from Archive (GPDSAR) subroutine to remove one or more structures from an open archive file. Use the Delete Structure Networks from Archive (GPDSNA) when you want to remove all archived structures associated with a root structure. To remove all archived structures from an open archive file, use the Delete All Structures from Archive (GPDASA) subroutine.

Inquiring for Archive Files

To determine whether any attached resources contain archive files, use the Inquire List of Attached Resources (GPQATR) subroutine, specifying a resource type of 5=ARCHIVE_FILE

If an archive file exists in a nucleus, use the Inquire Nucleus Resource Identifier (GPQNCR) subroutine to find the resource identifier assigned by the nucleus.

To determine the archive state of the graPHIGS API, use the Inquire Archive State Value (GPQASV) subroutine. GPQASV returns a value indicating whether or not any archive files are open based on the current archive state (AROP or ARCL).

The Inquire Archive Files (GPQARF) subroutine returns a list of open archive file identifiers and associated descriptor information.

Use the Retrieve Structure Identifiers (GPRSTI) subroutine to obtain a list of structure identifiers in a specified archive file. Use the Retrieve Identifiers of Structures in Network (GPRISN) subroutine to obtain a list of structure identifiers in a specified structure network in an open archive file.

Ancestors and Descendants of Structures in Archive File

Your application can use two inquiries to determine the structure relationships that precede and follow a particular structure in an archive file. These relationships are expressed as structure identifiers paired with element numbers. For example, the path:

(101,10),(102,5),(103,0)

is interpreted as follows:

In structure 101, element 10 is an EXECUTE STRUCTURE of structure 102
In structure 102, element 5 is an EXECUTE STRUCTURE of structure 103
Structure 103 is the last structure of the path.

The returned data defines the path from structure 101 to structure 103. You can control the order of the path returned, so the top of the path is returned first or the bottom of the path is returned first. In addition, you can control the depth of the path returned (that is, the number of pairs of data returned).

Use the Retrieve Ancestors to Structures (GPRAS) subroutine to retrieve the ancestral paths that lead to the specified structure in an archive file. These paths are those created by other structures that reference the specified structure by use of Execute Structure elements. Use the Retrieve Descendants to Structure (GPRDS) subroutine to return paths that lead from the specified structure. These paths are those created by the Execute Structure elements in the specified structure in an archive file.

Conflicts

A conflict exists when both the specified archive file and the currently selected structure store contain the same structure identifier. The way in which your application resolves this conflict is determined by the conflict resolution flags in the archive and retrieve subroutines. These flags allow your application to control conflicts by providing three different courses of action:

1=ABANDON: If a conflict is encountered, then the graPHIGS API exits the function without retrieving or archiving any structure data.
2=MAINTAIN: If a conflict is encountered, then the graPHIGS API does not archive or retrieve the conflicting structure but continues archiving or retrieving all specified structures not in conflict.
3=UPDATE: Archive or retrieve the specified structures regardless of whether a conflict is encountered.

The default for all archiving subroutines is 3=UPDATE subroutines is 1=ABANDON To change the conflict resolution flag from the default value, use the Set Conflict Resolution (GPCNRS) subroutine. To determine the current value of the flag, use the Inquire Conflict Resolution (GPQCNR) subroutine.

Conflict Inquiries

Your application can inquire information regarding potential conflicts by structure or root identifier. The Inquire All Conflicting Structures in Archive (GPQACA) subroutine lists conflicting identifiers in the current structure. Inquire Conflicting Structures in Network in Archive (GPQCNA) lists conflicting identifiers in the current structure network.

Table 6 shows how the setting of the conflict resolution flag affects archive and retrieve functions under various conditions.

Table 6. Archive and Retrieve Functions and Conflict Resolution

Conditions	Function	Conflict Resolution Flag Values
Conditions	Function	Abandon	Maintain	Update
Identifier in Source; Identifier not in Destination	Archive	Structure Changed	Structure Changed	Structure Changed
Identifier in Source; Identifier not in Destination	Retrieve	Structure Changed	Structure Changed	Structure Changed
Identifier in Source; Identifier in Destination	Archive	Error 128	No Change	Structure Changed
Identifier in Source; Identifier in Destination	Retrieve	Error 128	No Change	Structure Changed
Identifier not in Source; Identifier not in Destination	Archive	Warning 120 No Change	Warning 120 No Change	Warning 120 No Change
Identifier not in Source; Identifier not in Destination	Retrieve	Warning 120 Empty Structure Created	Warning 120 Empty Structure Created	Warning 120 Empty Structure Created
Identifier not in Source; Identifier in Destination	Archive	Warning 120 No Change	Warning 120 No Change	Warning 120 No Change
Identifier not in Source; Identifier in Destination	Retrieve	Warning 120 Error 128	Warning 120 No Change	Warning 120 Empty Structure Created

Error 128: Structure conflict occurs when resolution flag is abandon.
Warning 120: One or more structures do not exist.

The Archive File Format

The graPHIGS API uses it own binary file format for archive files (ISO PHIGS does not have a standard binary format for archive files). On VM, archive files must have a fixed record format with a logical length of 256. On MVS, archive file datasets must have a fixed-blocked record format, a logical record length of 256, and a blocksize of 4096.

For VM and AIX, if an archive file does not exist, then one is created by the Open Archive File subroutine (GPOPAR) For MVS, however, the dataset for the archive file must be allocated before GPOPAR is called.

Estimating Storage Requirements for Archive Files

For MVS, the following can be used as a guide to calculate how much space will be required for an archive file:

The file header is one record in size.
For every ten (or fewer) structures in an archive file, one record is allocated for internal control. For example, if there are eleven structures in an archive file, there will be two control records (one to handle the first ten structures and one for the last one, with space for nine more structures).
An empty structure takes no space in the file other than as an entry in a control record.
A non-empty structure starts on a record boundary and its space requirements can be calculated in the following manner:
1. Add up the size of each element in the structure.
2. Add 12 extra bytes for each grouping of elements that adds up to 65524 or less. Elements are grouped in their order of appearance in the structure and will be grouped together until the next element would cause the element group to be greater than 65524 bytes in size.
3. Add 8 bytes for every execute structure element or conditional execute structure element. Add another 8 bytes if at least one execute structure-type element exists.
4. Add 12 bytes for structure information.
5. Divide the total number of bytes for the structure by 256. The result is the number of records that the structure data uses. If the remainder of the division is not 0, add 1 to the number of records

The figure, "Calculating Space for an Archive File," shows an example calculation of space for an archive file. It assumes that the archive file will hold the following:

Structure 1 with 16 elements with the following sizes (in bytes):
8, 8, 8, 10000, 16, 16, 16, 8, 8, 25000, 8, 8, 8, 40000, 16, 16

Note: The 16-byte elements are execute structure elements.
Structure 2 with 15 elements with the following sizes:
12, 8, 8, 8, 15000, 12, 8, 8, 8, 2000, 12, 8, 8, 8, 45000
Empty Structures 10, 11, 12, ..., 19, 20

      Calculating Space for an Archive File

      Data Item                                  |  Number of Records
      -------------------------------------------|-------------------
      File header                                |          1
      -------------------------------------------|-------------------
      13 structures exist:  2 control records    |
          needed (1 for first 10, 1 for next 3)  |          2
      -------------------------------------------|-------------------
      Structure 1:                   (Bytes)     |
                                                 |
         Structure information:          12      |
         Element group 1:                        |
            Group information:  12               |
            Element data                         |
             (13 elements):  35112               |
            ----------------------               |
            Total:                    35124      |
         Element group 2:                        |
            Group information   12               |
            Element data                         |
             (3 elements):   40032               |
            ----------------------               |
            Total:                    40044      |
         Execute Structure Data:                 |
            Ex.Str. information  8               |
            Ex.Str. data                         |
             (3 elements):      24               |
            ----------------------               |
            Total:                       32      |
         ----------------------------------      |
         Total for structure:         75212      |
                                                 |
         75212 / 256 = 293, Remainder = 204      |        294
      -------------------------------------------|-------------------
      Structure 2:                   (Bytes)     |
                                                 |
         Structure information:          12      |
         Element group 1:                        |
            Group information:  12               |
            Element data                         |
             (13 elements):  62108               |
            ----------------------               |
            Total:                    62120      |
         ----------------------------------      |
         Total for structure:         62132      |
                                                 |
         62132 / 256 = 242, Remainder = 180      |        243
      -------------------------------------------|-------------------
      Total records needed in file:              |        540
                                                 |
 
      File requires 540 / 16 = 34 blocks of storage