Use Create Store to create a new Store resource. The graPHIGS API uses the Store resource to manage the memory needed by the subroutines that return complex data. Use of the Store resource provides two levels of memory management: low level and high level. The graPHIGS API manages the memory at a low level because it uses, re-uses, allocates, and deallocates memory from the system in order to return data to the application. However, the application manages the memory at a high level because it creates and deletes the Stores. An application may create multiple Stores.
The application can pass the newly created Store resource as a parameter to a subroutine returning complex data. Another parameter to a subroutine returning complex data is a pointer to a pointer to a structure which defines the additional memory referenced by fields within the structure. The application accesses the returned data through its pointer to the structure. It does not use the Store resource to access the data.
A Store continues to hold the information from the function until the Delete Store subroutine deletes the Store or until the application uses the Store as a parameter to a subsequent subroutine which returns complex data. Then the graPHIGS API replaces the old information with the newly requested data. A Store resource only contains the results of the last subroutine.
If the graPHIGS API can create the Store resource, then the graPHIGS API sets the error indicator to zero and returns the Store handle. If the graPHIGS API cannot create the Store resource, then the value of the Store handle is unpredictable and the graPHIGS API sets the error indicator to one of the following errors:
|pcreate_store (err_ind, store)|