GDSX Management Programming Manual

GDSX Management Programming Manual—529930-001

3-1

SPI Programming Considerations

This section discusses the SPI programming considerations that are specific to the

GDS subsystem.

Building the Command Buffer

The following programming considerations are relevant when an application builds the

command buffer for a GDSX command:

•

The recommended buffer length in bytes for a GDSX command is a predefined

value with the symbolic name ZGDS-VAL-BUFLEN.

•

The GDS subsystem does not support multiple commands in a single request

message. However, the GDS subsystem supports level-2 wildcards in object

names. That is, an asterisk (*) character can be used to represent a whole

separated name, such as $GDS.*.*.

•

The GDS subsystem does not support the continuation of a command across

multiple messages, but it does support special cases that involve receiving multiple

reply messages using the context token as described in the SPI Programming

Manual.

•

The command buffers for all GDSX commands can contain extensible structured

tokens. An extensible structured token that is to appear in a command should

always be initialized by the SPI procedure SSNULL to ensure that every field of the

token is initialized to its null value. This action is important because an operation

will be performed if a field contains a value other than its null value. For example,

in the ALTER LINE command, if a field of the extensible structured token that

describes the line attributes contains a value other than its null value, then that

value is assigned to the attribute corresponding to that field.

•

Using SSNULL is important even when every field of an extensible structured

token has a value assigned to it, so that the application continues to work if it is

compiled with new definition files that add new fields to the token.

•

The only tokens that can appear more than once in a GDSX command are ZSPI-

TKN-COMMENT and ZCOM-TKN-TRACE-OPT. ZSPI-TKN-COMMENT is the

comment token, described in the SPI Programming Manual. ZCOM-TKN-TRACE-

OPT is a token used in the TRACE command, and it is described in Section 5,

Commands and Responses.

•

If any of the other tokens in a command appear more than once, an error is given

either by the GDS subsystem or by SCP.