SPI Programming Manual (G06.24+, H06.03+, J06.03+)

General SPI Programming Guidelines
SPI Programming Manual—427506-006
5-31
Checking the Command Message for Validity
READUPDATE and REPLY directly; a C program uses the same procedures through
the
tal interface declaration. A COBOL program normally uses READ and WRITE. A
TACL routine generally uses a loop with #INPUTV and #REPLYV.
After the server has received an SPI message, it can use the SPI procedures to get
command, object-type, and parameter information from the message buffer and put
context, status, and other response information into a response buffer.
Checking the Command Message for Validity
When your subsystem receives a command message, it should first check that the
message is a valid SPI command buffer:
1. Check that the byte count read from $RECEIVE is at least 6 bytes.
2. Check that the value of the first word of the buffer is -28.
3. Check that the buffer-length field, Z-BUFLEN, is greater than or equal to the used
length, ZSPI-TKN-USEDLEN.
4. Check that the header type, ZSPI-TKN-HDRTYPE, is equal to ZSPI-VAL-
CMDHDR, indicating that the buffer is a command buffer.
If any of the preceding tests fails, your subsystem should not attempt to send an SPI
response buffer but should return file-system error 2 to the requester.
The read count used by the requester should not affect your server’s response,
because detecting a short read (fewer bytes read than the number requested) is the
responsibility of the requester.
Checking Whether Your Subsystem Can Process the Command
If the command message passes all the validity checks, next ensure that your
subsystem can process the command:
1. Check that the subsystem ID in the command, ZSPI-TKN-SSID, matches the
subsystem ID for your subsystem, to ensure that the command is intended for your
subsystem.
2. Check that the maximum field version, ZSPI-TKN-MAX-FIELD-VERSION, is less
than or equal to your subsystem’s version.
3. Reset the buffer by calling SSPUT with ZSPI-TKN-RESET-BUFFER, as requesters
do when they receive a response buffer; set the buffer length to the length
declared by your subsystem. If you receive an SPI error -5 (buffer full) when
resetting the buffer, the command is too long for your subsystem to process.
If one of these tests fails, your subsystem should return an SPI error response
containing at least a return token (ZSPI-TKN-RETCODE), and, if possible, other
information about the error. The value of the return token should be an error number
defined by your subsystem to identify the particular error.