_SETSPP() and _SETSPP_TS64()--Set Space Pointer for i5/OS PASE


  Syntax 
 #include <as400_protos.h>

 void _SETSPP(ILEpointer  *target,
              const void  *memory);


 void _SETSPP_TS64(ILEpointer  *target,
                   ts64_t      ts64);

  Default Public Authority: *USE

  Library: Standard C Library (libc.a)

  Threadsafe: Yes

Note: These functions can only be used in an i5/OS PASE program. See i5/OS PASE for more information about creating i5/OS PASE programs.

The _SETSPP() function sets a tagged space pointer to the teraspace equivalent of an i5/OS PASE memory address. The _SETSPP_TS64() function sets a tagged space pointer to the memory identified by a 64-bit teraspace address.


Parameters

target
(Output) Pointer to a 16-byte aligned buffer where the tagged space pointer (or null pointer) is returned.

memory
(Input) Pointer containing either an i5/OS PASE memory address, or a null pointer (zero).

ts64
(Input) 64-bit teraspace address, or null (zero).

Authorities

_SETSPP and _SETSPP_TS64 require no authority.


Return Value

_SETSPP and _SETSPP_TS64 return no function result. A tagged space pointer or 16-byte null pointer is returned in the target buffer.


Error Conditions

Any error is reported with an i5/OS exception message that the system converts to an i5/OS PASE signal. See i5/OS PASE Signal Handling for information about handling i5/OS exceptions.


Usage Notes

  1. _SETSPP returns a 16-byte null pointer if the input i5/OS PASE memory address is null (zero) or if a 64-bit memory value points to a location that cannot contain i5/OS PASE memory. i5/OS PASE memory is allocated from teraspace, but teraspace has a limited capacity smaller than 64-bits, so i5/OS PASE can only provide addressability to a subset of a 64-bit address space.

  2. _SETSPP_TS64 returns a 16-byte null pointer if the input ts64 value is zero or outside the range of teraspace.

  3. _SETSPP and _SETSPP_TS64 return target a space pointer regardless of whether there is currently any memory at the target address.

  4. A tagged space pointer to a teraspace location must only be used by the process that owns the teraspace, although the current system implementation does not reliably enforce this restriction. Applications must not assume that a process can reference memory in the teraspace of another process because future system implementations may make this impossible. Tagged space pointers to teraspace memory that were either inherited by the child process of a fork or stored in shared memory by another process should be considered unusable.

  5. Tagged (16-byte) pointers must not be stored in memory mapped from a bytestream file (by either mmap or shmat) although the current system implementation does not reliably enforce this restriction. Tagged pointers can be stored in shared memory objects (created by shmget and mapped by shmat), but a tagged space pointer to teraspace memory cannot be reliably used by a process other than the one that owns the teraspace.

Related Information


API introduced: V4R5 for _SETSPP, V5R3 for _SETSPP_TS64
Top | i5/OS PASE APIs | APIs by category