SPI Programming Manual Abstract This manual describes the operating system procedures that programmers call to process the Subsystem Programmatic Interface (SPI) messages. It presents conventions that regulate message content and interpretation, provides programming guidelines and examples, and describes the common ZSPI data definitions. Product Version SPI G05 and H01 Supported Release Version Updates (RVUs) This publication supports G05.00 and all subsequent G-series RVUs and H06.
Document History Part Number Product Version Published 427506-002 SPI D40 and G05 September 2003 427506-003 SPI D40 and G05 September 2003 427506-004 SPI D40 and G05 December 2003 427506-005 SPI G05 August 2004 427506-006 SPI G05 and H01 February 2006
SPI Programming Manual Glossary Index Examples What’s New in This Manual xiii Manual Information xiii New and Changed Information Figures xiii About This Manual xv Audience xv Related Manuals xvi Notation Conventions xvi 1.
Contents 2. SPI Concepts and Protocol (continued) 2.
2. SPI Concepts and Protocol (continued) Contents 2.
3. The SPI Procedures (continued) Contents 3. The SPI Procedures (continued) Special Operations With SSGET and SSGETTKN 3-14 Considerations 3-22 SSMOVE and SSMOVETKN Procedures 3-24 General Syntax 3-24 Considerations 3-25 Example: Moving Buffer Tokens Using SSMOVETKN 3-26 SSIDTOTEXT Procedure 3-34 General Syntax 3-34 Considerations 3-35 Examples 3-36 TEXTTOSSID Procedure 3-36 General Syntax 3-36 Considerations 3-37 Examples 3-38 4.
5. General SPI Programming Guidelines (continued) Contents 5.
5. General SPI Programming Guidelines (continued) Contents 5. General SPI Programming Guidelines (continued) Control of Types of Response Records 5-47 Continuing Despite Errors 5-47 Reporting Errors From the SPI Procedures 5-47 Pass-Through Error Lists 5-51 Summary of Server Role 5-54 6.
7. SPI Programming in COBOL (continued) Contents 7. SPI Programming in COBOL (continued) SSPUT 7-5 SSPUTTKN 7-5 SSGET 7-6 SSGETTKN 7-6 SSMOVE 7-6 SSMOVETKN 7-6 Examples 7-6 8.
9. SPI Programming in TAL (continued) Contents 9. SPI Programming in TAL (continued) Defining Token Maps 9-2 Interprocess Communication 9-3 SPI Procedure Syntax in TAL 9-3 Passing Token Parameters by Value or by Reference SPI Procedure Syntax in TAL 9-3 (continued) SSINIT 9-4 SSNULL 9-4 SSPUT and SSPUTTKN 9-4 SSGET and SSGETTKN 9-4 SSMOVE and SSMOVETKN 9-5 Examples 9-5 A.
B. Summary of DDL for SPI (continued) Contents B. Summary of DDL for SPI (continued) TACL Clause B-5 SSID Clause B-5 HEADING Clause B-6 DISPLAY Clause B-6 Constants B-6 Type ENUM DEFs B-6 Token Types, Token Codes, and Token Maps DDL Data Translation B-7 B-6 C.
Contents E. SPI Programming Examples (continued) E.
Examples (continued) Contents Examples (continued) Example E-15. Example E-16. Example E-17. Example E-18. Example E-19. Example E-20. Example E-21. Example E-22.
Figures (continued) Contents Figures (continued) Figure C-6. Figure C-7. Structures Within a Token Map C-8 Structure of a List in the Buffer C-11 Tables Table 1-1. Table 2-1. Table 2-2. Table 3-1. Table 3-2. Table 4-1. Table 4-2. Table 8-1. Table 8-2. Table 8-3. Table A-1. Table A-2. Table D-1. Table D-2.
What’s New in This Manual Manual Information SPI Programming Manual Abstract This manual describes the operating system procedures that programmers call to process the Subsystem Programmatic Interface (SPI) messages. It presents conventions that regulate message content and interpretation, provides programming guidelines and examples, and describes the common ZSPI data definitions. Product Version SPI G05 and H01 Supported Release Version Updates (RVUs) This publication supports G05.
Changes in the G06.24 Manual What’s New in This Manual • • • 265, Java Logging Subsystem (L4J) 266, Matrix SMLC CBB 4.2 Subsystem (CPS) 267, Deadlock Detector Subsystem (DLD) Changes in the G06.24 Manual Added details of subsystems, 260 and 261 in Table D-1, NonStop Kernel Subsystem Numbers, on page D-1.
About This Manual This manual describes the Subsystem Programmatic Interface (SPI): Section Description Section 1, Introduction to SPI Provides an overview of SPI. Section 2, SPI Concepts and Protocol Presents topics central to understanding SPI. Section 3, The SPI Procedures Describes the syntax of the SPI procedures and the operations they perform. Section 4, ZSPI Data Definitions Provides descriptions of the ZSPI data definitions and the Data Definition Language (DDL) code used to define them.
Related Manuals About This Manual by many NonStop Kernel subsystems and by customer-developed applications that manage these subsystems. Related Manuals For D-series and G-series RVUs, SPI is part of the Distributed Systems Management (DSM) architecture. For more information, see the Distributed Systems Management (DSM) Manual. If the subsystems you are managing expect requests to be routed through an SCP process, read the Subsystem Control Point (SCP) Management Programming Manual.
General Syntax Notation About This Manual each side of the list, or horizontally, enclosed in a pair of brackets and separated by vertical lines. For example: LIGHTS [ ON ] [ OFF ] [ SMOOTH [ num ] ] K [ X | D ] address-1 { } Braces. A group of items enclosed in braces is a list from which you are required to choose one item. The items in the list may be arranged either vertically, with aligned braces on each side of the list, or horizontally, enclosed in a pair of braces and separated by vertical lines.
Notation for Messages About This Manual Line Spacing. If the syntax of a command is too long to fit on a single line, each continuation line is indented three spaces and is separated from the preceding line by a blank line. This spacing distinguishes items in a continuation line from items in a vertical list of selections. For example: ALTER [ / OUT file-spec / ] CONTROLLER [ , attribute-spec ]... !i and !o.
Notation for Management Programming Interfaces About This Manual [ ] Brackets. Brackets enclose items that are sometimes, but not always, displayed. For example: Event number = number [ Subject = first-subject-value ] A group of items enclosed in brackets is a list of all possible items that can be displayed, of which one or none might actually be displayed.
Change Bar Notation About This Manual !r. The !r notation following a token or field name indicates that the token or field is required. For example: ZCOM-TKN-OBJNAME !o. token-type ZSPI-TYP-STRING. !r The !o notation following a token or field name indicates that the token or field is optional. For example: ZSPI-TKN-MANAGER token-type ZSPI-TYP-FNAME32. !o Change Bar Notation Change bars are used to indicate substantive differences between this manual and its preceding version.
1 Introduction to SPI This section provides an overview of the Subsystem Programmatic Interface: Topic Page The Components of SPI 1-1 The Environment for D-Series RVUs 1-10 The Components of SPI The Subsystem Programmatic Interface (SPI), a central component of the Distributed System Management (DSM) architecture, is the path that management applications and subsystems use to exchange command-response messages and event messages.
SPI and EMS Introduction to SPI • • • • • • A standard message format A standard message protocol A standard unit of information: the token Procedures for composing and decoding messages Data definitions for commonly used data structures Rules and guidelines governing message content and protocol SPI and EMS The Event Management Service (EMS) is based on SPI, and EMS messages are one of two types of SPI messages (the other being control and inquiry messages).
Subsystem Manager Introduction to SPI Figure 1-1. SPI Communication With a Single-Process Subsystem A subsystem might consist of a single process, in which case this process both provides the subsystem services and serves as the SPI subsystem manager. Management Application Subsystem Legend SPI Command SPI Response VST001.
Subsystem Manager Introduction to SPI Figure 1-2. SPI Communication With a Multiprocess Subsystem A subsystem might consist of several processes. One of these, the manager process, supports the SPI interface to management applications. Subsystem Process Subsystem Manager Process Management Application Subsystem Process Subsystem Process Legend SPI Command SPI Response VST002.vsd Multiple management applications can communicate with a single subsystem.
SPI Message Protocol Introduction to SPI Figure 1-3. Subsystem Manager Communicating With Multiple Management Applications A subsystem manager can support concurrent SPI communications with multiple management applications. Management Application Subsystem Process Subsystem Manager Management Application Subsystem Process Subsystem Process Management Application Legend SPI Command SPI Response A subsystem does not need to communicate directly with management applications.
SPI Message Format Introduction to SPI • How requesters and servers should respond to error conditions Communication between a management application and a subsystem follows the standard HP requester-server model, with the management application in the role of requester and the subsystem manager process in the role of server. Figure 1-4. SPI Communication Through an Intermediate Process A subsystem can have its commands and responses routed through an intermediate process.
Tokens Introduction to SPI SPI messages are built in buffers initialized by the SSINIT procedure. The messages contain tokens (and are sometimes called tokenized messages). The interface itself is described as token-based. Programs use SPI procedures to format message buffers, assign values to tokens, and put tokens into and retrieve tokens from message buffers.
SPI Data Definitions Introduction to SPI • • • • From C using the tal interface declaration From COBOL using the ENTER TAL construct From TACL using special built-in functions From TAL SPI Data Definitions Tokens, values, command numbers, message headers, and error numbers are some of the SPI-defined data items that are used to build SPI messages. These items are defined using the DDL and are provided to programmers in definition files with names beginning with ZSPI.
A Basic Interface and Extensions Introduction to SPI A Basic Interface and Extensions This manual describes the basic SPI interface. Many NonStop Kernel subsystems are based on an extended version of SPI. These extensions, based on ZCOM data definitions, and a common implementation of the extensions, based on ZCMK definitions, are described in the SPI Common Extensions Manual. Table 1-1.
The Environment for D-Series RVUs Introduction to SPI Table 1-1. Comparison: SPI Basic and Extended Features (page 2 of 2) Basic SPI Extended SPI Message routing Does not regulate message routing. Provides a message routing process (SCP) that also provides security and other features. Compatibility Provides basic mechanisms for determining versions of requesters, servers, and the definitions they use.
Implications for Management Applications Introduction to SPI on a node running a C-series RVU in a network with a node running a D-series RVU. The SCP and subsystem processes that communicate with an unconverted management application should be run at low PINs. This approach provides the best way, other than converting the application, to avoid the problems described here.
Converting Management Applications Introduction to SPI Interprocess Communications Restrictions These restrictions apply to communication among processes on a node running a D-series RVU or among processes in a mixed network of C-series and D-series RVUs and are relevant to all instances of SPI requester-server communications: • • No process on a node running a C-series RVU can be opened by a high-PIN process on a node running a D-series RVU.
2 SPI Concepts and Protocol This section defines the basic concepts on which the Subsystem Programmatic Interface (SPI) is based: Topic Page SPI Message Protocol 2-1 Tokens 2-3 Data Definitions 2-10 SPI Message Buffer 2-13 Lists 2-19 Commands 2-27 Responses 2-28 Subsystem IDs (SSIDs) 2-44 Errors and Warnings 2-47 SPI Message Protocol Communication between a management application and a subsystem follows the standard HP requester-server model, with the management application in the role
Requester Sends a Command Message SPI Concepts and Protocol An entire command must always be sent in one command message. SPI does not support commands continued across multiple messages, nor does it support multiple commands per message. However, a command can be applied to multiple objects.
Server Returns the Response Message SPI Concepts and Protocol processed. The server and requester then follow the response continuation protocol in Continued Responses on page 2-34. By default, the subsystem returns a single response record per response message. However, if requested, many NonStop Kernel subsystems return multiple response records per response message.
Token Data Type SPI Concepts and Protocol Tokens are self-describing data items; a typical token in an SPI message carries with it an identifying number, the data type of its value, the length of its value, and the value. Token number, data type, and length are known collectively as the token code, and a token is often viewed as consisting of two parts: a token code and a token value. The token data type and token length are known collectively as the token type. Token codes contain a subsystem ID.
Token Type SPI Concepts and Protocol has a value consisting of four integers. If the value is longer than 254 bytes, or if it is of variable length, the token length is set to 255, and the actual length of the value is stored in the first 2 bytes of the value itself. Both options are illustrated in Figure 2-2 on page 2-6. Token Type The token data type and token length together define the token type. Token types have symbolic names of the form subsys-TYP-desc.
Token Names SPI Concepts and Protocol Figure 2-2. Token Length Fixed-Length Token Data Type Length ((n) n) Token Number Data Item 0 1 2 n bytes Variable-Length Token Data Type 255 Length ((n-2) n-2) 0 Token Number Data Item 2 n bytes VST006.vsd Token Names Every token code has a symbolic token name, a meaningful name of the form subsysTKN-name, where subsys identifies the subsystem responsible for the definition and name describes the content or function of the token.
SPI Concepts and Protocol Types of Tokens Types of Tokens Tokens are divided into four categories: Simple tokens Have a simple data item or fixed structure as a value Extensible structured tokens Have an extensible structure as a value Zero-length tokens Have no value and consist of a token code only Header tokens Have values that reside in the SPI message header Simple Tokens Tokens whose values are elementary data items or fixed structures are called simple tokens.
SPI Concepts and Protocol Extensible Structured Tokens map itself, into the buffer. The message recipient retrieves the structure from the message by specifying its own version of the map in an SSGET call.
SPI Concepts and Protocol Zero-Length Tokens map and placed in the fields of the structure by the SSNULL and SSGET procedures. A null value is required for every field of an extensible structured token. The null value specified in the DDL is a single-byte value, defined either as a character or as an integer in the range 0 to 255. The SPI procedures form the null value for the corresponding field by concatenating this single-byte value with itself as many times as necessary to fill the field.
SPI Concepts and Protocol • • Data Definitions The values of header tokens can be retrieved at any time using SSGET, without changing and regardless of the current position of the buffer pointers. Certain special SSGET operations, such as ZSPI-TKN-ADDR and ZSPI-TKNOFFSET, cannot be performed on header tokens. The header tokens in Table 2-1 are described in Token Codes on page 4-31. For their use in procedure calls, see Section 3, The SPI Procedures. Table 2-1.
SPI Concepts and Protocol Naming Conventions Naming Conventions SPI data definitions have names of this form. subsys-type-description subsys^type^description subsys_type_description (in DDL and COBOL) (in TAL and TACL) (in C) subsys is a four-character abbreviation that identifies the subsystem that defined the item. Some subsystems declare many of their own definitions in addition to the common definitions that are used by most subsystems (such as those defined by SPI and EMS).
SPI Concepts and Protocol Examples of Definition Names TNM Token numbers TYP Token types VAL Token values description is an expression describing the function or meaning of the item. For example, OBJNAME has something to do with the name of an object, and PATH-SWITCHCAUSE has something to do with the reason for a path change. This part of the definition name can contain additional separators (-,^, or _).
SPI Concepts and Protocol Definition Files Supplied by HP subsys ZCOM (an extended SPI definition) type TKN (a token code) description OBJNAME (value conveyed by token: an object name) Definition Files Supplied by HP The data definitions provided by HP for the NonStop server are distributed in standard definition files, normally located in $release-vol.ZSPIDEF.* (although they can be placed elsewhere).
SPI Concepts and Protocol Message Header Figure 2-3. The SPI Buffer Message Header Message Body H T1 T2 T2 T8 Tokens Used Used Length Length Buffer Length Legend H An SPI buffer or message H The SPI message header Tn A token with ID number n VST007.vsd The SPI procedure SSINIT initializes an SPI buffer and places values in header tokens. SSPUT puts tokens into a buffer, and SSGET retrieves token values from a buffer. Section 3, The SPI Procedures, describes the SPI procedures.
SPI Concepts and Protocol • • • • • • • • • • • • Message Body The maximum version of any field in any extensible structure in the buffer The subsystem ID of the server The server version The maximum number of response records the server is allowed to return The command number The object-type to which the command is applied A flag indicating the status of checksum protection The number of the last nonzero error returned by an SPI procedure The token code involved in the last SPI call that returned a nonz
SPI Concepts and Protocol Used Length recommend a buffer size that can accommodate the largest command or response supported by the subsystem. These recommended buffer sizes have names of the form subsys-VAL-BUFLEN. Used Length Few command and response messages occupy the entire allocated buffer. You can determine how many bytes actually contain message information by using the SSGET procedure to retrieve the value of the header token ZSPI-TKN-USEDLEN.
SPI Concepts and Protocol Buffer Pointers token value. The next-token pointer is an internal buffer management position and cannot be explicitly retrieved by an application. The Last-Put-Token Pointer The last-put-token pointer contains the position of the last token added to the buffer by the SSPUT procedure, and is stored in the header token ZSPI-TKN-LASTPOSITION. Its value can be retrieved by calling SSGET with ZSPI-TKN-LASTPOSITION.
SPI Concepts and Protocol Buffer Checksum Figure 2-4. Pointer Manipulation Examples This sequence of procedure calls demonstrates how the SPI procedures manipulate the current-token, next-token and last-put-token pointers. 1 SSINIT (buffer,...) H C N 2 SSPUT (...,T1...) H T1 C N 3 SSPUT (...,T2...) H P T1 C N 4 SSPUT (...,T3...) H T2 P T1 T2 T3 C N 5 SSPUT (...,T3...) H P T1 T2 T3 C N SSPUT (...,ZSPI-TKN-RESET-BUFFER,...) 6 H P T1 T2 T3 C N 7 SSGET (...,T1,...) H SSGET (.
SPI Concepts and Protocol Lists When so directed, each SPI procedure updates the checksum after any modification of the buffer. Each time an SPI procedure is called, it first recomputes the checksum and compares it against the checksum stored in the buffer. If they do not match, the procedure reports a checksum error, indicating that the buffer has been corrupted since the last SPI procedure call. By default, SPI does not calculate buffer checksums.
SPI Concepts and Protocol Segment Lists Segment Lists SPI servers use segment lists to build segmented responses. Tokens in a segmented response are divided into repeating and nonrepeating groups, and each repeating group is enclosed in a segment list. For more information, see Segmented Responses on page 2-38. A segment list consists of all tokens between ZSPI-TKN-SEGLIST and the corresponding ZSPI-TKN-ENDLIST. Generic Lists Generic lists are provided for use in customer-developed subsystems.
SPI Concepts and Protocol Pointer Manipulation and Lists 10. Having exited the list and returned to the top level of the buffer, SSGET retrieves token T6. The procedure call series in Figure 2-5 are performed by the TAL program in Example E-3 on page E-10 and the C program in Example E-4 on page E-13.
SPI Concepts and Protocol Pointer Manipulation and Lists Figure 2-5. Pointer Manipulation and Lists 1 SSPUT (...,ZSPI-TKN-RESET-BUFFER,...) H T1 T2 [ T3 T4 T5 ] T6 T1 T2 [ T3 T4 T5 ] T6 C N T1 T2 [ T3 T4 T5 ] T6 [ T3 T4 T5 ] T6 [ T3 T4 T5 ] T6 T4 T5 ] T6 C N 2 This sequence of procedure calls demonstrates how the SPI procedures manipulate the current-token, next-token and current-list pointers. 3 SSGET (...,T1,...) SSGET (...,T2,...) H H C 4 SSGET (...,T3,...
SPI Concepts and Protocol Pointers, Lists, and ZSPI-TKN-NEXTTOKEN Pointers, Lists, and ZSPI-TKN-NEXTTOKEN Figure 2-6 on page 2-24 shows the behavior of SSGET special operation ZSPI-TKNNEXTTOKEN when working in and around lists. It demonstrates a sequence of procedure calls and the resulting pointer changes. Although the figure shows a data list, the demonstrated behavior applies to all list types: 1.
SPI Concepts and Protocol Pointers, Lists, and ZSPI-TKN-NEXTTOKEN Figure 2-6. Pointers, Lists, and ZSPI-TKN-NEXTTOKEN 1 SSPUT (...,ZSPI-TKN-RESET-BUFFER,...) H T1 [ T2 T3 T3 ] T4 C N 2 SSGET (...,ZSPI-TKN-NEXTTOKEN,...) H T1 [ T2 T3 T3 ] T4 C N 3 SSGET (...,ZSPI-TKN-NEXTTOKEN,...) H T1 [ T2 T3 T3 ] T4 C N L 4 SSGET (...,ZSPI-TKN-NEXTTOKEN,...
SPI Concepts and Protocol Pointers, Lists, and ZSPI-TKN-NEXTCODE Pointers, Lists, and ZSPI-TKN-NEXTCODE Figure 2-7 on page 2-26 shows the behavior of SSGET special operation ZSPI-TKNNEXTCODE in the same buffer scanned with ZSPI-TKN-NEXTTOKEN in Figure 2-6 on page 2-24. It demonstrates a sequence of procedure calls and the resulting pointer movements. Although the figure shows a data list, the demonstrated behavior applies to all list types: 1.
SPI Concepts and Protocol Pointers, Lists, and ZSPI-TKN-NEXTCODE Figure 2-7. Pointers, Lists, and ZSPI-TKN-NEXTCODE This sequence of procedure calls demonstrates the effect of the special operation ZSPI-TKNNEXTCODE on the buffer pointers when working with lists. 1 SSPUT (...,ZSPI-TKN-RESET-BUFFER,...) H T1 [ T2 T3 T3 ] T4 C N 2 SSGET (...,ZSPI-TKN-NEXTCODE,...) H T1 [ T2 T3 T3 ] T4 C N 3 SSGET (...,ZSPI-TKN-NEXTCODE,...) H T1 [ T2 T3 T3 ] T4 C N 4 SSGET (...
SPI Concepts and Protocol Commands Commands A command directs an SPI server to perform an action on one or more objects. The action can affect the objects in some way or might just retrieve information about the objects. The command in an SPI request is identified by a command number, which the requester specifies in the SSINIT procedure call that initializes the message. SSINIT stores the command number in the header token ZSPI-TKN-COMMAND. Command numbers have names of the form subsys-CMD-command.
SPI Concepts and Protocol Responses Extended GETVERSION Commands A subsystem can provide additional features in its implementation of the GETVERSION command: • • The subsystem can allow the requester to specify a particular object type other than NULL in order to retrieve the version of some subsystem component. The subsystem can allow additional tokens in the command which prompt the subsystem for additional information describing specific features supported by the subsystem.
SPI Concepts and Protocol Simple Responses A requester controls the type of response—within the capabilities of the server—by specifying some combination of these parameters: • • • • • The number of objects to which the command is applied, which can be affected by the use of wild cards in the object name or the use of subsystem-defined command modifiers. A command applied to a single object can result only in a simple or a segmented response.
SPI Concepts and Protocol Multirecord Responses Multirecord Responses When a command is applied to more than one object, the server returns multiple response records (unless the requester suppresses response records; see Suppressing Response Records on page 2-43). In this case, message traffic can be reduced by having the server return more than one response record in each response message.
SPI Concepts and Protocol Multirecord Responses Figure 2-8. ZSPI-TKN-MAXRESP = 0 (Default) The server returns one response record in each response message. Response records are not enclosed in data lists. Example: MAXRESP = 0 and one object qualifies for processing: H Ra T1a T2a The server returns one message containing one response record (not in a datalist).
SPI Concepts and Protocol Multirecord Responses Figure 2-9. ZSPI-TKN-MAXRESP > 0 The server returns as many as n response records in each response message. Each response record is contained in a separate data list. Example: MAXRESP = -1 and one object qualifies for processing: H [ Ra T1a T2a ] The server returns one message containing one response record in a datalist.
SPI Concepts and Protocol Multirecord Responses Figure 2-10. ZSPI-TKN-MAXRESP = –1 The server returns as many response records in each response message as fit in the buffer. Each response record is contained in a separate data list. Example: MAXRESP = -1 and one object qualifies for processing: H [ Ra T1a T2a ] The server returns one message containing one response record in a datalist.
SPI Concepts and Protocol Continued Responses Continued Responses Many subsystems let a single command be applied to multiple objects, in which case the server returns a separate response record for each object.
SPI Concepts and Protocol Continued Responses indicate, for instance, that there are no more objects to process because the remaining objects were deleted since the server returned the last response.) The absence of a context token is the only valid indicator of the last response message. Your application should always check for the context token (it can do so with a simple call to SSGET).
SPI Concepts and Protocol Continued Responses Figure 2-11. Response Continuation 1 H T1 The requester sends a command directed to multiple objects and specifying a MAXRESP value of -1. T2 2 The server processes two objects ( a and b) and adds response records to the buffer. Before processing a third object, the server finds that there is no room in the buffer for a response record. So it adds a context token and returns the response.
SPI Concepts and Protocol Continued Responses Response Continuation Protocol These steps summarize the protocol for continuing a response. Each step corresponds to an item in Figure 2-11 on page 2-36: 1. The requester composes a command that is to be applied to multiple objects. In this example, the requester specifies a value of –1 for ZSPI-TKN-MAXRESP, telling the server to return as many response records as it can fit in each response message.
SPI Concepts and Protocol Segmented Responses from this response message tells the requester that all qualifying objects have been processed and the response for this command is complete. Segmented Responses A command might generate a response record that contains so many occurrences of a particular token or group of tokens that the record does not fit in even the largest allowable message buffer.
SPI Concepts and Protocol Segmented Responses Figure 2-12. Segmented Responses Structure of a Simple Segmented Response: First Response Record Segment H [ R Message 1 ] T1 T2 T3 { T4 T5 } { T4 T5 } { T4 T5 } M C Base Tokens Segment List H [ R Repeating Tokens { T4 T5 } { T4 T5 } { T4 T5 Message 2 } ] Second Segment Example: A segmented response for two objects a and b.
SPI Concepts and Protocol Segmented Responses Determining Subsystem Support for Segmented Responses A subsystem that returns ZSPI-TKN-SEGMENTATION with a value of TRUE in its GETVERSION response can generate segmented responses. A subsystem that supports segmentation for any command must support segmentation for all commands. Requesting a Segmented Response To request a segmented response, a command must include ZSPI-TKN-ALLOW with the value ZSPI-VAL-ALLOW-SEGMENTS. Otherwise, segmentation is disallowed.
SPI Concepts and Protocol Empty Responses Empty Responses An empty response consists of a single response message that contains no response records. An empty response must contain a return code (ZSPI-TKN-RETCODE) with a subsystem-defined error number that declares that the response message contains no response records. In special cases, an “empty response” might also contain error information describing the command. (See point 3.) An empty response message does not always indicate an empty response.
SPI Concepts and Protocol Empty Responses Figure 2-13. Empty Responses Three situations in which a server returns an empty response: 1 The requester sets ZSPI-TKN-RESPONSE-TYPE to ZSPI-VAL-ERR-AND-WARN, and no errors or warnings are encountered during command processing: H R The server returns an empty response.
SPI Concepts and Protocol Object Identification in Responses Object Identification in Responses A response record must contain a subsystem-defined token identifying the object that the response record describes. This object-name token appears even if the response contains an error list that includes the object name. The exceptions to this rule are: • • • • If the response record corresponds to a command that does not have an object name, the response record does not include an object name.
SPI Concepts and Protocol Subsystem IDs (SSIDs) The two possible values for ZSPI-TKN-RESPONSE-TYPE are: • • ZSPI-VAL-ERR-WARN-AND-NORM directs the server to return a response record for every object in the set of objects specified in the command. This action is the default if the response-type token is not included in the command.
SPI Concepts and Protocol Subsystem IDs (SSIDs) The subsystem version field (Z-VERSION) is a 16-bit unsigned integer value representing the software release version of the subsystem. For NonStop Kernel subsystems, this value is in the form returned by the TOSVERSION procedure: that is, the left byte contains the letter part of the version as an ASCII uppercase alphabetic character, and the right byte contains the numeric part of the version as an unsigned integer value.
SPI Concepts and Protocol SSID Scope Figure 2-14.
SPI Concepts and Protocol • Errors and Warnings If the token is not enclosed in a list and its token code does not contain an SSID, it belongs to the SSID specified in the header token ZSPI-TKN-SSID. Errors and Warnings An SPI server reports an error when it cannot complete a command. It issues a warning when it completes a command but the results are suspect or it wants to provide the requester with additional advisory information.
SPI Concepts and Protocol Error Lists Figure 2-15. Error Information in a Response Record If ZSPI-TKN-RETCODE = error number indicating empty response message (Required) If ZSPI-TKN-RETCODE = 0 (no errors, but possibly warnings): (Required) ... (Optional.
SPI Concepts and Protocol Pass-Through Errors Each error list contains an error token (ZSPI-TKN-ERROR) that identifies the error described by other tokens in the list. ZSPI-TKN-ERROR is a fixed structure consisting of the subsystem ID of the subsystem that reported the error and the error number of an error defined by that subsystem. (The version portion of the subsystem ID in an error token can be either zero or the version of the subsystem reporting the error.
SPI Concepts and Protocol Continuing Despite Errors corresponding TACL built-in function descriptions in Section 8, SPI Programming in TACL. Continuing Despite Errors Some subsystems support another standard SPI token to let the requester specify under what conditions the server should continue processing a set of objects. This is the allow-type token (ZSPI-TKN-ALLOW-TYPE).
SPI Concepts and Protocol Recovering From an Error on an Object in a Set subsystems that do not support this feature do not proceed to the next object in the set if any error or warning occurred on the previous object. Recovering From an Error on an Object in a Set The use of the context token for continuation allows for resuming processing after an error, starting with the object following the one on which the error occurred. That makes it easy for your application to continue the command immediately.
SPI Concepts and Protocol Sample Error Responses Error List Example 2 Single error list (subsystem SYSB): Z-SSID Z-ERROR Z-TOKENCODE Z-INDEX Z-OFFSET
SPI Concepts and Protocol Sample Error Responses To indicate that this error list describes an error reported by the file system, FUP gives the error list the subsystem ID of the file system.
SPI Concepts and Protocol Sample Error Responses SPI Programming Manual—427506-006 2- 54
3 The SPI Procedures This section describes these SPI procedures: Topic Page Overview of the SPI Procedures 3-1 SSINIT Procedure 3-4 SSNULL Procedure 3-6 SSPUT and SSPUTTKN Procedures 3-7 SSGET and SSGETTKN Procedures 3-12 SSMOVE and SSMOVETKN Procedures 3-24 SSIDTOTEXT Procedure 3-34 TEXTTOSSID Procedure 3-36 This section describes the procedures and their parameters in a general context. The exact syntax of an SPI procedure call depends on the programming language you use.
The SPI Procedures Special Operations The SSIDTOTEXT and TEXTTOSSID procedures perform these functions: SSIDTOTEXT Converts an internal form subsystem ID to its external representation TEXTTOSSID Finds an external representation of a subsystem ID and converts it to the internal representation Special Operations The SSPUT(TKN) and SSGET(TKN) procedures can perform special operations in addition to their primary functions.
The SPI Procedures Using the SPI Procedures Using the SPI Procedures The SPI procedures are in the standard operating-system library and can be called through: • • • • The tal interface directive in C (See Section 6, SPI Programming in C.) ENTER TAL from COBOL (See Section 7, SPI Programming in COBOL.) Corresponding built-in functions from TACL (See Section 8, SPI Programming in TACL.) Directly from TAL (See Section 9, SPI Programming in TAL.
The SPI Procedures SSINIT Procedure SSINIT Procedure An application must use the SSINIT procedure to initialize a command buffer. The SSINIT procedure initializes an SPI buffer with an appropriate header and places values in header fields. The previous contents of the buffer are overwritten. Do not use SSINIT to initialize an event-message buffer. Instead, use EMSINIT, as described in the EMS Manual.
The SPI Procedures header-type General Syntax input INT:value specifies the type of SPI buffer to initialize. This parameter determines how SSINIT interprets the parameters that follow it. You should always give the value ZSPIVAL-CMDHDR (0), indicating the standard command header (for a command or response). Other values are used internally by software for the NonStop server. command input INT:value is the command number. If not supplied, it defaults to zero.
The SPI Procedures SSNULL Procedure SSNULL Procedure The SSNULL procedure initializes an extensible structure with null values. Always use this procedure before setting values within an extensible structured token. For more information about null values, see Section 5, General SPI Programming Guidelines. General Syntax SSNULL ( token-map , struct [ , constants ] ) ! i ! o ! i token-map INT .EXT:ref:* is a token map to be used in initializing the fields of the structure. struct STRING .
The SPI Procedures SSPUT and SSPUTTKN Procedures SSPUT and SSPUTTKN Procedures The SSPUT and SSPUTTKN procedures insert tokens in an SPI buffer previously initialized by SSINIT. The two procedures are identical except for the type of the token-id parameter (SSPUT passes token-id by reference and SSPUTTKN passes it by value) and the consequent fact that SSPUTTKN cannot be used with a token map.
The SPI Procedures Special Operations With SSPUT and SSPUTTKN is a subsystem ID that qualifies the token code. If ssid is not supplied or is equal to zero ( 6*[0] ), the default applies. If SSPUT is currently adding tokens to a list, ssid defaults to the subsystem ID of that list; otherwise, ssid defaults to the subsystem ID in the SPI message header (ZSPI-TKN-SSID).
The SPI Procedures Special Operations With SSPUT and SSPUTTKN resets the maximum buffer length in the SPI message header, and subsequent SPI calls for that buffer fails with ZSPI-ERR-INVBUF. ZSPI-TKN-CHECKSUM: Set Checksum Flag With this token code, a nonzero token-value enables checksum protection of the buffer; a zero token-value disables it. ZSPI-TKN-CLEARERR: Clear Last SPI Error Use this token code to clear the last-error information to zero. If supplied, the tokenvalue parameter is ignored.
The SPI Procedures Special Operations With SSPUT and SSPUTTKN if zero or not supplied, deletes the next occurrence of the token code at or following the current-token pointer in the buffer. if less than zero, returns an error. ssid can be included to qualify token-code. The ZSPI-TKN-DELETE operation does not update the header token ZSPI-TKN-MAXFIELD-VERSION. As a result, following this operation, that token can indicate a version higher than the version of any field remaining in the buffer.
The SPI Procedures Considerations operation sets the current-token pointer to the beginning of the buffer following the header. ZSPI-TKN-RESET-BUFFER: Reset the Buffer Use this token code before extracting tokens from an SPI buffer received (in either a command or a response) from another process.
The SPI Procedures • • • • SSGET and SSGETTKN Procedures The order in which tokens are added to the buffer is not significant except in the case of: (1) SSPUT and SSPUTTKN calls with token codes for tokens that start and end lists, and (2) a few subsystem-specific exceptions mentioned in the subsystem manuals (for example, the ZEMS-TKN-SUBJECT-MARK token in an event message).
The SPI Procedures General Syntax is the SPI buffer from which information is to be extracted. token-id input INT .EXT:ref:* (SSGET) INT(32):value (SSGETTKN) is a token code or (for SSGET only) a token map. This parameter normally identifies the token to be retrieved. If the token-id is one of the SPI standard token codes indicating a special operation, the interpretation of the token-value, count, and index parameters can vary from the descriptions here.
The SPI Procedures Special Operations With SSGET and SSGETTKN described by the token-id. If not supplied, it defaults to one. If less than zero, it causes an error. • On return, it specifies the actual number of token values returned. If a count greater than one is specified, SSGET or SSGETTKN continues searching until it either satisfies the requested count or reaches the end of the buffer or list.
The SPI Procedures Special Operations With SSGET and SSGETTKN Table 3-2.
The SPI Procedures Special Operations With SSGET and SSGETTKN ZSPI-TKN-BUFLEN: Retrieve Current Buffer Length Call SSGET or SSGETTKN with this token code to retrieve the current buffer length from the corresponding header token. If you specify an index parameter, it must have a value of zero or one. ZSPI-TKN-CHECKSUM: Retrieve Value of Checksum Flag Call SSGET or SSGETTKN with this token code to retrieve the checksum flag from the corresponding header token.
The SPI Procedures Special Operations With SSGET and SSGETTKN Here SSGET or SSGETTKN returns, in ssid, INT .EXT:ref:6, the default subsystem ID value at the current-token pointer. SSPUT, SSPUTTKN, SSGET, and SSGETTKN use this value whenever the ssid parameter is omitted or null. If the default subsystem ID comes from a list token, then the version field of ssid is set to ZSPI-VAL-NULL-VERSION.
The SPI Procedures Special Operations With SSGET and SSGETTKN ZSPI-TKN-LEN: Get the Length of a Token Value Use this token code to get the byte length of a specific token value: SSGET SSGETTKN ( buffer , ZSPI-TKN-LEN , [ token-id ] , [ index ] , byte-length , [ ssid ] ) ! ! ! ! i i o i This operation returns in byte-length, INT .EXT:ref:1, the size of the buffer needed to contain the specified occurrence of the token value.
The SPI Procedures Special Operations With SSGET and SSGETTKN ZSPI-TKN-NEXTCODE: Get the Next Different Token Code in the Buffer Use this token code to get the next token code in the buffer that is different from the current token code: SSGET SSGETTKN ( buffer , ZSPI-TKN-NEXTCODE , [ next-token-code ] , , [ occurs ] , [ ssid ] ! o ) ! o ! o next-token-code contains the next different token code in the buffer. occurs contains the number of contiguous occurrences of next-token-code.
The SPI Procedures Special Operations With SSGET and SSGETTKN ZSPI-TKN-NEXTTOKEN: Get the Next Token Code in the Buffer Use this token code to get the token code of the next token in the buffer: SSGET SSGETTKN ( buffer , ZSPI-TKN-NEXTTOKEN , [ next-token-code ] , , , [ ssid ] ! o ) ! o This operation differs from ZSPI-TKN-NEXTCODE in that it always returns the token code of the next token, whether or not it is the same as that of the current token, and whether or not the token is within a list.
The SPI Procedures Special Operations With SSGET and SSGETTKN ZSPI-TKN-OFFSET: Retrieve the Byte Offset of a Token Value Use this token code to get the byte offset of a specific token value: SSGET ( bufferSSGETTKN , ZSPI-TKN-OFFSET , [ token-id ] , [ index ] , byte-offset , [ ssid ] ) ! ! ! ! i i o i This operation returns, in byte-offset, INT .EXT:ref:1, the byte offset from the start of the buffer to the value associated with the specified token code and index.
The SPI Procedures Considerations Considerations • • • • • • • Tokens extracted by SSGET and SSGETTKN are not deleted or removed from the buffer. For checkpointing purposes, note that calls to SSGET and SSGETTKN can modify the SPI message header. For instance, the header tokens ZSPI-TKN-LASTERR and ZSPI-TKN-LASTERRCODE change if an SPI error occurs on the call. Positioning information in the header also changes frequently, and future versions of SPI might introduce other kinds of change.
The SPI Procedures Considerations This example illustrates the second exception: CALL SSGETTKN (buffer, ZSPI-TKN-LEN, , , len) Before the call, the positioning is: current | v next | v After the call, the positioning is unchanged: current | v next | v This example illustrates the third exception: CALL SSGETTKN (buffer, ZSPI-TKN-LEN, TKN-A, , len) Before the call, the positioning is: current | v next | v
The SPI Procedures SSMOVE and SSMOVETKN Procedures SSMOVE and SSMOVETKN Procedures The SSMOVE and SSMOVETKN procedures copy tokens from one SPI buffer to another. One call can copy a single token, a sequence of tokens with the same token code, or a list. SSMOVE performs a sequence of SSGET and SSPUT operations. Likewise, SSMOVETKN performs a sequence of SSGETTKN and SSPUTTKN (or SSGET and SSPUT) operations.
The SPI Procedures dest-buffer Considerations input, output INT .EXT:ref:* is the SPI buffer to which the specified token or tokens are to be copied. dest-index input INT:value if greater than zero, identifies the first occurrence of token-id to be replaced in the destination buffer. A value of 1 specifies that replacement should start with the first occurrence of the token code, a value of 2 specifies the second occurrence, and so on.
The SPI Procedures Example: Moving Buffer Tokens Using SSMOVETKN of change. Programs should never assume that any SSMOVE or SSMOVETKN operation leaves the source buffer unchanged. • • • • After a successful SSMOVE or SSMOVETKN operation, the current-token position in the source buffer is changed to the position of the last token copied.
The SPI Procedures Example: Moving Buffer Tokens Using SSMOVETKN Example 3-1. Moving Buffer Tokens Using SSMOVETKN (page 1 of 7) /* * Try moving some buffer tokens around using SSMOVETKN. */ #pragma symbols #pragma inspect #pragma nomap #pragma nolmap #define max_bufsize 256 /* in bytes */ #include "secc.
The SPI Procedures Example: Moving Buffer Tokens Using SSMOVETKN Example 3-1.
The SPI Procedures Example: Moving Buffer Tokens Using SSMOVETKN Example 3-1.
The SPI Procedures Example: Moving Buffer Tokens Using SSMOVETKN Example 3-1.
The SPI Procedures Example: Moving Buffer Tokens Using SSMOVETKN Example 3-1.
The SPI Procedures Example: Moving Buffer Tokens Using SSMOVETKN Example 3-1. Moving Buffer Tokens Using SSMOVETKN (page 6 of 7) /* * Get the tokens in the SPI buffer "b1" */ get_count = 1; /* * Note that the following code moves all the nonheader tokens from * B1 to B2.
The SPI Procedures Example: Moving Buffer Tokens Using SSMOVETKN Example 3-1.
The SPI Procedures SSIDTOTEXT Procedure SSIDTOTEXT Procedure The SSIDTOTEXT procedure converts an internal form subsystem ID (SSID) to its external representation. General Syntax len := SSIDTOTEXT ( ssid , chars [, status ] ); len !i !o !o returned value INT returns the number of characters placed into chars. Zero is returned if one of the errors (0, 29), (4,0), or (8,0) occurs. Some other errors may prevent the subsystem name from being obtained.
The SPI Procedures Considerations status output INT(32) .EXT:ref:1 is a status code that indicates any problems encountered. These number pairs describe the two halves of the INT(32) value: Error numbers Meaning (0,0) No error (0,x) Something was wrong with the calling sequence. The x half of INT(32) can have these values and meanings: x= 29 a required parameter is missing. x=632 not enough stack space is available. (1,x) An error occurred allocating the private segment.
The SPI Procedures Examples version is either a string of digits that represents a TOSVERSION-format (Ann) or a value from 0 to 65535. The 0.0.0 form is used to represent the null subsystem ID. Its internal representation is binary zero. The number of zeros in each field can vary. For example, 000.0.000 is equivalent to 0.0.0 Examples These are examples of the external form of the subsystem ID: TANDEM.SAFEGUARD.D40 TANDEM.94.0 0.0.
The SPI Procedures Considerations status output INT(32) .EXT:ref:1 is a status code that indicates any problems encountered. These number pairs describe the two halves of the INT(32) value: Error numbers Meaning (0,0) No error (0,x) Something was wrong with the calling sequence. The x half of INT(32) can have these values and meanings: x= 29 A required parameter is missing. x=632 Not enough stack space is available. (1,x) An error occurred allocating the private segment.
The SPI Procedures Examples version is either a string of digits that represents a TOSVERSION-format (Ann) or a value from 0 to 65535. The 0.0.0 form is used to represent the null subsystem ID. Its internal representation is binary zero. The number of zeros in each field can vary. For example, 000.0.000 is equivalent to 0.0.0 Examples These are examples of the external form of the subsystem ID: TANDEM.SAFEGUARD.D40 TANDEM.94.0 0.0.
4 ZSPI Data Definitions The data types, tokens, values, and other declarations on which SPI is based are referred to as the SPI standard definitions or the ZSPI definitions.
ZSPI Data Definitions Fundamental Data Structures ZSPI-DDL-BYTE def ZSPI-DDL-BYTE type binary 8 unsigned spi-null 0. ZSPI-DDL-BYTE defines a single byte. ZSPI-DDL-BYTE-PAIR def ZSPI-DDL-BYTE-PAIR. 02 Z-BYTE type ZSPI-DDL-BYTE end occurs 2 times. ZSPI-DDL-BYTE-PAIR defines a pair of bytes. ZSPI-DDL-CHAR def ZSPI-DDL-CHAR pic x spi-null " ". ZSPI-DDL-CHAR defines a single ASCII character. ZSPI-DDL-CHAR-PAIR def ZSPI-DDL-CHAR-PAIR. 02 Z-C 02 Z-S redefines Z-C.
ZSPI Data Definitions Fundamental Data Structures ZSPI-DDL-CHAR4 def ZSPI-DDL-CHAR4. 02 Z-C pic x(4) 02 Z-S redefines Z-C. 03 Z-I type binary 16 02 Z-B redefines Z-C pic x end spi-null " ". occurs 2 times. occurs 4 times. ZSPI-DDL-CHAR4 defines a string of four ASCII characters, also addressable as two integers or four individual characters. ZSPI-DDL-CHAR5 def ZSPI-DDL-CHAR5. 02 Z-C pic x(5) 02 Z-S redefines Z-C. 03 Z-I type binary 16 03 filler pic x. 02 Z-B redefines Z-C pic x end spi-null " ".
ZSPI Data Definitions Fundamental Data Structures ZSPI-DDL-CHAR8 def ZSPI-DDL-CHAR8. 02 Z-C pic x(8) 02 Z-S redefines Z-C. 03 Z-I type binary 16 02 Z-B redefines Z-C pic x end spi-null " ". occurs 4 times. occurs 8 times. ZSPI-DDL-CHAR8 defines a string of eight ASCII characters, also addressable as four integers or eight individual characters. ZSPI-DDL-CHAR16 def ZSPI-DDL-CHAR16. 02 Z-C pic x(16) 02 Z-S redefines Z-C. 03 Z-I type binary 16 02 Z-B redefines Z-C pic x end spi-null " ". occurs 8 times.
ZSPI Data Definitions Fundamental Data Structures ZSPI-DDL-CHAR50 def ZSPI-DDL-CHAR50. 02 Z-C pic x(50) 02 Z-S redefines Z-C. 03 Z-I type binary 16 02 Z-B redefines Z-C pic x end spi-null " ". occurs 25 times. occurs 50 times. ZSPI-DDL-CHAR50 defines a string of 50 ASCII characters, also addressable as 25 integers or 50 individual characters. ZSPI-DDL-CHAR64 def ZSPI-DDL-CHAR64. 02 Z-C pic x(64) 02 Z-S redefines Z-C. 03 Z-I type binary 16 02 Z-B redefines Z-C pic x end spi-null " ". occurs 32 times.
ZSPI Data Definitions Fundamental Data Structures ZSPI-DDL-CRTPID def ZSPI-DDL-CRTPID tacl crtpid. 02 Z-PROCNAME type ZSPI-DDL-CHAR6. 02 Z-CRT redefines Z-PROCNAME occurs 3 times. 02 Z-PID. 03 Z-CPU type ZSPI-DDL-BYTE 03 Z-PIN type ZSPI-DDL-BYTE 02 Z-CPUPIN redefines Z-PID type ZSPI-DDL-UINT. end type ZSPI-DDL-INT spi-null " ". spi-null " ". ZSPI-DDL-CRTPID defines an 8-byte internal-format process ID for C-series RVUs. ZSPI-DDL-DEVICE def ZSPI-DDL-DEVICE type ZSPI-DDL-CHAR8 tacl device.
ZSPI Data Definitions Fundamental Data Structures ZSPI-DDL-ERROR def ZSPI-DDL-ERROR. 02 Z-SSID 02 Z-ERROR end type ZSPI-DDL-SSID. type ZSPI-DDL-ENUM spi null 0. ZSPI-DDL-ERROR defines an SSID-qualified SPI error value. ZSPI-DDL-EXIOADDR def ZSPI-DDL-EXIOADDR. 02 Z-PATYPE 02 Z-CHNL 02 Z-CTLR 02 Z-UNIT 02 Z-CPU 02 Z-FILLER end type type type type type type ZSPI-DDL-ENUM ZSPI-DDL-UINT ZSPI-DDL-UINT ZSPI-DDL-UINT ZSPI-DDL-UINT ZSPI-DDL-INT2 spi-null spi-null spi-null spi-null spi-null spi-null 255.
ZSPI Data Definitions Fundamental Data Structures ZSPI-DDL-FNAME32 def ZSPI-DDL-FNAME32 02 Z-SYSNAME 02 Z-LOCALNAME end tacl fname32. type ZSPI-DDL-CHAR8. type ZSPI-DDL-FNAME. ZSPI-DDL-FNAME32 defines a 32-byte internal file name. ZSPI-DDL-HEADER def ZSPI-DDL-HEADER. 02 Z-MSGCODE 02 Z-BUFLEN 02 Z-OCCURS 02 Z-FILLER type ZSPI-DDL-INT. type ZSPI-DDL-UINT. type ZSPI-DDL-UINT. type ZSPI-DDL-BYTE occurs 0 to 94 times depending on Z-OCCURS. end ZSPI-DDL-HEADER defines an SPI message header.
ZSPI Data Definitions Fundamental Data Structures ZSPI-DDL-INT2-PAIR def ZSPI-DDL-INT2-PAIR. 02 Z-INT2 type ZSPI-DDL-INT2 end occurs 2 times. ZSPI-DDL-INT2-PAIR defines a pair of 32-bit integers. ZSPI-DDL-INT4 def ZSPI-DDL-INT4 type binary 64 spi-null 0. ZSPI-DDL-INT4 defines a 64-bit fixed-point number. ZSPI-DDL-PARM-ERR def ZSPI-DDL-PARM-ERR. 02 Z-TOKENCODE 02 Z-INDEX 02 Z-OFFSET end type ZSPI-DDL-TOKENCODE. type ZSPI-DDL-UINT. type ZSPI-DDL-UINT.
ZSPI Data Definitions Fundamental Data Structures ZSPI-DDL-PHANDLE def ZSPI-DDL-PHANDLE. 02 Z-BYTE type ZSPI-DDL-BYTE occurs 20 times 255. end spi-null ZSPI-DDL-PHANDLE defines a process handle for D-series RVUs. ZSPI-DDL-PROCNAME def ZSPI-DDL-PROCNAME 02 Z-CRTPID 02 Z-QUAL1 02 Z-QUAL2 end tacl type type type fname. ZSPI-DDL-CRTPID. ZSPI-DDL-CHAR8. ZSPI-DDL-CHAR8. ZSPI-DDL-PROCNAME defines an internal-format process file name.
ZSPI Data Definitions Fundamental Data Structures ZSPI-DDL-TOKENCODE def ZSPI-DDL-TOKENCODE. 02 Z-TKN. 03 Z-DATATYPE 03 Z-BYTELEN 03 Z-NUMBER 02 Z-TKNTYPE 02 Z-TKNCODE type ZSPI-DDL-BYTE. type ZSPI-DDL-BYTE. type ZSPI-DDL-INT. redefines Z-TKN type ZSPI-DDL-INT occurs 2 times. redefines Z-TKN type ZSPI-DDL-INT2. end ZSPI-DDL-TOKENCODE defines a token code for an SSGET or SSPUT special operation for which the token value (in the token-value parameter) is itself a token code.
ZSPI Data Definitions Token Data Types ZSPI-DDL-VERSION def ZSPI-DDL-VERSION 0. type binary 16 unsigned spi-null ZSPI-DDL-VERSION is used with a labeled dump version formatting procedure. It is equivalent to ZSPI-DDL-UINT. Token Data Types A token data type is part of every token code and identifies the fundamental data type of the token’s value. For the data definition of a particular type, see the corresponding token type (ZSPI-TYP-…) in Token Types on page 4-18. Table 4-1.
ZSPI Data Definitions Token Data Types Table 4-1. SPI-Defined Token Data Types (ZSPI-TDT-…) (page 2 of 2) Token Data Type Type of Data Item ZSPI-TDT-TOKENCODE 32-bit token code ZSPI-TDT-TRANSID 64-bit TMF internal-format transaction ID ZSPI-TDT-UINT 16-bit unsigned integer ZSPI-TDT-UNDEF Unknown or undefined data type ZSPI-TDT-USERNAME 16-byte internal-format user name ZSPI-TDT-BOOLEAN constant ZSPI-TDT-BOOLEAN value is 10.
ZSPI Data Definitions Token Data Types ZSPI-TDT-ENUM constant ZSPI-TDT-ENUM value is 11. The ENUM data type identifies a 16-bit signed item for which the range of acceptable values is enumerated. The maximum range of numeric values for this type is -32768 to +32767. Its format is the same as ZSPI-TDT-INT. ZSPI-TDT-ERROR constant ZSPI-TDT-ERROR value is 28. The ERROR data type identifies an error token in fully qualified form (including the subsystem ID).
ZSPI Data Definitions Token Data Types other subsystems in event messages and error lists. This form consists of an 8-byte internal-format node name followed by a 24-byte internal-format local file name. ZSPI-TDT-INT constant ZSPI-TDT-INT value is 2. The INT data type identifies a 16-bit signed integer. Its value range is -32768 to +32767. ZSPI-TDT-INT2 constant ZSPI-TDT-INT2 value is 3. The INT2 data type identifies a 32-bit signed integer. Its value range is -2,147,483,648 to +2,147,483,647.
ZSPI Data Definitions Token Data Types appears in every event message to mark this token as the subject token. A token with this token data type has no token value; that is, it has a zero token length. ZSPI-TDT-PHANDLE constant ZSPI-TDT-PHANDLE value is 32. The PHANDLE data type identifies a process handle for D-series RVUs. ZSPI-TDT-SSCTL constant ZSPI-TDT-SSCTL value is 39.
ZSPI Data Definitions Token Data Types ZSPI-TDT-TIMESTAMP constant ZSPI-TDT-TIMESTAMP value is 23. The TIMESTAMP data type identifies a 64-bit, microsecond-resolution Julian timestamp (in Greenwich Mean Time) or an elapsed-time value in microseconds. ZSPI-TDT-TOKENCODE constant ZSPI-TDT-TOKENCODE value is 29. The TOKENCODE data type is used for special SSGET, SSPUT, and EMSGET operations for which the token-value parameter is itself a token code.
ZSPI Data Definitions Token Types ZSPI-TDT-USERNAME constant ZSPI-TDT-USERNAME value is 27. The USERNAME data type identifies a 16-byte internal-format user name, such as the USERIDTOUSERNAME procedure might generate. Token Types Every token has a token type. A token type (TYP) associates a defined token data type (TDT) with a corresponding data definition. The token type can then be used in the TOKEN TYPE IS clause of a token code definition.
ZSPI Data Definitions Token Types ZSPI-TYP-CHAR token type ZSPI-TYP-CHAR value is ZSPI-TDT-CHAR def is ZSPI-DDL-CHAR. ZSPI-TYP-CHAR specifies that a token’s value consists of a single ASCII character. A token of this type has a CHAR token data type and is based on the CHAR structure. ZSPI-TYP-CHAR-PAIR token type ZSPI-TYP-CHAR-PAIR value is ZSPI-TDT-CHAR def is ZSPI-DDL-CHAR- PAIR. ZSPI-TYP-CHAR-PAIR specifies that a token’s value consists of two ASCII characters.
ZSPI Data Definitions Token Types ZSPI-TYP-CHAR6 token type ZSPI-TYP-CHAR6 value is ZSPI-TDT-CHAR def is ZSPI-DDL-CHAR6. ZSPI-TYP-CHAR6 specifies that a token’s value consists of six ASCII characters. A token of this type has a CHAR token data type and is based on the CHAR6 structure. ZSPI-TYP-CHAR7 token type ZSPI-TYP-CHAR7 value is ZSPI-TDT-CHAR def is ZSPI-DDL-CHAR7. ZSPI-TYP-CHAR7 specifies that a token’s value consists of seven ASCII characters.
ZSPI Data Definitions Token Types ZSPI-TYP-CHAR40 token type ZSPI-TYP-CHAR40 value is ZSPI-TDT-CHAR def is ZSPI-DDL-CHAR40. ZSPI-TYP-CHAR40 specifies that a token’s value consists of 40 ASCII characters. A token of this type has a CHAR token data type and is based on the CHAR40 structure. ZSPI-TYP-CHAR50 token type ZSPI-TYP-CHAR50 value is ZSPI-TDT-CHAR def is ZSPI-DDL-CHAR50. ZSPI-TYP-CHAR50 specifies that a token’s value consists of 50 ASCII characters.
ZSPI Data Definitions Token Types ZSPI-TYP-DEVICE token type ZSPI-TYP-DEVICE value is ZSPI-TDT-DEVICE def is ZSPI-DDL-DEVICE. ZSPI-TYP-DEVICE specifies that a token’s value is an 8-byte internal-format device name. A token of this type has a DEVICE token data type and is based on the DEVICE structure. ZSPI-TYP-ENUM token type ZSPI-TYP-ENUM value is ZSPI-TDT-ENUM def is ZSPI-DDL-ENUM. SPI-TYP-ENUM specifies that a token’s value is a 16-bit enumerated value.
ZSPI Data Definitions Token Types ZSPI-TYP-FNAME token type ZSPI-TYP-FNAME value is ZSPI-TDT-FNAME def is ZSPI-DDL-FNAME. ZSPI-TYP-FNAME specifies that a token’s value is a 24-byte internal-format file name. A token of this type has an FNAME token data type and is based on the FNAME structure. ZSPI-TYP-FNAME32 token type ZSPI-TYP-FNAME32 value is ZSPI-TDT-FNAME32 def is ZSPI-DDL-FNAME32. ZSPI-TYP-FNAME32 specifies that a token’s value is a 32-byte internal file name.
ZSPI Data Definitions Token Types ZSPI-TYP-INT2-PAIR token type ZSPI-TYP-INT2-PAIR value is ZSPI-TDT-INT2 def is ZSPI-DDL-INT2-PAIR. ZSPI-TYP-INT2-PAIR specifies that a token’s value is a pair of 32-bit integers. A token of this type has an INT2 token data type and is based on the INT2-PAIR structure. ZSPI-TYP-INT4 token type ZSPI-TYP-INT4 value is ZSPI-TDT-INT4 def is ZSPI-DDL-INT4. ZSPI-TYP-INT4 specifies that a token’s value is a 64-bit fixed-point number.
ZSPI Data Definitions Token Types event message to mark this token as the subject token. A token of this type has a MARK token data type and no value. ZSPI-TYP-PARM-ERR token type ZSPI-TYP-PARM-ERR value is ZSPI-TDT-STRUCT def is ZSPI-DDL-PARM-ERR. ZSPI-TYP-PARM-ERR specifies that a token’s value is a structure returned by a subsystem in an error list when a parameter error occurs in a command to the subsystem or in an SPI procedure call made by the subsystem.
ZSPI Data Definitions Token Types ZSPI-TYP-SSCTL token type ZSPI-TYP-SSCTL value is ZSPI-TDT-SSCTL occurs 0 times. ZSPI-TYP-SSCTL specifies that a token is a special token code used to direct one of the SPI procedures to perform a control operation on the buffer, such as clearing error information, flushing data from the buffer, or ending a list. A token of this type has an SSCTL token data type and no value. Subsystems should not use this token type.
ZSPI Data Definitions Token Types ZSPI-TYP-TIMESTAMP token type ZSPI-TYP-TIMESTAMP value is ZSPI-TDT-TIMESTAMP def is ZSPI-DDL-TIMESTAMP. ZSPI-TYP-TIMESTAMP specifies that a token’s value is a 64-bit Julian timestamp. A token of this type has a TIMESTAMP token data type and is based on the TIMESTAMP structure. ZSPI-TYP-TOKENCODE token type ZSPI-TYP-TOKENCODE value is ZSPI-TDT-TOKENCODE def is ZSPI-DDL-TOKENCODE. ZSPI-TYP-TOKENCODE specifies that a token’s value is itself a token code.
ZSPI Data Definitions Token Numbers ZSPI-TYP-USERNAME token type ZSPI-TYP-USERNAME value is ZSPI-TDT-USERNAME def is ZSPI-DDL-USERNAME. ZSPI-TYP-USERNAME specifies that a token’s value is a 16-byte internal-format user name. A token of this type has a USERNAME token data type and is based on the USERNAME structure. ZSPI-TYP-VERSION token type ZSPI-TYP-VERSION value is ZSPI-TDT-UINT def is ZSPI-DDL-VERSION. ZSPI-TYP-VERSION specifies that a token’s value is a software release version.
ZSPI Data Definitions Token Numbers Table 4-2.
ZSPI Data Definitions Token Numbers Token Number Definition Syntax This syntax box lists the token numbers by numeric value. (Numeric values are provided for debugging purposes only—always use the symbolic name in programs.
ZSPI Data Definitions Token Codes Token Codes This subsection describes the token codes defined by SPI. A token code associates a token number with a token type, an SSID, and a heading for formatted display of SPI messages. ZSPI-TKN-ADDR token-code value token-type ssid heading ZSPI-TKN-ADDR ZSPI-TNM-ADDR ZSPI-TYP-TOKENCODE ZSPI-VAL-NULL-EXT-SSID "Token_address". ZSPI-TKN-ADDR is a special operation token that directs SSGET to return the address of a specified token value.
ZSPI Data Definitions Token Codes Valid values for this token are: ZSPI-VAL-NORMONLY The server continues command processing with the next object in the set only if the command was completely successful on the previous object (no error list). This is the default if ZSPI-TKNALLOW-TYPE is not included in the command. ZSPI-VAL-WARNAND-NORM The server processes the next object in the set even if a warning is encountered on the previous object.
ZSPI Data Definitions Token Codes ZSPI-TKN-COMMAND token-code value token-type ssid heading ZSPI-TKN-COMMAND ZSPI-TNM-COMMAND ZSPI-TYP-ENUM ZSPI-VAL-NULL-EXT-SSID "Command". ZSPI-TKN-COMMAND contains the command number. This value is set by SSINIT and can be retrieved using SSGET. This value cannot be modified using SSPUT. ZSPI-TKN-COMMENT token-code value token-type ssid heading ZSPI-TKN-COMMENT ZSPI-TNM-COMMENT ZSPI-TYP-STRING ZSPI-VAL-NULL-EXT-SSID "Comment".
ZSPI Data Definitions Token Codes ZSPI-TKN-COUNT token-code value token-type ssid heading ZSPI-TKN-COUNT ZSPI-TNM-COUNT ZSPI-TYP-TOKENCODE ZSPI-VAL-NULL-EXT-SSID "Token_count". ZSPI-TKN-COUNT directs SSGET to obtain the total number of occurrences of a specific token in the buffer. Its token type is ZSPI-TYP-TOKENCODE. ZSPI-TKN-DATA-FLUSH token-code value token-type ZSPI-TKN-DATA-FLUSH ZSPI-TNM-DATA-FLUSH ZSPI-TYP-SSCTL.
ZSPI Data Definitions Token Codes ZSPI-TKN-DELETE token-code value token-type ZSPI-TKN-DELETE ZSPI-TNM-DELETE ZSPI-TYP-TOKENCODE. ZSPI-TKN-DELETE directs SSPUT to delete a specified token from the buffer. Its token type is ZSPI-TYP-TOKENCODE. ZSPI-TKN-ENDLIST token-code value token-type ssid heading ZSPI-TKN-ENDLIST ZSPI-TNM-ENDLIST ZSPI-TYP-SSCTL ZSPI-VAL-NULL-EXT-SSID "End_of_list". ZSPI-TKN-ENDLIST ends the current list (of any type). Its token type is ZSPI-TYPSSCTL.
ZSPI Data Definitions Token Codes error number (defined by that subsystem). For more information, see Error Numbers on page 4-46. For information about error lists, see Section 2, SPI Concepts and Protocol. ZSPI-TKN-HDRTYPE token-code value token-type ssid heading ZSPI-TKN-HDRTYPE ZSPI-TNM-HDRTYPE ZSPI-TYP-UINT ZSPI-VAL-NULL-EXT-SSID "Header_type". ZSPI-TKN-HDRTYPE identifies the type of header that the message contains.
ZSPI Data Definitions Token Codes ZSPI-TKN-LASTERR token-code value token-type ssid heading ZSPI-TKN-LASTERR ZSPI-TNM-LASTERR ZSPI-TYP-LASTERR ZSPI-VAL-NULL-EXT-SSID "Last_error". ZSPI-TKN-LASTERR records the last nonzero status code returned by an SPI procedure while processing this buffer. This value is set by the procedure that detected the error and can be retrieved using SSGET. This value can be cleared using the special SSPUT operation ZSPI-TKN-CLEARERR.
ZSPI Data Definitions Token Codes ZSPI-TKN-LIST token-code value token-type ssid heading ZSPI-TKN-LIST ZSPI-TNM-LIST ZSPI-TYP-LIST ZSPI-VAL-NULL-EXT-SSID "List". ZSPI-TKN-LIST begins a generic list. This token is provided for the convenience of subsystems you write. NonStop Kernel subsystems provided by HP do not use it. Its token type is ZSPI-TYP-LIST.
ZSPI Data Definitions Token Codes ZSPI-TKN-MAXRESP token-code value token-type ssid heading ZSPI-TKN-MAXRESP ZSPI-TNM-MAXRESP ZSPI-TYP-INT ZSPI-VAL-NULL-EXT-SSID "Max_responses". ZSPI-TKN-MAXRESP contains a value indicating the number of response records the requester accepts in a response message. This value can be set using SSINIT or SSPUT, and can be retrieved using SSGET. For more information, see Multirecord Responses on page 2-30.
ZSPI Data Definitions Token Codes ZSPI-TKN-OBJECT-TYPE token-code value token-type ssid heading ZSPI-TKN-OBJECT-TYPE ZSPI-TNM-OBJECT-TYPE ZSPI-TYP-ENUM ZSPI-VAL-NULL-EXT-SSID "Object_type". ZSPI-TKN-OBJECT-TYPE contains the object type to which the command is to be applied. This value is set by SSINIT and can be retrieved using SSGET. This value cannot be modified using SSPUT.
ZSPI Data Definitions Token Codes TKN-LASTPOSITION, it sets the current position according to the passed position value. Position values are based on the byte offsets of tokens in the buffer; position values are rendered invalid if an SSPUT with ZSPI-TKN-DELETE or ZSPI-TKN-DATAFLUSH is used to modify the buffer after the position value is obtained. ZSPI-TKN-PROC-ERR token-code value token-type ssid heading ZSPI-TKN-PROC-ERR ZSPI-TNM-PROC-ERR ZSPI-TYP-ENUM ZSPI-VAL-NULL-EXT-SSID "Procedure_in_error".
ZSPI Data Definitions Token Codes ZSPI-TKN-RESPONSE-TYPE token-code value token-type ssid heading ZSPI-TKN-RESPONSE-TYPE ZSPI-TNM-RESPONSE-TYPE ZSPI-TYP-RESPONSE-TYPE ZSPI-VAL-NULL-EXT-SSID "Response_type". ZSPI-TKN-RESPONSE-TYPE indicates what kinds of response records the subsystem should return. Its token type is ZSPI-TYP-ENUM.
ZSPI Data Definitions Token Codes ZSPI-TKN-SEGMENTATION token-code value token-type ssid heading ZSPI-TKN-SEGMENTATION ZSPI-TNM-SEGMENTATION ZSPI-TYP-BOOLEAN ZSPI-VAL-NULL-EXT-SSID "Segmented_response_support". A server uses this token to announce that it can generate segmented responses—by returning the token with a value of TRUE in its GETVERSION response. A value of FALSE (or the absence of the token from the GETVERSION response) indicates that the server does not support segmented responses.
ZSPI Data Definitions Token Codes ZSPI-TKN-SSID token-code value token-type ssid heading ZSPI-TKN-SSID ZSPI-TNM-SSID ZSPI-TYP-SSID ZSPI-VAL-NULL-EXT-SSID "SSID". ZSPI-TKN-SSID contains the subsystem ID of the server that is to process the command. This value is set by SSINIT and can be retrieved using SSGET. This value cannot be modified using SSPUT. ZSPI-TKN-SSID-ERR token-code value token-type ssid heading ZSPI-TKN-SSID-ERR ZSPI-TNM-SSID-ERR ZSPI-TYP-SSID ZSPI-VAL-NULL-EXT-SSID "SSID_error".
ZSPI Data Definitions Token Length Token Length The second part of the token code is the token length. For fixed-length token values up to 254 bytes long, this field gives the length of the token value in bytes. When the value of this field is 255, the token value is either variable length or a fixed length greater than 254 bytes. When the fixed length is greater than 254, the actual length is supplied in a succeeding word. The special operator ZSPI-TKN-LEN returns the token length.
ZSPI Data Definitions Error Numbers Error Numbers Error numbers are 16-bit signed integers used to identify errors that SPI servers can return in response messages. Error number definition syntax is listed below. The errors are described in Appendix A, Errors. Error Number Definition Syntax This syntax box lists the error numbers by numeric value. (Numeric values are provided for debugging purposes only—always use the symbolic name in programs.
ZSPI Data Definitions Subsystem Numbers Subsystem Numbers The SPI definitions include a subsystem number for every NonStop Kernel subsystem that has a programmatic command interface based on SPI, reports events through EMS, or defines error information in SPI error lists. Your program should use the symbolic names for these subsystem numbers. The names are all of the form ZSPISSN-subsys, where subsys is the appropriate four-character subsystem abbreviation.
ZSPI Data Definitions Miscellaneous Values ZSPI-VAL-HDRSIZE constant ZSPI-VAL-HDRSIZE value is 256. ZSPI-VAL-HDRSIZE is the recommended number of bytes to reserve for the standard command header. It is provided primarily for use by subsystems in determining their recommended buffer sizes. ZSPI-VAL-MSGCODE constant ZSPI-VAL-MSGCODE value is -28. ZSPI-VAL-MSGCODE is the signed integer value found in the first word of every SPI message.
ZSPI Data Definitions Miscellaneous Values ADDR, ZSPI-TKN-LEN, ZSPI-TKN-OFFSET, and ZSPI-TKN-COUNT. Using the null token code has the same effect as omitting token-code: the operation returns the address, length, or offset of the currently selected token, or counts occurrences of the current token beginning with the current occurrence. ZSPI-VAL-NULL-VERSION constant ZSPI-VAL-NULL-VERSION value is 0. ZSPI-VAL-NULL-VERSION is the null version value.
ZSPI Data Definitions Miscellaneous Values ZSPI-VAL-VERSION constant ZSPI-VAL-VERSION value is version "D20". ZSPI-VAL-VERSION is the one-word version value of this version of the SPI standard definitions. The left byte contains the letter part of the version as an ASCII uppercase alphabetic character, and the right byte contains the numeric part of the version as an unsigned integer value. For example, for the version “G06,” the left byte is the ASCII character G, and the right byte is “06”.
5 General SPI Programming Guidelines This section offers three categories of programming guidelines: Topic Page General Guidelines for All SPI Programs 5-1 Guidelines for SPI Requesters 5-8 Guidelines for SPI Servers 5-16 General Guidelines for All SPI Programs The guidelines in this section apply to all SPI programs—requesters and servers. Retrieving Tokens by Name The most common way to retrieve tokens from the buffer is by passing their names to SSGET.
General SPI Programming Guidelines Scanning a Buffer Sequentially After the call, the positioning is: current | v next | v The SSGET procedure also includes a count parameter. This feature lets a program extract up to the specified number of occurrences of a token in one call, whether they are contiguous or not, and receive their values as an array.
General SPI Programming Guidelines Scanning a Buffer Sequentially Successive calls with ZSPI-TKN-NEXTCODE: token code 1st 2nd 3rd 4th 5th call call call call call occurrences A 3 B 1 A 2 C 1 ZSPI-ERR-MISTKN The NEXTCODE operation sets both the current position and the next position to the token code it returns. This means that a subsequent call to SSGET with the returned token code can be used to get the value associated with that token code.
General SPI Programming Guidelines Positioning the Buffer Pointers Positioning the Buffer Pointers Whenever SSGET retrieves a token from the data portion of the buffer, it starts at a given position and scans the buffer until it finds the appropriate token. The SSGET procedure maintains pointers in the SPI message header to keep track of positioning in the buffer. As your program scans the buffer with SSGET, these pointers are automatically updated.
General SPI Programming Guidelines Working With Lists Working With Lists SPI defines four types of lists, as described in Lists on page 2-19. Every list starts with a list token corresponding to the type of list (ZSPI-TKN-LIST, ZSPI-TKN-DATALIST, ZSPI-TKN-SEGLIST, or ZSPI-TKN-ERRLIST) and ends with ZSPI-TKN-ENDLIST. You can think of the list token and the end-list token as analogous to left and right parentheses.
General SPI Programming Guidelines Checking for Null Values When SSGET is first called to scan this buffer (with any token code other than ZSPITKN-NEXTTOKEN), it sees only three tokens: The tokens inside the lists are not available until the list is selected. Calling SSGET with a list token selects that list.
General SPI Programming Guidelines Resetting the Buffer and after the current position, including any tokens within lists, by using SSPUT with the operation ZSPI-TKN-DATA-FLUSH. These two operations are useful mostly to server programs in preparing response messages.
General SPI Programming Guidelines Writing High-Level Procedures Writing High-Level Procedures The SPI procedures provide basic functionality for building and decoding SPI buffers. If your application performs some commands frequently, you might want to simplify your programming task by writing high-level procedures that themselves call on the SPI procedures.
General SPI Programming Guidelines Starting the Management Process Starting the Management Process Some subsystem server processes can be started through SYSGEN or by an operator before the application is run; some can be explicitly started by the application using the NEWPROCESS or PROCESS_CREATE_ procedure; and some can be started either way. How the server can be started and in what form it is run depend on the subsystem and, in some cases, on decisions made at your installation.
General SPI Programming Guidelines Opening the Management Process Opening the Management Process Your application has complete responsibility for establishing contact with the subsystem, sending and receiving the messages, and terminating contact. How your application performs these tasks depends on the subsystem and the programming language you are using.
General SPI Programming Guidelines Preparing the Command Buffer Error 16: File Number Has Not Been Opened The management process rejected an open attempt because it had not yet completed its own initialization when it received the open request. Try the open again later.
General SPI Programming Guidelines Sending the Command After you have allocated the buffer, use the SPI procedures to initialize it and add tokens containing the information for your command, as described in Section 3, The SPI Procedures. Sending the Command After it has established communication with the management process, your application can use any standard mechanism for sending and receiving messages.
General SPI Programming Guidelines Receiving the Response Error 2: Request Not an SPI Buffer The process rejected a message because the requester had it open for SPI commands, but the command was not a valid SPI buffer. For instance, the first word of the message did not contain -28, or the subsystem received an event message when it expected a command. Check that the command is a properly formatted SPI buffer.
General SPI Programming Guidelines Taking Action Based on the Response Your application might be interested only in whether the command succeeded or failed, and perhaps in a limited amount of associated information. In this case, simply check the value of the return token and ignore any error lists. Some applications, however, might want full information about multiple errors and warnings and pass-through errors.
General SPI Programming Guidelines Stopping the Management Process Stopping the Management Process Some subsystems have a special command to stop the management process explicitly. Others stop this process automatically. Still others determine how they will stop by reading the AUTOSTOP parameter sent as part of the startup message (see Starting the Management Process on page 5-9). For details, see the individual subsystem management programming manual.
General SPI Programming Guidelines • • • • • • • • Guidelines for SPI Servers Initialize every request with the SSID provided by the subsystem. Do not reuse a response message without initializing it—some header values set by the server are not appropriate for the request. Avoid defining data items with names beginning with Z. Tolerate unrecognized tokens in a response. Ignore responses that contain the “empty response” return code.
General SPI Programming Guidelines Defining Simple Tokens where hdr is the size of the SPI message header, defined by SPI as ZSPIVAL-HDRSIZE. tokens is the total number of tokens in the longest command or response message defined by the server. This value includes list tokens (ZSPI-TKN-LIST, -DATALIST, -SEGLIST, -ENDLIST). A token code is 4 bytes long. ssid-qual-tokens is the total number of tokens that are qualified by an SSID. The SSID adds 12 bytes to the length of a token code.
General SPI Programming Guidelines Defining Simple Tokens each of which SPI defines as a fixed structure. It is recommended that most structured tokens defined for a subsystem be extensible structured tokens. SPI uses a token length of zero in some tokens—such as the tokens that begin and end lists—to indicate that these tokens have no token values. However, it is recommended that tokens you define always have a value. If there are only two choices, the value can be of a Boolean or enumerated type.
General SPI Programming Guidelines Defining Extensible Structured Tokens Defining Extensible Structured Tokens Some restrictions on what can be done with extensible structured tokens are: • • • Any item that is inherently of variable length cannot be included as a field of an extensible structured token. Although an extensible structured token can grow from release to release, in any given release it must have a fixed size.
General SPI Programming Guidelines Defining Extensible Structured Tokens parameters to ADD. If a change is made that makes a formerly unalterable attribute alterable, problems arise. You can not move the field from the second structure to the first, because removing a field is an incompatible change. If you leave the field where it is, your partitioning of fields is no longer consistent. Do not place other command parameters or results in the structures that contain object attributes.
General SPI Programming Guidelines Defining Extensible Structured Tokens have a negative value, 255 is a good choice; a numeric field of any length, with this value in every byte, is always -1.) In choosing a null value for a field, consider future possible valid values for the field and avoid making one of those values the null value; otherwise, changes to your subsystem might make it incompatible with existing applications.
General SPI Programming Guidelines Defining Extensible Structured Tokens field must be described as NOVERSION to let SPI’s automatic determination of maximum field version work properly. The first approach has the advantage that no extra field is involved. The second has the advantage that the data type of the field is what it naturally should be.
General SPI Programming Guidelines Coding Subsystem Definitions Token Map For extensible structured tokens, programs pass to the SPI procedures an extended identifying code called a token map. A token map is a variable-length integer array. The first two words of a token map have the same structure as a token code. All token maps have a token data type of ZSPI-TDT-MAP, a token length of 255, and a token number specified by the subsystem. Most subsystems define a set of token maps.
General SPI Programming Guidelines • • • • Using the SPI Standard DDL Definitions Possible values for any enumerated-type tokens or fields Structure definitions for all extensible structured tokens Token codes for all simple tokens Token maps for all extensible structured tokens You can also include any other definitions that might be of use to requester programs sending commands to your subsystem.
General SPI Programming Guidelines Suggestions on Data Representation ensures that applications written in COBOL can accommodate the full range of values of these integers. • • • • • • • • Do not use 32-bit floating point or 64-bit floating point values unless absolutely necessary. These data types are not supported by COBOL or TACL. Do not use collections of bit flags, short integers, or short enumerated fields packed into a word unless there is a good reason to do so.
General SPI Programming Guidelines Dividing Your Definition File Into Sections any of your fields are of odd length, filler bytes might appear where you don’t want them. • • In the TAL declarations, make arrays have a lower bound of zero. Represent time intervals in microsecond precision and stored in fields of the SPI type ZSPI-DDL-TIMESTAMP.
General SPI Programming Guidelines Version Compatibility The names subsysROOT, BUILDING-BLOCKS, REQUESTER-VISIBLE-1, REQUESTER-VISIBLE-2, and REQUESTER-VISIBLE-3 are just illustrative—you can choose other names, because those names are not of interest to someone who wants to use the subsysDDL file just to compile the definitions into a DDL dictionary. That person just ?SOURCEs in the whole file without naming the sections individually.
General SPI Programming Guidelines Defining Objects 13. The size of a response message should not grow larger than the smallest size ever given as the recommended buffer size. When an interface is first designed, the recommended buffer size should factor in an estimate of how much the response is likely to grow in the future. Allow a generous amount, but keep the buffer size within reason.
General SPI Programming Guidelines • Subsystem ID Remove the attributes that can be repeated from the original object type and put them in a new object type that is a subsidiary of the original object type, making each repetition a separate instance of the subsidiary type. The name of an instance of the subsidiary object type is generally one of the attributes of the subsidiary object type concatenated with the name of the instance of the original object type.
General SPI Programming Guidelines Subsystem ID Choose a value for the subsystem-number field. If your company is writing more than one subsystem, this number should be unique for each subsystem. Note. When subsystems from a number of different suppliers are installed on a given system, there is a potential for confusion and improper operation if two subsystems share the same owner and subsystem number.
General SPI Programming Guidelines 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.
General SPI Programming Guidelines Checking Tokens in the Command Likewise, your subsystem should report any subsequent errors as SPI error responses, each identifying the error with a subsystem-defined error number in the return token. Checking Tokens in the Command Your subsystem should report missing required tokens, and should detect and report any extraneous tokens (including too many occurrences of valid tokens). This pseudocode example illustrates one way to approach these tasks.
General SPI Programming Guidelines Checking Tokens in the Command go to send^reply end ! ! ! ! ! For simple, variable-length tokens, a check of the length is needed. Omit this for fixedlength tokens. (Omitting the token code that is the third argument to SSGET means to use the token at the current position.
General SPI Programming Guidelines Checking Tokens in the Command go to send^reply end case end do ! Check that all the required tokens were supplied. if count[subsys^TNM^REQUIRED1] = 0 then reject(subsys^TKN^REQUIRED1,0, subsys^ERR^REQUIRED^MISSING) go to send^reply end if count[subsys^TNM^REQUIRED2] = 0 then reject(subsys^MAP^REQUIRED2^V,0, subsys^ERR^REQUIRED^MISSING) go to send^reply end (Repeat for each required token.
General SPI Programming Guidelines Checking Tokens in the Command int errcode struct .ssid(ZSPI^DDL^SSID^DEF) begin struct error(ZSPI^DDL^ERROR^DEF) struct parm^err(ZSPI^DDL^PARM^ERR^DEF) SSPUT(reply,ZSPI^TKN^RETCODE,errcode) SSPUT(reply,ZSPI^TKN^ERRLIST) error.z^ssid := subsys^VAL^SSID error.z^error := errcode SSPUT(reply,ZSPI^TKN^ERROR,error) parm^err.z^tokencode.z^tkncode := tokencode parm^err.z^index := index parm^err.
General SPI Programming Guidelines Checking Tokens in the Command For token maps, the example assumes that the subsys^MAP^xxxx definitions are used to declare and initialize variables whose names are formed by adding ^V to the end: subsys^MAP^xxxx^V. There are, of course, other ways to make the token maps available in the program. Because this example focuses on scanning for tokens in the command, it does not include error handling for errors from the SSPUT calls that build the response.
General SPI Programming Guidelines Checking for Command Cancellation The method described here is not the only valid approach, but it does illustrate the functions that should be performed. Checking for Command Cancellation As described in Canceling Commands on page 5-14, an application can use the filesystem CANCEL or CANCELREQ procedure to cancel command requests issued to your subsystem. Servers do not have to take any special action.
General SPI Programming Guidelines Using SSPUT to Place Lists in the Buffer Servers that do not otherwise need to support command cancellation need not be aware of command cancellation at all. If a subsystem needs to provide a way for a requester to cancel a command and learn something about how much the command did before it was canceled, that subsystem must implement an additional form of cancellation. Using SSPUT to Place Lists in the Buffer To place a list in the buffer: 1.
General SPI Programming Guidelines Defining Commands SSPUT SSPUT (BUF, ZSPI-TKN-RETCODE, STATUS) (BUF, ZSPI-TKN-ENDLIST) SSPUT (BUF, ZSPI-TKN-CONTEXT, CONTEXT) ! CONTEXT INFORMATION !END OF SECOND ! RESPONSE RECORD Defining Commands After you have determined what objects your subsystem will manage, you must decide what management services the subsystem needs to have, and then design programmatic commands to implement those services.
General SPI Programming Guidelines Single and Multiple Response Records per Response SERVER-BANNER). Your subsystem should include a similar command. Optionally, your GETVERSION command can return additional information. Every command sent to a NonStop Kernel subsystem returns the internal form of the server version in ZSPI-TKN-SERVER-VERSION. However, GETVERSION is useful because it is a safe command—one that simply returns information and makes no changes to the state of the system or network.
General SPI Programming Guidelines Defining the Context Token As described in Section 2, SPI Concepts and Protocol, the requester should return this context token in the next command message along with the original command. Each server that receives a command with a context token should check for: • • The command and parameters are consistent with the context supplied. The requester has not bypassed security or integrity constraints by supplying a forged or modified context token.
General SPI Programming Guidelines Defining the Context Token Figure 5-1. Response Continuation for a Typical Information Command Terminal Name <+> Requester Subsystem <$a> <$a> Context Terminal Name <+> Context <$a> Requester Subsystem <$b> <$b> Context ! ! ! Terminal Name <+> Context <$x> Requester Subsystem <$last> VST021.
General SPI Programming Guidelines Context Sensitivity context. If desired, the server can also provide more detailed information about the error. A server is not required to accept a context token from a different version of the server. Requesters cannot expect to save a context token from some session with a server and use it with another session sometime later. The server is not required to detect or reject such long-term saving of context tokens.
General SPI Programming Guidelines Determining How Many Response Records Fit in a Buffer Assume that the server builds the response record in the buffer during the course of executing the command on each object, and assume that the server knows a definite limit on the size of every possible response record.
General SPI Programming Guidelines Consistency Between Response Records in Different Replies then go to continue; if MAXRESP > -1 then if num-responses >= MAXRESP then go to continue; if multiple-responses then SSPUT(ZSPI-TKN-DATALIST); ! start response SSPUT(subsys-TKN-xxxxx,object name); processing-loop: do some work; SSGET(ZSPI-TKN-LASTPOSITION,remember-place); insert next token or error list into response; if buffer is full then go to backout; if ZSPI-TKN-BUFLEN - ZSPI-TKN-USEDLEN < overflow-need then
General SPI Programming Guidelines • • Checking the Context Token Make the server context-sensitive and hold a snapshot of the object’s current state in the server’s memory. Take a snapshot of the object, store it in a file (called a “snapshot file”), and use the context token to keep track of where the snapshot is stored.
General SPI Programming Guidelines Control of Types of Response Records do define standard error lists (for instance, some system procedures such as NEWPROCESS), and if your subsystem encounters critical errors in calls to the SPI procedures, HP recommends that you return error lists to applications in the standard form, and use the appropriate HP definition files for the tokens in these error lists rather than defining your own.
General SPI Programming Guidelines Reporting Errors From the SPI Procedures Failure of SSGET on a Header Token If SSGET fails when attempting to get any header token from a command, your subsystem should return an error response to report the problem. The return token of this response should be the one your subsystem defines to indicate that an SPI error occurred.
General SPI Programming Guidelines • Reporting Errors From the SPI Procedures As for the failure of SSGET on a header token, check that the buffer for this error response is large enough, and handle any errors from the procedures involved in creating the response. Failure of SSINIT When Initializing a Response Buffer If SSINIT fails for any reason except “buffer full,” a serious error has occurred.
General SPI Programming Guidelines Reporting Errors From the SPI Procedures Some suggestions: • • • • Your subsystem should stop immediately instead of attempting to continue. If you do attempt to continue and report the failure, initialize and build a buffer for a response (see Failure of SSGET on a Header Token on page 5-48). It is not imperative that you ignore ZSPI-TKN-MAXRESP. However, for simplicity, it is recommended that you return a single response record per response.
General SPI Programming Guidelines Pass-Through Error Lists Failure of SSGET With ZSPI-TKN-USEDLEN If after completing a response message, the server calls SSGET with ZSPI-TKNUSEDLEN to determine the count to use when sending the response, and SSGET fails, the server’s data stack is corrupt and the server should stop. If you do attempt to generate a response, proceed as in the case of SSINIT or SSPUT.
General SPI Programming Guidelines Pass-Through Error Lists contain those items needed to tell what inappropriate condition was detected and any additional values needed to understand the error. For example, if a command asks to start a subdevice when the line is not started and the name of the line is inherent in the name of the subdevice, no additional information need be included.
General SPI Programming Guidelines Pass-Through Error Lists Fill in only the Z-TOKENCODE field to describe a missing required token. If more than one field is involved in the error (as in the case of a field that conflicts with the value of another field), repeat the ZSPI-TKN-PARM-ERR token for each field involved. In addition, if the subsystem ID qualifying the token is not the default subsystem ID, include the ZSPI-TKN-SSID-ERR token to identify that SSID.
General SPI Programming Guidelines Summary of Server Role error. Omitting the token from the error list seems like a reasonable approach in that case, but if that is not suitable, include explicit directions for what to do. • • If a set of procedures are closely related (such as the HP file-system procedures), such procedures can share a subsystem ID. In these cases, you should use the token ZSPI-TKN-PROC-ERR token to indicate which of the procedures is involved.
6 SPI Programming in C This section provides language-specific information for the programmer who is using C to write an SPI requester or server: Topic Page Definition Names in C 6-1 C Definition Files 6-1 Declarations Needed in C Programs 6-2 Interprocess Communication 6-3 Writing a Server in C 6-3 SPI Procedure Syntax in C 6-4 Definition Names in C Symbolic names in this section are in the C form, using underscore (_) symbols rather than hyphens.
SPI Programming in C Declarations Needed in C Programs In these definition files, the structures are in lowercase (for example, zspi-ddl-ssid-def) and the defines are in uppercase (for example, ZSPI-TKN-SSID). The #include directive for ZSPIDEF.ZSPIC must appear first. Any #include directives for files that contain your own declarations must come after the #include directives for the standard files. The DDL compiler combines the items of a DDL REDEFINES clause into a union.
SPI Programming in C Passing Tokens by Value Performing the initialization this way causes compiler Warning 74: initializer data truncated. You can ignore the warning; the initialization is performed correctly. The second way to initialize the structure: #include stringh strcpy ( zosi_val_ssid.z_owner, ZSPI_VAL_TANDEM ); strcpy ( zosi_val_ssid.z_number, ZSPI_SSN_ZOSI ); strcpy ( zosi_val_ssid.z_version, ZOSI_VAL_VERSION ); The compiler does not issue a warning if you use this initialization method.
SPI Programming in C SPI Procedure Syntax in C SPI Procedure Syntax in C To call SPI procedures from a C program, you use the tal interface declaration, just as you would when calling other operating system procedures. For descriptions of the SPI procedures and their parameter, see Section 3, The SPI Procedures.
SPI Programming in C SSPUT and SSPUTTKN SSPUT and SSPUTTKN #include short SSPUT ( short *buffer short *token-id char *token-value short count short *ssid , ,[ ,[ ,[ ] ] ] ); #include short SSPUTTKN ( , ,[ ,[ ,[ short *buffer long token-id char *token-value short count short *ssid ] ] ] ); SSGET and SSGETTKN #include short SSGET ( short *buffer short *token-id char *token-value short index short *count short *ssid , ,[ ,[ ,[ ,[ ] ] ] ] )
SPI Programming in C SSMOVE and SSMOVETKN SSMOVE and SSMOVETKN #include short SSMOVE ( short short short short short short short , ,[ , ,[ ,[ ,[ *token-id *source-buffer source-index *dest-buffer dest-index *count *ssid ] ] ] ] ); #include short SSMOVETKN ( , ,[ , ,[ ,[ ,[ long short short short short short short token-id *source-buffer source-index *dest-buffer dest-index *count *ssid ] ] ] ] ); Examples For example source code programs written in C, se
7 SPI Programming in COBOL This section provides language-specific information for the programmer who is using COBOL to write an SPI requester or server. (COBOL74 does not support SPI.
SPI Programming in COBOL Declarations Needed in COBOL Programs Declarations Needed in COBOL Programs In addition to the declarations provided in the definition files, you must add these declarations to your COBOL programs. SPI Buffer In the Data Division of your program, you must set up the file for requester-server communication. Use a file description (FD) entry similar to: FD SERVER-FILE LABEL RECORDS ARE OMITTED.
SPI Programming in COBOL Interprocess Communication . . MOVE COBOL-VAL-TRUE TO ZTMF OF ZPWY-DDL-DEF-PROG. or IF ZTMF OF ZPWY-DDL-DEF-PROG = COBOL-VAL-FALSE . . . or IF ZTMF OF ZPWY-DDL-DEF-PROG NOT = COBOL-VAL-FALSE . . . . . It is recommended that you use the comparison “NOT = false-value” rather than “= true-value,” in case a subsystem uses a value other than -1 for TRUE.
SPI Programming in COBOL Communicating With the Server Communicating With the Server Except in the case of the EMS collector process ($0), use the OPEN verb to open the server, and use the READ WITH PROMPT verb to send commands to it. To open the EMS collector process to send commands to it or to report events, you must use the utility routine COBOL^SPECIAL^OPEN. To open the collector to send commands to it, specify “$0.#ZSPI” in the SELECT clause.
SPI Programming in COBOL SSINIT SSINIT ENTER TAL "SSINIT" USING buffer buffer-length ssid header-type command [ object-type [ max-resp [ server-version [ checksum [ max-field-version GIVING status. ] ] ] ] ] SSNULL ENTER TAL "SSNULL" USING token-map struct GIVING status. SSPUT ENTER TAL "SSPUT" USING buffer token-id [ token-value [ count [ ssid GIVING status. ] ] ] SSPUTTKN Use SSPUT rather than SSPUTTKN in COBOL programs.
SPI Programming in COBOL SSGET SSGET ENTER TAL "SSGET" USING buffer token-id [ token-value [ index [ count [ ssid GIVING status. ] ] ] ] SSGETTKN Use SSGET rather than SSGETTKN in COBOL programs. SSMOVE ENTER TAL "SSMOVE" USING token-id source-buffer [ source-index dest-buffer [ dest-index [ count [ ssid GIVING status. ] ] ] ] SSMOVETKN Use SSMOVE rather than SSMOVETKN in COBOL programs.
8 SPI Programming in TACL This section provides language-specific information for the programmer who is using the TACL to write an SPI requester or server: Topic Page Definition Names in TACL 8-1 Limitations of TACL for SPI Programming 8-1 TACL Definition Files 8-2 Declarations and Data Representations in TACL 8-2 Syntax of the TACL Built-Ins 8-8 Interprocess Communication 8-30 Example: Printing or Displaying the Status Structure of the Subsystem Control Point (SCP) 8-30 Definition Names i
SPI Programming in TACL TACL Definition Files TACL Definition Files TACL macros and routines must load the SPI standard definition file named ZSPIDEF.ZSPITACL on the disk volume chosen by your site, and must also load the definition files in TACL for all subsystems with which your program communicates. For NonStop Kernel subsystems, the names of the definition files in TACL are of the form ZSPIDEF.subsysTACL, where subsys is the four-character subsystem abbreviation.
SPI Programming in TACL • SPI Buffer For parameters that require external-format numbers, a numeric variable (a TEXT variable whose contents represent a number) is acceptable. SPI Buffer An SPI buffer in TACL is a writable variable level of type STRUCT. The definition of the STRUCT is irrelevant to TACL, except that TACL passes its length to the SSINIT procedure. The ZSPIDEF.subsysTACL definition file for each NonStop Kernel subsystem includes a buffer declaration whose name is subsys^DDL^MSG^BUFFER.
SPI Programming in TACL Token Codes In the first two examples, you could substitute 18182 for G06; however, G06 is recommended for clarity. The last two examples are possible subsystem IDs for a subsystem you might write. The third example assumes that you define your versions as simple integers. The fourth example assumes that you define them in the same format HP uses. The null value of the subsystem ID in TACL is 0.0.0.
SPI Programming in TACL Token Values Token Values These pages give the TACL types, value ranges, external representations, and special considerations for token values of the various token data types. TACL Types and Value Ranges In the definition files for SPI and the various NonStop Kernel subsystems, most tokens and token fields translate into appropriate TACL variable and field types, including high-level TACL types such as CRTPID, FNAME, and TIMESTAMP.
SPI Programming in TACL Token Values Table 8-1.
SPI Programming in TACL Identifying Null Values Values of token data type ZSPI^TDT^SSID have the external format described in Subsystem ID on page 8-3. Values of token data type ZSPI^TDT^ERROR consist of a subsystem ID in that format followed by a period and a numeric character string representing a number in the range -32768 to +32767. Values of token data type ZSPI^TDT^TRANSID have this external format: \system-name(crash-count).cpu.
SPI Programming in TACL Setting Reset Values Setting Reset Values Some subsystems, such as Pathway, define special values (similar to null values) that, when assigned to structured-token fields that represent command parameters, direct the subsystem to reset those parameters to their default values. However, these values might not always be legitimate values for the field as defined in TACL. To circumvent this problem, use the TACL built-in #SETBYTES to set these fields.
SPI Programming in TACL #SSINIT You can use #SSINIT only to initialize a buffer for a command or a response; it cannot be used to initialize an event-message buffer. #SSINIT [ / TYPE 0 / ] buffer-var ssid command [ / type-0-option [ , type-0-option ]... / ] TYPE 0 indicates the header type of the SPI message buffer being initialized. Type 0, a command or response header, is the default. It is also the only header type currently supported by TACL.
SPI Programming in TACL #SSNULL OBJECT object-type gives the object type. If you do not supply this option, the object type defaults to ZSPI^VAL^NULL^OBJECT^TYPE (zero). SERVERVERSION server-version is normally provided only by subsystems or by other programs that are acting as a server. In those cases, it is a 16-bit unsigned integer value representing the version of the subsystem or server program.
SPI Programming in TACL #SSPUT token-map is a token map to be used in initializing the fields of the structure. struct is the structure to be initialized with null values. Expansion #SSNULL expands to a numeric status code indicating the outcome of the operation. The status code has one of these values: 0 -3 -4 -7 -9 No error Missing parameter Illegal parameter address Internal error Illegal token code or map For more information about nonzero status codes, see Appendix A, Errors.
SPI Programming in TACL #SSPUT SSID ssid is a subsystem ID that qualifies the token code. If ssid is zero (0.0.0) or if you do not supply this option, the default applies. If #SSPUT is currently adding tokens to a list, ssid defaults to the subsystem ID of that list; otherwise, ssid defaults to the subsystem ID in the SPI message header (ZSPI^TKN^SSID). buffer-var is the name of the SPI message-buffer variable into which tokens are to be placed.
SPI Programming in TACL • • #SSPUT Specifying a count parameter greater than one for #SSPUT is equivalent to calling #SSPUT count number of times in succession with a count of 1 (but supplying a new token-value before each call). If count is greater than 1 and the token is of variable length, the length of each token value must be an even number of bytes to ensure word alignment. For example, the object-name token used by extended-SPI subsystems, ZCOM^TKN^OBJNAME, is a variable-length character string.
SPI Programming in TACL #SSPUT Table 8-2.
SPI Programming in TACL #SSPUT The ZSPI^TKN^DATA^FLUSH operation does not cause the header token ZSPI^TKN^MAX^FIELD^VERSION to be updated. As a result, following this operation, that field can indicate a version higher than that contained in the buffer. ZSPI^TKN^DELETE: Delete a Token or List Use this token code to delete a token code from the buffer. For token-value, specify the token code to be deleted. You must supply COUNT count.
SPI Programming in TACL #SSPUTV byte values for #SSPUT or as an 8-byte STRUCT for #SSPUTV. For this operation to be valid, the contents of the buffer prior to the previously saved position must not have been modified by ZSPI^TKN^DELETE, ZSPI^TKN^DATAFLUSH, or #SSMOVE operations. Otherwise, this operation can corrupt the buffer and cause later operations to give indeterminate results. If token-value is zero or not supplied, this operation sets the current position to the beginning of the buffer.
SPI Programming in TACL #SSPUTV COUNT count gives the token count. If count is greater than 1, source-var is assumed to contain an array of count elements, each of which is described by the token-id. If you do not supply this option, TACL assumes a count of 1. If token-id is one of the special SPI token codes whose semantics do not allow a token value, you must omit COUNT count.
SPI Programming in TACL #SSPUTV For more information about nonzero status codes, see Appendix A, Errors. Considerations • • • • • If the token length specified by token-id is zero (for instance, if token-id is ZSPI^TKN^DATALIST, ZSPI^TKN^ERRLIST, ZSPI^TKN^LIST, ZSPI^TKN^ENDLIST, or ZEMS^TKN^SUBJECT^MARK), you must still supply a variable for source-var, but its contents do not matter.
SPI Programming in TACL • #SSGET SPI defines a number of token codes for use with #SSPUT and #SSPUTV to set the values of header tokens and perform special operations. See Special Operations for #SSPUT and #SSPUTV on page 8-13. #SSGET Use #SSGET to retrieve binary token values from an SPI buffer, convert them to external representation, and make that external representation accessible in the function’s expansion.
SPI Programming in TACL #SSGET SSID ssid gives a subsystem ID (of type SSID) that qualifies the token code. If ssid is omitted or equal to zero (0.0.0), it defaults to the subsystem ID of the current list, or if the current position is not in a list, then to the subsystem ID specified in the SPI message header. The version field of this parameter is not used when searching the buffer. buffer-var is the name of the SPI message-buffer variable from which information is to be extracted.
SPI Programming in TACL #SSGET If l-token-id is either omitted or equal to ZSPI^VAL^NULL^TOKENCODE and index is either omitted or zero, then #SSGET returns the length of the current occurrence of the current token. If l-token-id is a token map, this operation returns the length contained within the specified token map; the actual value in the buffer can be longer or shorter than this length.
SPI Programming in TACL #SSGET If o-token-id is either omitted or equal to ZSPI^VAL^NULL^TOKENCODE and index is either omitted or zero, then #SSGET returns the length of the current occurrence of the current token. Expansion #SSGET expands to a numeric status code indicating the outcome of the operation. If the status code is 0 (no error), it is followed by a space and a space-separated list of the relevant results in TACL’s external representation.
SPI Programming in TACL #SSGET Considerations • When token-code is ZSPI^TKN^ENDLIST, the index and count parameters have no effect. However, if supplied, index must be equal to zero or 1, and the count in the expansion is always returned as 1. Header Tokens and Special Operation for #SSGET and #SSGETV The index parameter you supply with these token codes must be 0 or 1. Table 8-3.
SPI Programming in TACL #SSGETV If the default subsystem ID comes from a list token, the version field of the returned subsystem ID value is set to ZSPI^VAL^NULL^VERSION. Therefore, when comparing subsystem ID values for equality, your program should omit the version field from the test. #SSGETV Use #SSGETV to obtain binary token values from an SPI buffer and put them into a STRUCT. You can use #SSGETV with any type of token.
SPI Programming in TACL #SSGETV result-var is the name of the writable STRUCT in which #SSGETV is to store the result. The original contents of the STRUCT are lost. If the status code in the expansion is 0 (no error), the result stored in the STRUCT is: • • • • • • If you specified token-id, the result is the value of the token.
SPI Programming in TACL #SSGETV If the status is 0 and the get-op is token-id, the status is followed by a space and the number of token values returned. For more information about nonzero status codes, see Appendix A, Errors.
SPI Programming in TACL #SSMOVE #UNFRAME {same_ssid} • • • • • • • Tokens extracted by #SSGETV are not deleted or removed from the buffer. When the current position is within a particular list, all #SSGETV calls pertain only to tokens within that list, except that header tokens are always accessible. Your program can exit the list by calling #SSGET with the ZSPI^TKN^ENDLIST token. When token-id is ZSPI^TKN^ENDLIST, the index and count parameters have no effect.
SPI Programming in TACL #SSMOVE COUNT count gives the maximum number of token values to copy, unless token-id is a list token; in the latter case, it gives the maximum number of lists to copy. If you do not supply this option, count defaults to 1. DINDEX dest-index if dest-index is greater than zero, identifies the first occurrence of tokenid to be replaced in the destination buffer.
SPI Programming in TACL #SSMOVE an extensible structured token, or a list token. If a list token is specified, the list token, its associated end-list token, and all tokens in between are moved. Expansion #SSMOVE expands to a numeric status code indicating the outcome of the operation. If the status code is 0 (no error), it is followed by a space and the number of token values or lists moved.
SPI Programming in TACL Interprocess Communication Interprocess Communication An application requester written in TACL should open the management process for each subsystem using the READ option of #REQUESTER, and should use #APPENDV and #EXTRACTV to send commands and decode responses. If you are writing a subsystem, it is recommended that you run TACL specifying its IN and OUT files as $RECEIVE, and then use an #INPUTV/#REPLYV loop protected by a suitable exception handler.
SPI Programming in TACL Example: Printing or Displaying the Status Structure of the Subsystem Control Point (SCP) Example 8-1. Printing or Displaying the Status Structure of the SCP (page 1 of 2) ?TACL MACRO == SCPSTAT == Display SCP’s status structure.
SPI Programming in TACL Example: Printing or Displaying the Status Structure of the Subsystem Control Point (SCP) Example 8-1. Printing or Displaying the Status Structure of the SCP (page 2 of 2) == Reset the buffer after receiving the response. #SET err [#SSPUT spi_buf ZSPI^TKN^RESET^BUFFER ZCOM^VAL^BUFLEN] [#IF err |THEN| *** ERROR [err] from #SSPUT RESET^BUFFER] == Retrieve the return code and test its value.
9 SPI Programming in TAL This section provides language-specific information for the programmer who is using the TAL to write an SPI requester or server: Topic Page Definition Names in TAL 9-1 TAL Definition Files 9-1 Declarations Needed in TAL Programs 9-1 Interprocess Communication 9-3 SPI Procedure Syntax in TAL 9-3 Examples 9-5 Definition Names in TAL Symbolic names in this section are in the TAL form, using circumflex (^) symbols rather than hyphens.
SPI Programming in TAL Subsystem ID structure described in “SPI Buffer” in Section 4. Use this declaration to allocate a buffer variable of the recommended size (subsys^VAL^BUFLEN): STRUCT .buf(subsys^DDL^MSG^BUFFER^DEF); Then you can easily refer to the Z^MSGCODE (-28), Z^BUFLEN, and Z^OCCURS fields of this structure as needed. Some subsystems provide additional buffer declarations allocating different recommended buffer-size values for different commands.
SPI Programming in TAL Interprocess Communication Your TAL module must include this source directive and declaration: ?SOURCE subsysTAL . . INT .user^chosen [0:subsys^MAP^name^WLN-1] := subsys^MAP^name ; This code declares user^chosen and initializes it with the proper value for the token map. Then you can refer to user^chosen as the token code in SPI calls such as SSPUT and SSGET to operate on subsys-MAP-name tokens.
SPI Programming in TAL SSINIT SSINIT { status := } { CALL } SSINIT ( , , , , , , , , , buffer buffer-length ssid header-type command [ object-type [ max-resp [ server-version [ checksum [ max-field-version ] ] ] ] ] ! o ! i ! i ! i ! i ! i ! i ! i ! i ) ; ! i SSNULL { status := } { CALL } SSNULL ( token-map , struct ) ; ! i ! o SSPUT and SSPUTTKN The SSPUT and SSPUTTKN procedures are identical except for the type of the token-id parameter (SSPUT passes token-id by reference and SSPUTTKN passes i
SPI Programming in TAL { status := } { CALL } SSMOVE and SSMOVETKN { SSGET } { SSGETTKN } ( , , , , , buffer token-id [ token-value ] [ index ] [ count ] [ ssid ] ) ; ! ! ! ! ! ! i/o i i/o i i/o i/o SSMOVE and SSMOVETKN The SSMOVE and SSMOVETKN procedures are identical except for the type of the token-id parameter (SSMOVE passes token-id by reference and SSMOVETKN passes it by value) and the consequent fact that SSMOVETKN cannot be used with a token map.
SPI Programming in TAL Examples SPI Programming Manual—427506-006 9 -6
A Errors This appendix lists all the error numbers defined by SPI. The two categories of errors are: • • Error numbers returned in the status parameter on calls to the SPI procedures (errors 0 through –12) General errors returned in SPI messages (errors –13 through –37) The ZSPI errors are listed by number in Table A-1 and by name in Table A-2. When any of these errors (except error 0 or error –1) occurs, the header token ZSPI-TKNLASTERR is set to the error number. Table A-1.
Errors Table A-1.
Errors 0: ZSPI-ERR-OK Table A-2.
Errors –2: ZSPI-ERR-ILLPARM • • • The length of the used portion of the buffer (ZSPI-TKN-USEDLEN) is greater than the maximum buffer length (Z-BUFLEN). SSPUT might have been called with ZSPI-TKN-RESET-BUFFER and a maxlen value that was smaller than ZSPITKN-USEDLEN. The buffer contains ZSPI-TKN-ENDLIST but no corresponding list token. The position descriptor within the buffer (ZSPI-TKN-POSITION) indicates a current list that does not begin with a list token.
Errors –4: ZSPI-ERR-BADADDR with ZSPI-TKN-NEXTCODE or ZSPI-TKN-NEXTTOKEN unless you are certain that all tokens the program could encounter are qualified by the default subsystem ID. • The value parameter is required when calling SSGET with certain standard token codes (such as ZSPI-TKN-LEN and ZSPI-TKN-OFFSET) or when calling SSPUT with a token code that has a value (a nonzero token length). Effect.
Errors –6: ZSPI-ERR-XSUMERR –6: ZSPI-ERR-XSUMERR Cause. The current buffer checksum does not match the checksum computed on return from the last SPI call. This error suggests that the buffer has been modified or damaged. Effect. The last error is set to this error number, and the requested operation is not completed. Recovery. Using a debugging tool such as Inspect, check for inadvertent corruption of the buffer contents. –7: ZSPI-ERR-INTERR Cause.
Errors –9: ZSPI-ERR-ILLTKN –9: ZSPI-ERR-ILLTKN Cause. An invalid token code or token map was supplied in the procedure call. The possibilities include: • • • • • The token data type was not recognized. For example, a program used a token data type not included in the SPI standard definitions. (The only token data types permitted by SPI are those defined by SPI.) The token length was not a multiple of the basic length associated with the token data type.
Errors –12: ZSPI-ERR-NOSTACK Recovery. Check that the token code being supplied in the call is defined for the version of the SPI definitions being used. –12: ZSPI-ERR-NOSTACK Cause. An SPI procedure was called with fewer than 768 words of data stack left. Effect. The last error is set to this error number, and the requested operation is not completed. Recovery. Increase the number of stack pages available or reduce the amount of stack space used.
B Summary of DDL for SPI This appendix reviews features of DDL that pertain to SPI data definitions. If you are not familiar with DDL, this information will help you read and understand the DDL source code in this and other related manuals.
Summary of DDL for SPI General Language Rules for DDL You can make the information in the DDL definition file available to the system procedures that derive display text from SPI messages. The DDL information helps the EMSTEXT procedure and the SPI_BUFFER_FORMAT procedures produce more readable display text. EMSTEXT presents event messages to operators. The SPI_BUFFER_FORMAT procedures help Inspect to display SPI messages.
Summary of DDL for SPI TYPE Clause Figure B-1. DEF Statement Examples 1 def ZSPI-DDL-BOOLEAN 2 def ZSPI-DDL-ENUM 3 def 4 type pic s9(4) logical comp spi-null spi-null tacl " ". 255 enum . ZFUP-DDL-PART-RENAME-OPTS . 02 Z-PART-ONLY type ZSPI-DDL-INT . 02 Z-PART-NAME type ZSPI-DDL-DEVICE . 02 Z-PRIEXT-SIZE type ZSPI-DDL-INT2 spi-null 02 Z-SECEXT-SIZE type ZSPI-DDL-INT2 spi-null end . ZSPI-DDL-CHAR5 02 Z-C 02 Z-S redefines Z-C . 03 Z-I 03 filler 02 Z-B redefines Z-C end . 255 . 255 .
Summary of DDL for SPI PICTURE (PIC) Clause In DDL source code, a DEF statement referred to in a TYPE clause must precede the DEF statement that refers to it. In manuals, likewise, DEF statements are usually presented so that each DEF precedes all the DEFs that refer to it. Subsystem DEFs referred to by other subsystem DEFs usually appear in the “Common Definitions” section of the appropriate subsystem management programming manual.
Summary of DDL for SPI FILLER Clause FILLER Clause A clause beginning with the keyword FILLER specifies an unnamed place-holder field. The definition files include FILLER clauses where needed to ensure alignment of adjacent fields on word boundaries. Example 4 in Figure B-1 illustrates the use of the FILLER clause.
Summary of DDL for SPI HEADING Clause HEADING Clause This clause provides the SPI_BUFFER_FORMAT procedures and Inspect with information they need to label a token or field value when displaying the contents of an SPI message. DISPLAY Clause This clause provides the edit code that is used when a token or field value is represented in display text. Include this clause when the DISPLAY clause might make the value more readable or when the default edit code is not suitable for the token or field.
Summary of DDL for SPI DDL Data Translation This notation is not DDL code, but is a shortened notation designed to give the information needed. For instance, the example above reflects this TOKEN-CODE statement in the definition file ZSPIDEF.ZSPIDDL: TOKEN-CODE zspi-tkn-context VALUE IS zspi-tnm-context TOKEN-TYPE IS zspi-typ-bytestring. DDL Data Translation The DDL compiler can translate any DEF statement into data-declaration source code in TAL, C, COBOL, or TACL.
Summary of DDL for SPI DDL Data Translation SPI Programming Manual—427506-006 B- 8
C SPI Internal Structures This appendix describes these internal formats of SPI data structures: Topic Page SPI Buffer Format C-1 Token Structure C-5 Token-Map Structure C-7 List Structure C-10 The detailed formats are expressed as TAL structures. This information is for debugging purposes only. Note. The information in this appendix might change in future RVUs. Application programs and subsystems you write should not depend on these formats.
SPI Internal Structures Standard Part of Header not implemented as true tokens—they are identified in the buffer by their positions rather than by their token codes. However, application programs and subsystems you write retrieve and change the values of header tokens using SSGET and SSPUT as if they were true tokens. Standard Part of Header The first data structure in the buffer contains the standard part of the header. This structure contains information that is common to all SPI buffers.
SPI Internal Structures Specialized Part of Header Specialized Part of Header The standard part of the header is followed by the specialized part, a structure that differs depending on the header type. To users of the SPI procedures, the header type is a header token with an unsigned integer value of either 0 for a standard command header, or 1 for an event-message header. Internally, the header type is identified by a token code that appears in the first two words of the specialized part.
SPI Internal Structures Context Part of Header STRING ZGROUP; STRING ZUSER; INT ZUSERGROUP = ZGROUP; END; INT ZSYSTEM; STRUCT ZCRTPID; BEGIN INT ZNAME [0:2]; STRING ZCPU, ZPIN; END; INT ZFLAGS; ! Console print, emphasis END; For more information about event messages, see the EMS Manual. Context Part of Header This structure, if present, follows the specialized part and contains context information used by SSGET and SSPUT, including position descriptors and SPI error information.
SPI Internal Structures Token Structure Token Structure A token consists of a token code (qualified by a subsystem ID) and a token value. Token Code The token code is stored in either a simple format (when qualified by the default subsystem ID), or an extended format (when qualified by a subsystem ID other than the default). Figure C-2. Internal Format of Token Code Simple Format 0 Type Length Number Extended Format 1 Type Length Number Subsystem ID VST024.
SPI Internal Structures Single-Occurrence Tokens 255, then the first word of the value gives the (noninclusive) length in bytes of the rest of the value. Single-Occurrence Tokens Single occurrences of token codes and token values are stored contiguously in the SPI buffer (see Figure C-3). A padding byte is emitted where necessary so that each token code begins on a word boundary. Figure C-3. Single-Occurrence Tokens as Stored in the Buffer Token Code Value Token Code Value ... VST025.
SPI Internal Structures Token-Map Structure UNSIGNED(1) Z^EXTENDED; ! ! ! ! ! True if extendedformat token code Token data type Token length Token number UNSIGNED(7) Z^DATATYPE; UNSIGNED(8) Z^BYTELEN; INT Z^NUMBER; END; STRUCT Z^TKN^SSID; ! Optional subsystem ID BEGIN INT Z^SSOWNER[0:3]; INT Z^SSNUM; INT Z^SSVERSION; END; END; END; This table header is followed by Z^TBL^COUNT values of the type associated with Z^TBL^TKN. (See Figure C-4 on page C-6.
SPI Internal Structures • • Token-Map Example One or more null-value specifications As new fields are added, additional version specifications for the new fields In more detail, a token map can be seen as a token-map header followed by one or more null-value specifications and zero or more version specifications. Figure C-6 shows the formats of the token-map header, a null-value specification, and a version specification. Figure C-6.
SPI Internal Structures CONSTANT Token-Map Example zbat-tnm-jobinfo VALUE IS 63. TOKEN-MAP zbat-map-jobinfo VALUE IS zbat-tnm-jobinfo DEF IS zbat-ddl-jobinfo. VERSION "C00" FOR znumber THROUGH zlocation.
SPI Internal Structures List Structure TOKEN-MAP zbat-map-jobinfo VERSION "C00" VERSION "C10" NOVERSION VERSION "C10" FOR FOR FOR FOR VALUE IS zbat-tnm-jobinfo DEF IS zbat-ddl-jobinfo. znumber THROUGH zlocation. zuserid-is-present. zuserid. zjobclass.
SPI Internal Structures List Structure Figure C-7. Structure of a List in the Buffer List Token Code Length 1st Token nth Token ---------- ---------- Length End-List Token VST029.vsd When stored in the buffer, the token-number portion of the ZSPI-TKN-ENDLIST token is replaced with the length of the list. This is used for a boundary-tag consistency check.
SPI Internal Structures List Structure SPI Programming Manual—427506-006 C-12
D NonStop Kernel Subsystem Numbers and Abbreviations This appendix lists the NonStop Kernel subsystem numbers and abbreviations. Table D-1 lists the subsystem numbers, abbreviations, and mnemonics assigned to NonStop Kernel subsystems. The integer numbers themselves are provided for debugging purposes. Under normal circumstances, you should refer to a subsystem number by its symbolic name, which has the form ZSPI-SSN-ssss.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-1.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-1.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-1.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-1.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-1. NonStop Kernel Subsystem Numbers (page 6 of 11) Subsystem Number Subsystem Abbreviation 115 ZT21 IBM node type 2.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-1.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-1.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-1.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-1.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-1.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-2.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-2. NonStop Kernel Subsystem Abbreviations (page 2 of 9) Subsystem Abbreviation Subsystem Number Mnemonic Description ZCMS 70 CMS Configuration Management System ZCOM 21 ZCOM SPI common extensions definitions ZCP6 26 ZCPS 266 CPS Matrix SMLC CCB 4.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-2.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-2.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-2.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-2.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-2.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-2.
NonStop Kernel Subsystem Numbers and Abbreviations Table D-2. NonStop Kernel Subsystem Abbreviations (page 9 of 9) Subsystem Abbreviation Subsystem Number Mnemonic Description ZWAN 176 WAN Wide Area Network subsystem ZWEB 210 WEB WebServer ZWMS 165 WMS Workload Measurement System ZWVP 257 WVPT Web ViewPoint ZX25 41 X25 X.
E SPI Programming Examples This appendix lists the TAL source code and C source code for six programs that demonstrate basic SPI concepts and programming techniques. In addition to these twelve working example programs, there are eight supporting files (four in TAL and four in C), one TACL command file for compiling the TAL programs, and one TACL command file for compiling the C programs.
SPI Programming Examples Example Description Source File Page E-10 The C program equivalent of Example E-9 SECREQRC E-36 E-11 A simple SPI server that responds to commands from the requester in Example E-7. This example demonstrates fundamental SPI server activities.
SPI Programming Examples Compiling the Example Programs Compiling the Example Programs Compiling the TAL Programs 1. Set your default subvolume to the subvolume that contains the example source files. (If you plan to modify the programs for experimentation, copy the source files from the distribution subvolume to a working subvolume.) 2.
SPI Programming Examples Running the C Programs Running the C Programs The SECBUILD macro creates six runnable object files: Example Object File E-2 SEC0204O E-4 SEC0205O E-6 SEC0206O E-8 SEC0207O E-10 SECREQRO SECSERVO∗ E-12 ∗ Run automatically by SECREQO, the requester from E-10. Choose from the first five programs. A Note on Program Output The example programs use DSM Template Services formatting procedures to display the contents of SPI buffers.
SPI Programming Examples Example E-1: Basic Buffer Manipulations in TAL Example E-1. TAL File: Basic Buffer Manipulations (page 1 of 2) -File name: SET0204 -SPI EXAMPLE TAL 2-4 -Figure 2-4. Pointer Manipulation ?SYMBOLS, INSPECT LITERAL max^bufsize = 256; ! in bytes ?SOURCE SETCDECS ?NOLIST, SOURCE $system.system.
SPI Programming Examples Example E-1: Basic Buffer Manipulations in TAL Example E-1.
SPI Programming Examples Example E-2: Basic Buffer Manipulations in C Example E-2: Basic Buffer Manipulations in C The C source file in Example E-2 demonstrates the basic buffer manipulation activities illustrated in Figure 2-4 on page 2-18. The program uses DSM Template Services to display the contents of the buffer after each manipulation. Run the program to see the effect of SPI procedure calls on the contents of the buffer and the locations of the buffer pointers.
SPI Programming Examples Example E-2: Basic Buffer Manipulations in C Example E-2.
SPI Programming Examples Example E-3: Working With Lists in TAL Example E-3: Working With Lists in TAL Example E-3 on page E-10 demonstrates the basic buffer manipulation activities illustrated in Figure 2-5 on page 2-22. The TAL program uses DSM Template Services to display the contents of the buffer after each manipulation. Run the program to see SPI procedure calls used to move in and out of an SPI list.
SPI Programming Examples Example E-3: Working With Lists in TAL Example E-3. TAL File: Working With Lists (page 1 of 3) -File name: SET0205 -SPI EXAMPLE TAL 2-5 -Figure 2-5. Pointer Manipulation and lists ?SYMBOLS, INSPECT LITERAL max^bufsize = 256; ! in bytes ?SOURCE SETCDECS ?NOLIST, SOURCE $system.system.
SPI Programming Examples Example E-3: Working With Lists in TAL Example E-3.
SPI Programming Examples Example E-4: Working With Lists in C Example E-3.
SPI Programming Examples Example E-4: Working With Lists in C Example E-4. C File: Working With Lists (page 1 of 2) /* File name: sec0205c * SPI EXAMPLE C 2-5 * Figure 2-5. Pointer Manipulation and lists */ #pragma symbols #pragma inspect #pragma nomap #pragma nolmap #define max_bufsize 256 /* in bytes */ #include "secc.
SPI Programming Examples Example E-4: Working With Lists in C Example E-4.
SPI Programming Examples Example E-5: Displaying SPI Buffer Contents With TAL Example E-5: Displaying SPI Buffer Contents With TAL Example E-5 demonstrates the basic buffer manipulation activities illustrated in Figure 2-6 on page 2-24. This TAL program uses DSM Template Services to display the contents of the buffer after each manipulation. Run the program to see the behavior of the SSGET special operation ZSPI-TKN-NEXTTOKEN. Source File SET0206 Object File SET0206O Example E-5.
SPI Programming Examples Example E-5: Displaying SPI Buffer Contents With TAL Example E-5.
SPI Programming Examples Example E-5: Displaying SPI Buffer Contents With TAL Example E-5.
SPI Programming Examples Example E-6: Displaying SPI Buffer Contents With C Example E-6: Displaying SPI Buffer Contents With C Example E-6 on page E-19 demonstrates the basic buffer manipulation activities illustrated in Figure 2-6 on page 2-24. This C program uses DSM Template Services to display the contents of the buffer after each manipulation. Run the program to see the behavior of the SSGET special operation ZSPI-TKN-NEXTTOKEN.
SPI Programming Examples Example E-6: Displaying SPI Buffer Contents With C Example E-6. C File: Pointers, Lists, and ZSPI-TKN-NEXTTOKEN (page 1 of 3) /* File name: sec0206c * SPI EXAMPLE C 2-6 * Figure 2-6. Pointer Manipulation and lists */ #pragma symbols #pragma inspect #pragma nomap #pragma nolmap #define max_bufsize 256 /* in bytes */ #include "secc.
SPI Programming Examples Example E-6: Displaying SPI Buffer Contents With C Example E-6.
SPI Programming Examples Example E-7: Special SSGET Operation in TAL Example E-6.
SPI Programming Examples Example E-7: Special SSGET Operation in TAL Example E-7. TAL File: Pointers, Lists, and ZSPI-TKN-NEXTCODE (page 1 of 3) -File name: SET0207 -SPI EXAMPLE TAL 2-7 -Figure 2-7. Pointer Manipulation and lists ?SYMBOLS, INSPECT LITERAL max^bufsize = 256; ! in bytes ?SOURCE SETCDECS ?NOLIST, SOURCE $system.system.
SPI Programming Examples Example E-7: Special SSGET Operation in TAL Example E-7.
SPI Programming Examples Example E-8: Special SSGET Operation in C Example E-7.
SPI Programming Examples Example E-8: Special SSGET Operation in C Example E-8. C File: Pointers, Lists, and ZSPI-TKN-NEXTCODE (page 1 of 3) /* File name: sec0207c * SPI EXAMPLE C 2-7 * Figure 2-7. Pointer Manipulation and lists */ #pragma symbols #pragma inspect #pragma nomap #pragma nolmap #define max_bufsize 256 /* in bytes */ #include "secc.
SPI Programming Examples Example E-8: Special SSGET Operation in C Example E-8.
SPI Programming Examples Example E-9: A Simple SPI Requester in TAL Example E-8.
SPI Programming Examples Example E-9: A Simple SPI Requester in TAL Example E-9. TAL File: A Simple SPI Requester (page 1 of 8) -File name: SETREQR -SPI EXAMPLE TAL Basic Requester model.
SPI Programming Examples Example E-9: A Simple SPI Requester in TAL Example E-9. TAL File: A Simple SPI Requester (page 2 of 8) PROC get^string (p^buffer, p^count^read); STRING .p^buffer; INT .
SPI Programming Examples Example E-9: A Simple SPI Requester in TAL Example E-9. TAL File: A Simple SPI Requester (page 3 of 8) 4 -> display^spi^buffer := true; 5 -> display^spi^buffer := false; 6 -> sline ':=' " " -> @sp; CALL writex (term, sline, @sp '-' @sline); CALL stop (process^id); ! Stop the server. CALL stop; OTHERWISE -> sline ':=' " " -> @sp; CALL writex (term, sline, @sp '-' @sline); sline ':=' "Invalid option. Try again.
SPI Programming Examples Example E-9: A Simple SPI Requester in TAL Example E-9. TAL File: A Simple SPI Requester (page 4 of 8) ! Put in the current volume/subvolume. server^name ':=' start^buffer.default FOR 8 WORDS; ! Parse parameters for 'debug' debug^flag := false; SCAN start^buffer.
SPI Programming Examples Example E-9: A Simple SPI Requester in TAL Example E-9.
SPI Programming Examples Example E-9: A Simple SPI Requester in TAL Example E-9.
SPI Programming Examples Example E-9: A Simple SPI Requester in TAL Example E-9. TAL File: A Simple SPI Requester (page 7 of 8) END; CALL writex (term, sline, @sp '-' @sline); WHILE 1=1 DO ! Do forever BEGIN CALL get^string (in^string.data, in^string.
SPI Programming Examples Example E-9: A Simple SPI Requester in TAL Example E-9. TAL File: A Simple SPI Requester (page 8 of 8) IF tkn^retcode THEN BEGIN sline ':=' "Error returned.
SPI Programming Examples Example E-10: A Simple SPI Requester in C Example E-10: A Simple SPI Requester in C Example E-10 on page E-37 is a simple SPI requester that sends commands to the server shown in Example E-11 on page E-45. The requester starts and stops the server automatically. The requester's commands have the server perform simple string manipulations on a text string that you enter.
SPI Programming Examples Example E-10: A Simple SPI Requester in C Example E-10. C File: A Simple SPI Requester (page 1 of 8) /* File name: secreqrc * SPI EXAMPLE C Basic Requester model. */ #pragma symbols #pragma inspect #pragma nomap #pragma nolmap #define max_bufsize #define version 560 /* in bytes */ 0x4414u /* Set to the value: "D20" */ #include "secc.h" #include "secr.
SPI Programming Examples Example E-10: A Simple SPI Requester in C Example E-10. C File: A Simple SPI Requester (page 2 of 8) /* *======================================================================== * Proc : get_string = * Function : This procedure will prompt the home term for the function = * and the string data on which to perform the function.
SPI Programming Examples Example E-10: A Simple SPI Requester in C Example E-10. C File: A Simple SPI Requester (page 3 of 8) case '4': display_spi_buffer = true; break; case '5': display_spi_buffer = false; break; case '6': printf (" \n"); STOP(process_id); STOP(); break; /* Stop the server. */ default: printf (" \n"); printf ("Invalid option. Try again.
SPI Programming Examples Example E-10: A Simple SPI Requester in C Example E-10. C File: A Simple SPI Requester (page 4 of 8) #pragma PAGE "open_server" /* *=================================================================== * Proc : open_server = * Function : This procedure will open the server.
SPI Programming Examples Example E-10: A Simple SPI Requester in C Example E-10.
SPI Programming Examples Example E-10: A Simple SPI Requester in C Example E-10.
SPI Programming Examples Example E-10: A Simple SPI Requester in C Example E-10. C File: A Simple SPI Requester (page 7 of 8) write_read_server (); if (display_spi_buffer) { printf ("SPI buffer received:\n"); dump_buf (req_buffer); } /* Reset the buffer */ buflen = max_bufsize; if (err = SSPUTTKN (req_buffer, ZSPI_TKN_RESET_BUFFER, (char *) &buflen)) { display_spi_error (err, ZSPI_VAL_SSPUTTKN, ZSPI_TKN_RESET_BUFFER, false); printf ("Bad SPI buffer returned! Cannot reset the buffer.
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-10. C File: A Simple SPI Requester (page 8 of 8) memcpy (req_buffer, sav_buffer, max_bufsize); /* Now delete the context token from the saved buffer. */ tkn_code = ZSPI_TKN_CONTEXT; if (err = SSPUTTKN (sav_buffer, ZSPI_TKN_DELETE, (char *) &tkn_code)) display_spi_error (err, ZSPI_VAL_SSPUTTKN, tkn_code, true); goto SEND_IT; } /* No context.
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-11. TAL File: A Simple SPI Server (page 1 of 10) -File name: SETSERV -SPI EXAMPLE TAL Basic Server model.
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-11. TAL File: A Simple SPI Server (page 2 of 10) ?SOURCE SETCUTIL ?PAGE "PROC build^hdr^response" PROC build^hdr^response; !=======================================================================! ! Proc : build^hdr^response ! ! Function : This procedure will build the header for responses.
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-11. TAL File: A Simple SPI Server (page 3 of 10) ! Put error list token IF err := ssputtkn (res^buffer, zspi^tkn^errlist) THEN BEGIN CALL display^spi^error (err, zspi^val^ssputtkn, zspi^tkn^errlist, false); RETURN; END; l^err^def.z^ssid ':=' my^ssid FOR 12 BYTES; l^err^def.
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-11.
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-11. TAL File: A Simple SPI Server (page 5 of 10) ! Start Data list only IF zspi^tkn^maxresp is not = 0 IF max^resp THEN BEGIN IF err := ssputtkn (res^buffer, zspi^tkn^datalist) THEN CALL display^spi^error (err, zspi^val^ssputtkn, zspi^tkn^datalist, true); END; l^start^idx := 0; ! Check for CONTEXT token. IF context^count THEN BEGIN ! Here the CONTEXT token was sent. Copy the passed context. out^string.len := the^context.
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-11. TAL File: A Simple SPI Server (page 6 of 10) IF out^string.len < in^string.len THEN BEGIN ! update the context and add it to the returned buffer. the^context.command := spi^command; the^context.index := l^start^idx; the^context.con^string.len := out^string.len; the^context.con^string.data ':=' out^string.data FOR out^string.len BYTES; the^context.len := $offset (context^template.con^string) + out^string.
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-11. TAL File: A Simple SPI Server (page 7 of 10) PROC process^requests; BEGIN ! Read in the spi^command received CALL readupdatex (rcv^file^num, req^buffer, max^bufsize, spi^buffer^size); CALL fileinfo (rcv^file^num, last^file^err); CASE (last^file^err) OF ! data was found in the buffer BEGIN 6 -> ! system message ! first word of req^buffer is message type.
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-11. TAL File: A Simple SPI Server (page 8 of 10) INT PROC validate^tokens; BEGIN STRUCT .
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-11. TAL File: A Simple SPI Server (page 9 of 10) tkn^code := zspi^tkn^context; context^count := context^count + tkn^count; IF context^count <> 1 THEN BEGIN RETURN (zcom^err^tkn^dup); END ELSE BEGIN ! retrieve and validate the context IF err := ssgettkn (req^buffer, zspi^tkn^context, the^context) THEN CALL display^spi^error (err, zspi^val^ssgettkn, zspi^tkn^context, true); IF (the^context.
SPI Programming Examples Example E-11: A Simple SPI Server in TAL Example E-11.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12: A Simple SPI Server in C Example E-12 is a simple SPI server that performs simple string manipulations on strings provided by the requester shown in Example E-9 on page E-28. The server is started automatically when you run the requester, SECREQRO. Source File SECSERVC Object File SECSERVO Example E-12. C File: A Simple SPI Server (page 1 of 12) /* File name: secservc * SPI EXAMPLE C Basic Server model.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12. C File: A Simple SPI Server (page 2 of 12) void process_spi_buffer(void); void process_requests(void); short validate_tokens(void); short verify_msg (short p_count); #include "seccutlc" #pragma PAGE "PROC build_hdr_response" void build_hdr_response(void) /* *======================================================================== * Proc : build_hdr_response = * Function : This procedure will build the header for responses.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12. C File: A Simple SPI Server (page 4 of 12) /* *======================================================================= * Proc : initialization = * Function : This procedure will open $RECEIVE. It also sets the = * server_banner. = *======================================================================= */ void initialization(void) { char l_filename [24]; short l_err; short l_status; memset (&server_banner.u_z_c.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12. C File: A Simple SPI Server (page 6 of 12) case 1 : /* string to reverse. */ l_len = in_string.len; for (l_idx = l_start_idx; l_idx < l_len; l_idx++) { out_string.data [l_len - l_idx - 1] = in_string.data [l_idx]; } out_string.len = in_string.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12. C File: A Simple SPI Server (page 7 of 12) /* * Here I have the option to add the work that has been done to * returned buffer. This depends on the function being performed. * I will add it here just for illustration purposes. */ if (err = SSPUTTKN (res_buffer, ZSPI_TKN_COMMENT, (char *) &out_string)) display_spi_error (err, ZSPI_VAL_SSPUTTKN, ZSPI_TKN_COMMENT, true); break; case 3 : /* Shift string to lowercase */ out_string.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12. C File: A Simple SPI Server (page 8 of 12) #pragma PAGE "PROC process_requests" /* *================================================================== * Proc : process_requests = * Function : This procedure will process the requests received = * on $RECEIVE.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12. C File: A Simple SPI Server (page 9 of 12) #pragma PAGE "validate_tokens" /* *===================================================================== * Proc : validate_tokens = * Function : This procedure will determine if the "req_buffer" = * contains a valid SPI command. All required tokens = * must be present.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12. C File: A Simple SPI Server (page 10 of 12) /* walk through the buffer pulling out tokens */ while (err = SSGETTKN (req_buffer, ZSPI_TKN_NEXTCODE, (char *) &tkn_code,, &tkn_count) == ZSPI_ERR_OK) { switch { case /* if (tkn_code) ZSPI_TKN_COMMENT : Check the entire token code, just to be sure.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12. C File: A Simple SPI Server (page 11 of 12) #pragma PAGE "verify_msg" /* *======================================================================== * Proc : verify_msg = * Function : This procedure will determine if a valid SPI buffer was = * received. = * Returns : An error code indicating the error found, = * or ZSPI_ERR_OK (0) which indicates no error was found.
SPI Programming Examples Example E-12: A Simple SPI Server in C Example E-12. C File: A Simple SPI Server (page 12 of 12) #pragma PAGE "PROC server MAIN" /* *====================================================================== * MAINLINE ROUTINE STARTS HERE.
SPI Programming Examples Example E-13: Common Declarations for TAL Examples Example E-13: Common Declarations for TAL Examples This TAL code contains common declarations used by the other TAL example programs. Source File SETCDECS Example E-13. TAL File: SETDECS Supporting Code ?SYMBOLS, INSPECT, NOCODE, NOMAP, NOLMAP, DATAPAGES 64 ?NOLIST, SOURCE ZSPITAL ?LIST --File name: SETCDECS -SPI EXAMPLE TAL Common Declarations and variables.
SPI Programming Examples Example E-14: Common Declarations for C Examples Example E-14: Common Declarations for C Examples This C code contains common declarations used by the other C example programs. Source File SECCH Example E-14. C File: SECCH Supporting Code #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include nolist #include
SPI Programming Examples Example E-15: Common Routines for TAL Examples Example E-15: Common Routines for TAL Examples This TAL code contains common routines used by the other TAL example programs. Source File SETCUTIL Example E-15. TAL File: SETCUTIL Supporting Code (page 1 of 5) -File name: SETCUTIL -SPI EXAMPLE TAL Common Utility procedures.
SPI Programming Examples Example E-15: Common Routines for TAL Examples Example E-15.
SPI Programming Examples Example E-15: Common Routines for TAL Examples Example E-15. TAL File: SETCUTIL Supporting Code (page 3 of 5) ?PAGE "PROC display^token" !======================================================================! ! Proc : display^token ! ! Function : This procedure will add the token name of the passed ! ! token code to the current position pointer to by "sp". ! ! Nothing is written to the home term.
SPI Programming Examples Example E-15: Common Routines for TAL Examples Example E-15.
SPI Programming Examples Example E-16: Common Routines for C Examples Example E-15. TAL File: SETCUTIL Supporting Code (page 5 of 5) USE l^idx2; IF err = 0 OR err = zspi^err^continue THEN BEGIN l^idx2 := 0; FOR l^idx2 := 0 TO max^lines - 1 DO BEGIN IF l^lengths [l^idx2] > -1 THEN BEGIN CALL writex (term, l^sformat^buf [l^idx2 * max^line^len], l^lengths [l^idx2]); END; -- of IF l^lengths [l^idx2] > -1 END; -- of FOR l^idx2 := 0 to max^lines - 1 DO END ELSE -- IF err = 0 OR err ...
SPI Programming Examples Example E-16: Common Routines for C Examples Example E-16. C File: SECCUTLC Supporting Code (page 1 of 5) /* File name: seccutlc ** SPI EXAMPLE C Common Utility procedures.
SPI Programming Examples Example E-16: Common Routines for C Examples Example E-16.
SPI Programming Examples Example E-16: Common Routines for C Examples Example E-16.
SPI Programming Examples Example E-16: Common Routines for C Examples Example E-16. C File: SECCUTLC Supporting Code (page 4 of 5) #pragma PAGE "dump_buf" void dump_buf (short* p_spi_buf) /* =========================================================================== == Proc : dump_buf = == Function : This procedure will perform a labeled dump of the passed = == SPI buffer and display it on the home term.
SPI Programming Examples Example E-16: Common Routines for C Examples Example E-16.
SPI Programming Examples Example E-17: Declarations for TAL Requesters and Servers Example E-17: Declarations for TAL Requesters and Servers This TAL code contains common declarations used by the TAL requester and server example programs.
SPI Programming Examples Example E-17: Declarations for TAL Requesters and Servers Example E-17. TAL File: SETRDECS Supporting Code -File name: SETRDECS -SPI EXAMPLE TAL Requester Declarations and variables.
SPI Programming Examples Example E-18: Declarations for C Requesters and Servers Example E-18: Declarations for C Requesters and Servers This C code contains common declarations used by the C requester and server example programs. Source File SECRH Example E-18. C File: SECRH Supporting Code /* ** */ File name: secrh SPI EXAMPLE C Requester Declarations and variables.
SPI Programming Examples Example E-19: Routines for TAL Requesters and Servers Example E-19: Routines for TAL Requesters and Servers This TAL code contains common routines used by the TAL requester and server example programs. Source File SETRUTIL Example E-19. TAL File: SETRUTIL Supporting Code (page 1 of 4) -File name: SETRUTIL -SPI EXAMPLE TAL Requester Utility procedures.
SPI Programming Examples Example E-19: Routines for TAL Requesters and Servers Example E-19.
SPI Programming Examples Example E-19: Routines for TAL Requesters and Servers Example E-19. TAL File: SETRUTIL Supporting Code (page 3 of 4) ! ! If debug^flag is set, then bring up the server in DEBUG. ! l^process^flags.<15> := debug^flag; l^priority.
SPI Programming Examples Example E-20: Routines for C Requesters and Servers Example E-19. TAL File: SETRUTIL Supporting Code (page 4 of 4) BEGIN l^await^done := true; server^up := false; l^recoverable^err := false; ! Set default value IF file^error = 201 THEN l^recoverable^err := true; IF file^error = 211 THEN l^recoverable^err := true; IF file^error = 6 THEN ! System message BEGIN start^buffer ':=' req^buffer FOR read^count BYTES; IF start^buffer.
SPI Programming Examples Example E-20: Routines for C Requesters and Servers Example E-20. C File: SECRUTLC Supporting Code (page 1 of 4) /* File name: secrutlc * SPI EXAMPLE C Requester Utility procedures. */ #pragma PAGE "report_newprocess_error" /* *======================================================================== * Proc : report_newprocess_error = * Function : This procedure will format a NEWPROCESS error and write = * it to the home term.
SPI Programming Examples Example E-20: Routines for C Requesters and Servers Example E-20.
SPI Programming Examples Example E-20: Routines for C Requesters and Servers Example E-20. C File: SECRUTLC Supporting Code (page 3 of 4) /* * If debug_flag is set, then bring up the server in DEBUG.
SPI Programming Examples Example E-20: Routines for C Requesters and Servers Example E-20.
SPI Programming Examples Example E-21: TAL Examples Compiler Example E-21: TAL Examples Compiler The TACL command file in Example E-21 compiles the TAL example programs. Modify the two file assignments to specify the location of the SPI definition files on your node. ($SYSTEM.SPIDEF is the default.) Source File SETBUILD Example E-21. TACL Command File to Compile TAL Program Examples comment This TACL obey file will compile all of the SPI Example (TAL) files.
Glossary attribute. A characteristic of an object. For example, two attributes of a DNS alias are an alias type and domain. Two attributes of a communications line might be its baud rate and its retry count. In SPI messages, an attribute of an object is usually expressed as a simple token or a field within an extensible structured token. Tokens themselves have attributes: length, count, address, and offset. Programs can retrieve these through special SSGET operations. buffer.
Glossary context token subsystem in a new command message so that the subsystem can continue processing. See context token. context token. A token that indicates (by its presence or absence) whether or not a subsystem has more objects to process or more response messages to return. If this token is present in a response message, the response is incomplete and can be continued in another response message. To obtain the next message, the requester reissues the original command with the context token.
Glossary definition files definition files. A set of files containing data declarations for items related to SPI messages and their processing. The core definitions required to use SPI are provided in a DDL file and in several language-specific definition files, one for each programming language that supports SPI. The DDL compiler generates the language-specific files from the DDL file. Subsystems that support SPI provide additional definition files containing subsystem-specific definitions.
Glossary error token error token. A response token, ZSPI-TKN-ERROR, that identifies an error that occurred during command processing. Every error list contains an error token. Its value is a structure consisting of the subsystem ID and an error number identifying the error. See error list, error number, and return token. event. A significant change in some condition in the system or network. Events can be operational errors, notifications of limits exceeded, requests for action needed, and so on.
Glossary header token header token. A special token, present in every SPI message, that provides information about the message as a whole. The header tokens are typically items common to all or most messages of a specific kind.
Glossary management application management application. A program that manages a subsystem and its objects by issuing commands, retrieving event messages, or both. A management application is a requester with respect to the subsystem server to which it sends commands. management interface. An interactive or programmatic interface through which one can manage a subsystem and its objects.
Glossary object type typically has a name and a type known to the controlling subsystem. In DDL, an item in a dictionary. DDL assigns each object a unique object number for identification. object type. A category of objects to which a specific object belongs: for example, a specific disk file might have the object type FILE and a specific terminal the object type SU. A subsystem identifies a set of object types for the objects it manages.
Glossary pass-through error pass-through error. An error originally reported by one subsystem or system component but included in a response record produced by another subsystem. Typically, a subsystem passes an error from a second subsystem only if that error prevented the first subsystem from performing a command successfully. A pass-through error is expressed as an error list that is nested within another error list. See nested error list. position descriptor.
Glossary requester version requester version. The software revision level of the definition files used in the compilation of a requester. Each subsystem has its own definitions, so the requester version can differ in requests to different subsystems. response. The information or confirmation supplied by a subsystem in reaction to a command. A response is typically conveyed as one or more interprocess messages (response messages) from a subsystem to an application. response message.
Glossary sensitive command the response record contain ZSPI-TKN-MORE-DATA, indicating that the response record is incomplete. sensitive command. A command that can be issued only by a restricted set of users, such as the super group, because the subsystem restricts access to the command. For extended SPI subsystems, the sensitive commands are those that can change the state or configuration of objects; for these subsystems, the sensitive commands are also action commands.
Glossary SPI error number SPI error number. A number that indicates whether a call to an SPI procedure completed successfully and why it failed if it did. This number is returned in the status parameter on calls to the SPI procedures. The SPI error number does not reflect the success or failure of a command; it applies only to errors in the building and decoding of a message in an SPI buffer. SPI message header. The initial part of an SPI message.
Glossary subject structured tokens are extensible structured tokens. See structure, simple token, and extensible structured token. subject. In event management, a device, process, or other named entity about which a given event message is concerned. subordinate names option. In extended SPI subsystems, the designation that the object name given in the command stands not just for itself, but for the names of all objects at the next-lower level in a hierarchy.
Glossary Subsystem Programmatic Interface (SPI) Subsystem Programmatic Interface (SPI). A set of procedures and associated definition files and a standard message protocol used to define common message-based interfaces for communication between management applications and subsystems.
Glossary token data type (16 bits) and a token number (16 bits). In TAL, TACL, and COBOL, names are used to represent token codes (ZSPI-TKN-SSID, for example). In DDL, a special definition (using the TOKEN-CODE statement) that the DDL compiler translates into an SPI token code. Token codes have symbolic names of the form subsys-TKN-name. See also token map and qualified token code. token data type.
Glossary version number version number. A 16-bit integer representation of a software version. For NonStop Kernel subsystems, this consists of an uppercase alphabetic character in its left half and a number in its right half. warning. A condition, encountered in performing a command or other operation, that can be significant, but does not cause the command or operation to fail. A warning is less serious than an error. Compare with error.
Glossary warning SPI Programming Manual—427506-006 Glossary-16
Index A Acting on the response 5-14 Adding tokens to a buffer 3-7 Allow-type token 4-31 See also ZSPI-TKN-ALLOW-TYPE Arrays, in TAL 5-26 ASCII character strings alignment of 5-25 defining in subsystems 5-25 token data type for 4-13 B Boolean values 4-13, 5-25 Buffer See Message buffer Buffer size See Message buffer length C Canceling a command 5-14 Character strings, ASCII alignment of 5-25 defining in subsystems 5-25 token data type 4-13 Checking a response 5-14 Checkpointing and SSGET 3-22 and SSMOVE 3-
Index D D Data definitions coding 5-23 file organization 5-26 general information 2-10 naming conventions 2-11 required 5-23 suggested data representations 5-24 supplied by HP 2-13 using DDL to define B-1/B-7 ZSPI definitions 4-1/4-50 Data lists description of 2-19 in segmented responses 2-38 retrieving 5-5 SSPUT example 5-38 Data type translation, by DDL B-7 DDL and SPI data definitions B-1/B-7 CONSTANT statement B-6 data-type translation B-7 DEFINITION (DEF) statement B-2, B-6 DISPLAY clause B-6 FILLER
Index F Errors (continued) invalid buffer 5-13 invalid buffer format error 5-7 on SPI procedure calls 5-47/5-51 opening management process 5-10 pass-through 2-47 reading the response 5-12 recovering from 2-51 reporting 5-46, 5-47 retrieving last procedure error 3-17 Event Management Service See EMS Event messages, specialized header C-3 Exiting a list 5-5 Extensible structured tokens definition 2-7 moving 3-26 null values 2-8 obsolete fields in D-series RVUs responses 1-11 token maps 2-8 F File-system er
Index M Lists (continued) See also Data lists, Error lists, Generic lists, Segment lists working with 5-5/5-6 M Management applications converting to a D-series RVU 1-12 implications of changes for D-series RVUs 1-10 starting 5-9 Manager process 4-38 closing 5-14 stopping 5-15 Manager token 4-38 Maximum field version checking 5-31 increasing 3-10 retrieving 3-18 See also ZSPI-TKN-MAX-FIELDVERSION Message buffer calculating length 5-16 checksum 2-18, 4-32 current-list pointer 2-17 current-token pointer 2-
Index P Operating system, changes for D-series RVUs 1-10 P Pass-through errors description of 2-49 error lists for 5-51/5-54 example 2-52/2-53 reporting error 2-47 PICTURE (PIC) clause, in DDL B-4 Placing lists in an SPI buffer 5-38 Pointers affected by SSMOVE 3-26 and SSGET 5-4 and SSGET procedure 5-1 effect of procedure calls on 2-20 effect of procedures on 2-23, 2-25 manipulation of 2-17 resetting 3-11 types 2-16/2-17 Positioning to beginning of buffer 3-10 to beginning of list 3-10 Preparing the mess
Index S Retrieving the maximum field version 3-18 Retrieving the maximum responses setting 3-18 Retrieving the next different token code in the buffer 3-19 Retrieving the next token code in the buffer 3-20 Retrieving the object type 3-20 Retrieving the position of the last-put token 3-17 Retrieving the server version 3-21 Retrieving the token involved in last procedure error 3-17 Retrieving the used buffer length 3-21 Retrieving token values by name 5-1 sequentially 5-2 SSGET and SSGETTKN procedures 3-12
Index S SSGET procedure call (continued) syntax in C 6-5 syntax in COBOL85 7-6 syntax in TAL 9-5 usage considerations 3-22 using count parameter 5-2 using index parameter 5-1 SSGET TACL built-in 8-19 SSGETTKN procedure call concept 3-12/3-23 general syntax 3-12 special operations 3-14 syntax in C 6-5 syntax in TAL 9-5 usage considerations 3-22 SSGETV TACL built-in 8-24 SSID See Subsystem ID SSID clause, in DDL B-5 SSIDTOTEXT procedure call description of 3-34 examples 3-36 general syntax 3-34 usage consid
Index T Structure definitions, DDL 4-1, 4-18 Subsystem Control Point See SCP Subsystem IDs checking 5-31 converting to string 5-7 default 4-34, 5-5 defining 2-44, 5-29 qualifies error list 2-49 retrieving current 3-16 returned by ZSPI-TKNNEXTCODE 5-3 returned by ZSPI-TKNNEXTTOKEN 5-3 scope in message 2-46 Subsystem manager, opening 5-10 Subsystem numbers 4-47 Subsystem owner 5-29 Subsystem Programmatic Interface See SPI subsys-DDL-MSG-BUFFER 5-17 subsys-DDL-name 4-1, 4-18 subsys-VAL-BUFLEN 5-16 subsys-VAL
Index U Tokens (continued) header 2-9 internal structure C-5/C-7 logical structure of 2-3/2-5 order in buffer 3-12 overview 1-7 simple 2-7 term defined 2-4 unrecognized in response 5-14 zero length 2-9 TOKEN-CODE statement, in DDL B-6 TOKEN-MAP statement, in DDL B-6 TOKEN-TYPE statement, in DDL B-6 Transaction ID 4-17 Translation of data types, by DDL B-7 TYPE clause, in DDL B-3 U Unsigned integers 4-17, 5-24 Used length of buffer 5-7 V Version compatibility 5-27 Version of server 4-43 W Warnings in mu
Index Z ZSPI-DDL- structures (continued) SUBVOL 4-10 TIMESTAMP 4-10, 5-26 TOKENCODE 4-11 TRANSID 4-11 UINT 4-11 USERID 4-11 USERNAME 4-11 VERSION 4-12 ZSPI-ERR- errors BADADDR A-5 BADNAME A-2 BADSSID A-7 BUF-TOO-LARGE A-2 CONTINUE A-1 DUP-NAME A-1 ILLPARM A-4 ILLTKN A-7 ILL-CHAR A-2 INCOMP-RESP A-2 INTERR A-6 INVBUF A-3 INV-FILE A-1 MISPARM A-4 MISS-ENUM A-1 MISS-FIELD A-1 MISS-LABEL A-2 MISS-NAME A-1 MISS-OFFSET A-1 MISS-STRUCT A-1 MISTKN A-6 NEW-LINE A-1 NOSPACE A-5 NOSTACK A-8 NOTIMP A-7 NO-FORMATID A-
Index Z ZSPI-TDT- token data types (continued) TRANSID 4-17 UINT 4-17 UNDEF 4-17 USERNAME 4-18 ZSPI-TKN- tokens ADDR 3-15, 3-23, 4-31 ALLOW 2-40, 4-31 ALLOW-SEGMENTS 2-29 ALLOW-TYPE 2-50, 4-31, 5-47 BUFLEN 3-8, 3-16, 4-32 CHECKSUM 2-19, 3-9, 3-16 CLEARERR 3-9, 4-32 COMMAND 3-16, 4-33 COMMENT 4-33 CONTEXT 2-34, 2-37, 2-38, 4-33, 5-40, 5-41 COUNT 3-16, 4-34 DATALIST 4-34, 5-5 DATA-FLUSH 3-9, 3-17, 3-23, 4-34, 5-4 DEFAULT-SSID 3-16, 4-34 DELETE 3-9, 3-23, 4-35, 5-4, 5-6 ENDLIST 4-35, 5-5 ERRLIST 4-35, 5-5 ER
Index Z ZSPI-TYP- token types (continued) CHAR5 4-19 CHAR50 4-21 CHAR6 4-20 CHAR64 4-21 CHAR7 4-20 CHAR8 4-20 CHAR-PAIR 4-19 CRTPID 4-21 DEVICE 4-22 ENUM 4-22 ERROR 4-22 FLT 4-22 FLT2 4-22 FNAME 4-23 FNAME32 4-23 INT 4-23 INT2 4-23 INT2-PAIR 4-24 INT4 4-24 INT-PAIR 4-23 LASTERR 4-24 LIST 4-24 MAP 4-24 MARK 4-24 PARM-ERR 4-25 PHANDLE 4-25 POSITION 4-25 RESPONSE-TYPE 4-25 SSCTL 4-26 SSID 4-26 STRING 4-26 STRUCT 4-26 SUBVOL 4-26 TIMESTAMP 4-27 TOKENCODE 4-27 TRANSID 4-27 UINT 4-27 USERID 4-27 ZSPI-TYP- toke
Index Special Characters Special Characters $RECEIVE file 5-31 SPI Programming Manual—427506-006 Index-13
Index Special Characters SPI Programming Manual—427506-006 Index-14
