tpf_fsysc: Find storage in the system heap

This function returns the starting address and, optionally, the size in bytes of a storage allocation in the 31-bit or 64-bit system heap based on the unique, 8-byte token that is associated with the storage allocation.

Last updated

Changed for PUT14 (information only; no code change).
Changed for PUT11 (information only; no code change).
Added for PUT00.

Format

#include   <tpf/sysapi.h>
void       *tpf_fsysc(char *token, long *size);

token: A pointer to a unique 8-byte token that is contained in a 9-byte NULL-terminated string associated with the requested system heap storage allocation. The requested system heap can be 31-bit system heap storage (below the 2 GB bar) or 64-bit system heap storage (above the 2 GB bar). The token must match exactly the token that was specified in the tpf_gsysc function call with the GSYSC_UNIQUE flag, which was set when the storage was allocated.
size: A pointer to an 8-byte integer that specifies the length (in bytes) of the system heap storage allocation that is associated with the unique token. This parameter is optional; if it is not specified, a NULL pointer value must be specified.

Normal return

The starting system virtual memory (SVM) address (where EVM=SVM) of the system heap storage allocation in the 31-bit or 64-bit system heap based on the unique 8-byte token associated with the storage allocation is returned. If the SVM address is specified, the size of the storage allocation is saved in the specified 8-byte integer.

Error return

If unsuccessful, a value of 0 (NULL) is returned as the SVM address and the appropriate errno value is set as follows:

ETPFFSYS_INVTKN

The request cannot be completed because the pointer that was specified by the token parameter is not in the range of addressable storage or was NULL on input.

ETPFFSYS_TKNNFND

The z/TPF system tried to find a system heap storage address using a unique token; however, the 8-byte token specified by the token parameter is not in the unique token table for either the 31-bit or 64-bit system heap storage allocation.
If the tpf_fsysc function finds a 64-bit system heap storage address associated with the specified token and the application is running in 31-bit addressing mode, a system error occurs and the ECB exits.

Programming considerations

A value of ITOKENLEN is defined as 9 to help you define the size for the token string.
This function can be used only for storage allocations that have unique tokens, that is, they were defined using the tpf_gsysc function with the GSYSC_UNIQUE flag specified.
Applications cannot retrieve a 31-bit or 64-bit system heap storage address using the tpf_fsysc function if the storage was already released by the rsysc function.
Applications that allocate storage using the tpf_gsysc function must return the storage using the tpf_rsysc function 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' by the tpf_gsysc function for both 31-bit and 64-bit system heap storage. However, the requesting application can change this value. You can use the tpf_stpoc function to update key 9 storage.
The first 16 bytes of system heap storage are set to zeros when tpf_gsysc function processing is allocating the storage. 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.

Examples

The following C language example allocates, finds, and releases 12 KB of system heap storage using a unique token.

#include <tpf/sysapi.h>
#include <tpf/tpfapi.h>
#include <stdio.h>

int SAMPL()
{
  /****************************************************************/
  /* Allocate 12 KB of storage for a table used by many different */
  /* ECBs.                                                        */
  /****************************************************************/
  int frames = 3 , rc = 0;
  long size = 0;
  char token[ITOKENLEN] = "MYUNQTKN";
  struct table 
  {
    char *name;
    int code;
  } *tbl_ptr;
  tbl_ptr = tpf_gsysc(frames, token, NULL, GSYSC_UNIQUE);
  if (tbl_ptr == 0)
  {
    serrc_op(SERRC_EXIT,0x1111,"Error allocating table.",NULL);
  }
  tbl_ptr=tpf_fsysc(token,NULL);
  if (tbl_ptr == 0)
  {
    serrc_op(SERRC_EXIT,0x3333,"Error finding storage.",NULL); }
  }
}