The Annotated M[UMPS] Standards

☜

OMI - Response Header

1995 Version of ANSI (Equivalent to Current ISO Version) of Standard

☞

5.3.2 Response header

Each response shall contain a header that describes the server’s response to one request.

The response header is a short string <SS> so that the agent can locate the field following the header. 5.3.1 discusses the need for this ability.

Table 1 – Operation types

Type	Name	Description
		Control operations
1	Connect	Creates a session between an agent and a server. A connect request shall be sent by an agent and accepted by the server before the server accepts any other messages.
2	Status	Requests status from the server. Sent by the agent whenever server status is required.
3	Disconnect	Terminates an OMI session. A disconnect request should be sent by the agent on shutdown, before disconnecting the underlying circuit.
		Global update operations
10	Set	Assigns a value to a global variable.
11	Set Piece	Assigns a value to a piece of a global variable.
12	Set Extract	Assigns a value to positions within a global variable.
13	Kill	Kills a global variable.
		Global fetch operations
20	Get	Requests the value of a global variable. Returns the value, or the empty string if the variable is undefined. A status flag indicates if the variable was defined, so that the agent can use this message for either the MUMPS $Get function or a normal global fetch.
21	Define	Requests the status of a global variable.
22	Order	Requests the following global subscript or the following global name in collating sequence. Returns the empty string if no following subscript or global name is defined.
24	Query	Requests the next gvn in collating order. Returns the empty string if no further gvns are defined.
25	Reverse order	Requests the preceding global subscript or the preceding global name in collating order. Returns the empty string if no preceding subscript or global name is defined.
		Lock operations
30	Lock	Claims an incremental lock on an nref.
31	Unlock	Releases a lock on an nref.
32	Unlick client	Unlocks all nrefs for one client.
33	Unlock all	Unlocks all nrefs for all clients on the client node.

The fields of the global reference and their sequence shall be:

Error class: <LI> denotes 1 of 65 536 classes of errors. The MUMPS Development Committee assigns classes to OMI versions and to specific extensions of the standard (see 4.11). The classes of errors specified by ANSI/MDC X11.2 shall be 0 and 1. All other classes are reserved for assignment by the MUMPS Development Committee.
An error class of 0 means that the request completed successfully. Class 1 indicates failure to perform the request.
Error type: <SI> indicates the result of the server’s attempt to perform the request. When the error class is 0, indicating success, then the error type indicates types of success. For other error classes, the error type denotes a specific error condition.
Error modifier: <LI> modifies the meaning of specific error conditions. This field is optional, therefore it may be set to 0 by a server and may be ignored by an agent. See specific operations in 5.4 for use of the error modifier.
Server status: <LI> conveys information about the server itself, and is not necessarily related to the request. Each change in server status is conveyed in only one response. A value of 0 means that no change in server status has occurred since the last response.
Sequence number: <LI> This number shall equal the sequence number of the corresponding request.
Request identifier: This number shall equal the request identifier of the corresponding request.

Table 2 shows the error conditions that the server shall indicate in responses when applicable. The error class field shall equal 1 in all error responses where a numeric value for the error type appears.

Table 2 also shows other errors for completeness. Circuit errors by definition cause failure to deliver OMI messages. Database exception conditions are not protocol errors. Their error class equals 0 and they are signaled in other fields of the response.

Note – The grouping of error types in table 2 and the assignment of their numeric values is for didactic convenience and does not imply any special qualities or processing requirements.

<SS>
<SI>	<SI> Class	<SI> Type	<SI> Modifier	<SI> Server Status	<SI> Sequence	<SI> Req ID

Figure 3 – Form of a response header

Table 2 – Error conditions

Type	Name	Description
		Database errors
–	Undefined global	Signaled in the Define field of the Get response message.
–	Lock not granted	Signaled in the Lock Granted field of the Lock response message.
1	User not authorized	The user did not have authorization to perform the requested operation.
2	No such environment	The environment in the global reference is not known to the server.
3	Global reference content not valid	The global reference contains invalid characters.
4	Global reference too long	The global reference is longer than the maximum negotiated for this session.
5	Value too long	The value specified is longer than the maximum negotiated for this session.
6	Unrecoverable error	The server encountered a fatal error while processing the request, for example, disk full or write error.
		Protocol errors
10	Global reference format not valid	The structure of the global reference is incorrect. This error indicates a failure in the agent or server logic.
* 11	Message format not valid	The format of the message is incorrect.
12	Operation type not valid	The operation type requested by the agent is not known to the server.
13	Service temporarily suspended	The server has temporarily suspended OMI operations. The agent may choose to disconnect or to retry the operation later. This error is intended for use during backup or other maintenance operation.
* 14	Sequence number error	The server received a request with a sequence number that did not follow the sequence number of the previous request. Indicates either a logic failure or lost message(s).
		Session Establishment errors
0	OMI version not supported	The OMI major version requested by the agent in the connect message is not supported on the OMI server. The agent may try again with another version number.
* 21	Agent min length > server max length	The minimum length required by the agent for value, subscripts, reference or message was greater than the maximum supported by the server. No session can be established.
* 22	Agent max length < server min length	The maximum length allowed by the agent for a field is less than the minimum supported by the server. No session can be established
* 23	Connect request received during session	The agent sent a connect request to the server when an OMI session was already established.
24	OMI session not established	The agent sent a request to the server before sending the connect request.
		Circuit Errors
	Broken session
	Interface busy
	Insufficient resources
*) These errors are fatal to the session. The agent shall reestablish the session.

Copyright © Standard Documents; 1977-2024 MUMPS Development Committee;
Copyright © Examples: 1995-2024 Ed de Moel;
Copyright © Annotations: 2003-2008 Jacquard Systems Research
Copyright © Annotations: 2008-2024 Ed de Moel.

This page most recently updated on 14-Nov-2023, 21:47:33.

For comments, contact Ed de Moel (demoel@jacquardsystems.com)