The Annotated M[UMPS] Standards

☜

OMI - Requests and Responses

Draft MDC Standard

☞

5.4 Requests and responses

Table 1 shows the OMI operations and the values assigned to their operation types. These operations suffice for the database functions of ANSI/MDC X11.1. The unlock client and unlock all operations provide additional convenience for implementers.

Control operations establish and maintain the OMI session. They do not relate to application-level processes.

The global update and fetch operations perform assignment and retrieval of global variables and their values. They correspond directly to application-level database operations.

Lock operations claim and release exclusive use of nrefs, which correspond to database records by application program conventions.

A complete request or response is a <VS>, whose string comprises the request or response header followed by operation-specific fields defined here.

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.

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 request for either the M[UMPS] $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.
26	Reverse query	Requests the previous gvn in reverse collating order. Returns the empty string if no further gvns are defined.
70	Extget	Requests extended information about a global reference. Returns its value, or the empty string if the variable is undefined; its $data value; and the following subscript or the name of the following global variable.
72	Extorder	Requests extended information about the following global reference. Returns its value, or the empty string if it is undefined; its $data value; and its name – the following subscript or global name.
73	Revextorder	Requests extended information about the preceding global reference. Returns its value, or the empty string if it is undefined; its $data value; and its name – the preceding subscript or global name.
74	Extquery	Requests extended information about the following gvn in collating order. Returns its value and its name.
		Lock operations
30	Lock	Claims an incremental lock on an nref.
31	Unlock	Releases a lock on an nref.
32	Unlock client	Unlocks all nrefs for 1 client.
33	Unlock all	Unlocks all nrefs for all clients on the client node.
		Operations on devices
41	Open device	Gains ownership of a device.
42	Close device	Relinquishes ownership of a device.
43	Close client’s devices	Relinquishes ownership of all devices owned by the client.
44	Close all devices	Relinquishes ownership of all devices owned by all clients on the client node.
45	Set device parameters	Sets parameters for subsequent operations to the device.
46	Get device parameters	Returns the values of selected device parameters.
47	Write	Sends data and control information to a device.
48	Finish output	Sends to a device all information transmitted by the client (empties the server’s buffers).
49	Abort output	Terminates output to a device immediately.
		Process initiation operations
61	Job	Requests initiation of a process on the server.
62	Job status	Requests the status of a preceding job request.
63	Cancel job	Cancels 1 incomplete job request.
64	Cancel all jobs	Cancels all incomplete job requests for all clients on the client node.

Table 2 – Error conditions

Type	Name	Description
		Database errors
	Undefined global	Signaled in the Define field of the Get response.
	Lock not granted	Signaled in the Lock Granted field of the Lock response.
1	User not authorized	The user did not have authorization to perform the requested operation.
2	Unknown environment	The environment in a request 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.
70	Incompatible character set profile	The server is unable to translate subscripts or data between its character set profile and the M[UMPS] character set profile selected by the agent.
		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
20	OMI version not supported	The OMI major version requested by the agent in the connect request 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.
		Device errors
30	Unknown device	The device is not known to the server.
31	Device already owned	Another process owns the device.
32	Device not owned	A request names a device that is not owned by the client.
33	Device not accessible	The device is disconnected, off line, not mounted, etc.
34	Device not ready	The device is write locked, out of paper, paused by an operator, etc.
35	Unknown mnemonic space	The mnemonic space is unknown to the server (for the device).
36	Mnemonic space not set	A request names a mnemonic space that has not been set with a precedent open device transaction.
37	Output pending	The server cannot relinquish a device because output has not finished.
38	Parameter syntax	The server cannot parse a device parameter or a process parameter.
39	Unknown parameter	A process parameter is unknown, or the keyword of a device parameter is unknown, or a device parameter’s position is unacceptable to the server.
40	Parameter value	The value of a device parameter or a process parameter is unacceptable to the server.
41	Unknown keyword or position	A keyword is unknown, or the parameter’s position is unacceptable to the server (for the device and mnemonic space).
42	Parameter value	The value of a device parameter or a process parameter is unacceptable to the server.
43	Parameter changed	The agent requests a change to a parameter that the server cannot change.
44	Parameter style	The request contains a parameter style that the server does not support for the device.
45	Write argument syntax	The server cannot parse a write argument.
46	Write argument value	The value of a write argument is unacceptable to the server.
47	Minimum write argument limit	The smallest maximum required by the agent is greater than the maximum supported by the server.
48	Maximum write argument limit	The maximum length allowed by the agent is less than the minimum required by the server.
49	Data overflow	The server’s buffer capacity has been exceeded. Some or all of the data has been lost.
50	Not all write arguments accepted	The server did not accept all the write arguments in the request. The response shall indicate which write arguments shall be retransmitted.
		Process initiation errors
61	Unknown routine	The routine named in a job request is unknown to the server.
62	Unknown label	The label given in a job request is not present in the routine on the server.
63	Unknown line	The line specified by label + offset in a job request is not present in the routine on the server.
64	Job timed out	The process requested by a job request was not initiated during the time specified.
65	Overlapping job requests	The server received a job request before a preceding job request from the same client was completed.
66	Unknown job request number	The job request number in a job status request or a cancel job request is not that of the last job request processed by the server for the client program.
67	Job cancel	A cancel job request attempted to cancel a job request after process initiation completed.
68	Job error	An error of process initiation occurred.
		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.

Some specifications are "approved for inclusion in a future standard". Note that the MUMPS Development Committee cannot guarantee that such future standards will indeed be published.

This page most recently updated on 14-Nov-2023, 21:48:32.

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