Safeguard Management Programming Manual (G06.29+, H06.08+, J06.03+)

Safeguard Management Programming Manual—422086-028
5-1
5
SPI Programming Considerations
The SPI Common Extensions Manual discusses general programming considerations
for writing applications that use the Subsystem Programmatic Interface (SPI) to
communicate with subsystems like the Safeguard subsystem. This section discusses
SPI programming considerations specific to the Safeguard subsystem.
Building the Command Buffer
These programming considerations apply when an application builds the command
buffer for a Safeguard command.
The minimum buffer length in bytes for a Safeguard command is a predefined value
with the symbolic name ZSFG-VAL-BUFLEN. The maximum buffer length in bytes for a
Safeguard command is a predefined value with the symbolic name ZSFG-VAL-
MAXBUFLEN.
The Safeguard subsystem supports multiple commands in a single request message.
In addition, most of the Safeguard commands accept multiple object names in one
command, so one command can affect a number of objects. The maximum number of
object names depends on the size of the command buffer. All the objects named in one
command must be the same object type.
The Safeguard subsystem does not support continuation of a command across
multiple messages, but it does support the special case of receiving multiple reply
messages using the context token, as described in the SPI Programming Manual.
The command buffers for all Safeguard commands can contain extensible structured
tokens. An extensible structured token appearing in a command should always be
initialized by the SPI procedure SSNULL to insure that every field of the token is
initialized to its null value. This action is important because an operation is performed if
a field contains a value other than its null value. For example, in the ALTER USER
command, if an extensible structured token contains a value other than its null value,
that value is assigned to the attribute corresponding to that field.
Using SSNULL is important even when every field of an extensible structured token will
have a value assigned to it, so that the application continues to run even if it is
compiled with new definition files that add new fields to the token.
Only those tokens can appear more than once in a Safeguard command:
•
ZSFG-MAP-ACCESS
•
ZSFG-MAP-DEFAULT-ACCESS
•
ZSFG-MAP-REMOVE-ACCESS
•
ZSFG-MAP-REMOVE-DF-ACCESS