tpf_stpoc: Set or clear storage protection override

This function allows programs to turn on and turn off storage protection override so programs can access areas like globals and system heap without having to change their storage access key. Storage protection override allows entry control blocks (ECBs) to access storage with protection key 9 while running in key 1.

Last updated

Added for PUT00.

Format

#include <tpf/tpfapi.h>
void     tpf_stpoc(enum t_stpoc action, char* stpoc_value);

action

The action that the z/TPF system will take. Use one of these defined terms:

TPF_STPOC_ON: Turns on storage protection override.
TPF_STPOC_OFF: Turns off storage protection override.
TPF_STPOC_RESTORE: Changes storage protection override to the value contained in the stpoc_value parameter.

stpoc_value

Points to a 9-byte work area.

Normal return

Void.

Error return

Not applicable.

Programming considerations

You must turn off storage protection override before the program gives up control or exits.
Turning off storage protection override also will change back the protection key of the ECB to that of working storage.
When TPF_STPOC_ON or TPF_STPOC_OFF is coded, the stpoc_value will, on return, contain the status of storage protection override before it was changed. A NULL pointer indicates that the current value will not be saved.
When TPF_STPOC_RESTORE is coded, the stpoc_value must contain a value that is the result of a previous call to the tpf_stpoc function with either the TPF_STPOC_ON or the TPF_STPOC_OFF option.
Calling the function with TPF_STPOC_OFF is the same as calling the keyrc function.

Examples

The following example shows that by using the tpf_stpoc function, an application can use system heap (key 9 protected storage) without having to change its storage key.

#include <tpf/sysapi.h>
#include <tpf/tpfapi.h>
⋮
{
   void * myStorage;
   char   token[8];
   int    frames;
⋮
   myStorage=gsysc(frames,token);
   tpf_stpoc(TPF_STPOC_ON, NULL);
   memcpy(myStorage,"MY STORAGE",sizeof("MY STORAGE"));
   tpf_stpoc(TPF_STPOC_OFF, NULL);
⋮
}

Related information

keyrc: Restore protection key.

See z/TPF C functions overview for more information about z/TPF C/C++ language support.