tpf_rsysc: Release storage from the system heap

This function releases storage from the 31-bit or 64-bit system heap.

Last updated

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

Format

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

address: This argument specifies a pointer to the block of contiguous system heap storage in the 31-bit or 64-bit system heap storage area that is to be released. If the target system heap storage was obtained using the tpf_gsysc function with the GSYSC_UNIQUE flag, the address argument is optional and can be a NULL pointer.
frames: This argument specifies the number of system heap storage units (4-KB or 1-MB units, depending on how the GSYSC_UNIQUE flag on the corresponding tpf_gsysc function is set) to be released. This must match the number of frames on the corresponding tpf_gsysc function for this system heap storage. If the target system heap storage was obtained using the tpf_gsysc function with the GSYSC_UNIQUE flag, the frames argument is optional and can be a 0 (zero) value.
token: This argument is required; it specifies a pointer to the 8-byte token that is contained in a 9-byte NULL-terminated string that was specified when the system heap storage was acquired (using the tpf_gsysc function).

Normal return

RSYSC_OK indicates that the storage is released successfully.

Error return

If the request cannot be completed, RSYSC_ERROR is returned, no system heap storage is released, and the appropriate errno value is set with one of the following:

ETPFRSYS_INVTKN: The request cannot be completed because the address specified by the token parameter was not in an addressable range of storage, or was NULL on input.
ETPFRSYS_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.
ETPFRSYS_TKNMMTCH: The 8-byte token specified on the token parameter matches the token that is associated with the system heap storage address specified on the address parameter.
ETPFRSYS_INVADDR: The system heap storage address specified by the address parameter is not a valid system heap storage adddress or is not in the range of addressable storage in either the 31-bit or 64-bit system heap storage areas.
ETPFRSYS_ADDRNUSD: The sytem heap storage specified on the address parameter is not in use.
ETPFRSYS_INVFRMS: The number of frames does not match the system heap storage allocation for the address or token parameter, or both.

Programming considerations

Values of ITOKENLEN and IOWNERLEN are defined as 9 and 33, respectively, to help you define the size for the token and owner strings.
Storage that is acquired using the tpf_gsysc function must be returned by the application using the tpf_rsysc function because the storage is not attached to the ECB and will not be returned when the ECB exits.
Storage that is acquired using the tpf_gsysc function is tagged with the 8-byte token specified by the token parameter. You must specify the same token when you release the storage using the tpf_rsysc function.
If the tpf_gsysc GSYSC_UNIQUE flag is not specified, the following must be specified: the starting adddress of the system heap storage, the number of frames (4 KB or 1 MB) that were allocated, and the pointer to the 8-byte string that was specified in the tpf_gsysc function when releasing the storage. If the GSYSC_UNIQUE flag is specified in the tpf_gsysc function, the application must supply only the unique token when it later releases the storage using the tpf_rsysc function.
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 tpf_rsysc function.
You can use the rsysc or tpf_rsysc function to release system heap; however, the tpf_rsysc function offers more functionality.

Examples

The following C language example allocates and releases 3 MB of system heap storage.

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

int SAMPL()
{
  /*******************************************************************/
  /* Allocate 3 MB of storage above the 2 GB bar for a table         */
  /* used by an application and then release the system heap storage.*/
  /*******************************************************************/
  unsigned int frames = 3, rc = 0, flags;
  char token[ITOKENLEN] = "UMYTOKEN";
  struct table 
  {
    char  *name;
    int   code;
  } *tbl_ptr;
  Flags = GSYSC_1MB + GSYSC_64BIT;
  tbl_ptr = tpf_gsysc(frames, token, flags);
  if (tbl_ptr == 0)
  {
     serrc_op(SERRC_EXIT, 0x1111, "Error allocating table.", NULL);
  }

  rc = tpf_rsysc(tbl_ptr, frames, token);
  if (rc != RSYSC_OK)
  {
     serrc_op(SERRC_EXIT, 0x2222, "Error releasing storage.", NULL);
  }
  return rc;
}

The following C language example allocates and releases 12 KB of system heap storage using a unique token and then releases the storage using only the 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.                                                          */
  /******************************************************************/
  unsigned int frames = 3, rc = 0;
  char [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);
  }

  rc = tpf_rsysc(NULL, 0, token);
  if (rc == RSYSC_ERROR)
  {
     serrc_op(SERRC_EXIT, 0x2222, "Error releasing storage.", NULL);
  }
  return rc;
}