gsysc: Get storage from the system heap

This function allocates storage from the system heap.

Last updated

Changed for PUT11 (information only; no code change).
Changed for PUT06 (information only; no code change).

Format

#include <tpf/sysapi.h>
void *gsysc(int frames, char *token);

frames: This argument specifies the number of 4 KB frames to be allocated from the system heap.
token: This argument specifies an 8-byte string that identifies the storage being allocated. You need to specify this string when releasing storage to verify that the correct storage is released.

Normal return

The system virtual memory (SVM) address of the storage requested is returned.

Error return

If the request cannot be satisfied because the maximum size of the heap has been reached or there is not enough contiguous space available, 0 is returned.

If the system does not have enough real frames to satisfy the request, a catastrophic dump is taken and the system is IPLed again.

Programming considerations

Any storage allocated by gsysc() must be returned by the application using rsysc() because the storage is not attached to the ECB and will not be returned when the ECB exits.
The storage key is set to X'9'.
The first 16 bytes of system heap storage are set to zeros. You can put an indicator in these 16 bytes to show that the initialization of system heap storage is completed. The indicator does not have to be a full 16 bytes, but it must be in the first 16 bytes. The indicator can be a bit, a byte, an eye catcher such as the name of the area, and so on. When one process gets the system heap area and a second process tries to access data in that system heap area, the indicator is still zeros if the system heap area is not completely initialized. After the first process initializes the system heap storage, the indicator that you set is in the first 16 bytes, and any process can access the system heap storage.
To update key 9 storage in applications that are running in key 1, use the tpf_stpoc function.
You can use the gsysc or tpf_gsysc function to allocate system heap; however, the tpf_gsysc function offers more functionality.

Examples

The following example allocates and releases 12 KB of system heap storage.

#include <tpf/sysapi.h>
#include <stdio.h>
⋮
{
    /******************************************************************/
    /* Allocate 12 KB of storage for a table used by many different   */
    /* ECBs.                                                          */
    /******************************************************************/
    int  frames, rc;
    char * token = "TABLE40 ";
    struct table {
        char  *name;
        int   code;
    } *tbl_ptr;

    frames = 3;
    tbl ptr = (table *) gsysc(frames, token);
    if (tbl_ptr == 0) {
         serrc_op(SERRC_EXIT, 0x1111, "Error allocating table.", NULL);
    }
⋮
    rc = rsysc((void *)tbl_ptr, frames, token);
    if (rc == RSYSC_ERROR) {
         serrc_op(SERRC_EXIT, 0x2222, "Error releasing storage.", NULL);
    }
}