Button for 1977 Button for 1984 Button for 1990 Button for 1995 Button for MDC Button for notes Button for examples

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

    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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. Sequence number: <LI> This number shall equal the sequence number of the corresponding request.
  6. 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.

<SI> <SI>
Server Status
Req ID

Figure 3 – Form of a response header

Table 2 – Error conditions

    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.
Button for 1977 Button for 1984 Button for 1990 Button for 1995 Button for MDC Button for notes Button for examples

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

This page most recently updated on 13-Sep-2014, 14:16:58 .

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