HYPERMEDIA OBJECT MANAGEMENT

Abstract: A method and apparatus that uses a hypermedia approach to managing distributed objects. A first embodiment of the present invention uses the World Wide Web hypermedia system. A user initializes browser software that allows the user to browse and change various attributes of objects in the system. The browser communicates with a server that includes an http adapter and a gateway. The gateway can access objects in the system and generate HTML code in accordance with the objects. One embodiment of the present invention uses hierarchical tree-oriented objects. These objects are "self-describing" (also called "introspective"). The server queries the objects in response to the queries from the browser and each queried object responds with information about itself. In another preferred embodiment, the server initiates queries of the objects and retains this information for use in responding to later queries from the browser.

Description: HYPERMEDIA OBJECT MANAGEMENT FIELD OF THE INVENTION This application relates to object oriented programming and, in particular, to management of distributed objects via the World Wide Web. BACKGROUND OF THE INVENTION The past several years have seen an explosive growth of the use of distributed objects. Now, a single system may be composed of objects obtained from different vendors and having different interfaces. Such objects are called "heterogeneous objects. " Thus, a system can be formed of a large and rapidly changing number of heterogeneous objects. Such a system requires a flexible and adaptive approach for system and application management. Conventionally, a heterogeneous system is managed by way of object-specific presentation facilities, i.e., by way of a user front-end that was written for each type of heterogeneous object. Such an approach is, however, too expensive in both development time and maintenance and administrative costs. In addition, conventional object management is often achieved through a single management center. Use of a single center is not efficient when a large number of objects need to be managed. SUMMARY OF THE INVENTION The present invention overcomes the problems and disadvantages of the prior art by using a hypermedia approach to object management. In this approach, each object is akin to a hypermedia document. The described embodiment of the present invention uses the World Wide Web hypermedia system. In a preferred embodiment of the present invention, a user initializes browser software that allows the user to browse and change various attributes of objects in the system. The browser communicates with a server that includes an http adapter and a gateway. The gateway can access objects in the system and generate HTML code in accordance with the objects. A described embodiment of the present invention uses hierarchical tree- oriented objects. In a first embodiment, these objects are "self-describing" (also called "introspective"). The server queries the objects in response to the queries from the browser and each queried object responds with information about itself. In another preferred embodiment, the server initiates queries of the objects and retains this information for use in responding to later queries from the browser. In accordance with the purpose of the invention, as embodied and broadly described herein the invention is a system for managing objects, including a first server, comprising: a first receiver portion configured to receive a request in a hypermedia format; a first translator portion configured to convert the hypermedia request to an object request;a sender portion configured to send the object request to an object manager; a second receiver portion configured to receive a response from the object manager; and a second translator portion configured to convert the object manager response to the hypermedia format. In further accordance with the purpose of this invention, as embodied and broadly described herein the invention is a method for browsing objects, where a browser communicates with a server, comprising the steps, performed by the browser, of: sending an initial URL to the server; receiving first data from the server, where the first data specifies an object corresponding to the URL; sending user-entered data associated with the object to the server; and receiving second data from the server, where the second data specifies a second object corresponding to the user-entered data. Advantages of the invention will be set forth in part in the description which follows and in part will be obvious from the description or may be learned by practice of the invention. The advantages of the invention will be realized and attained by means of the elements and combinations particularly pointed out in the appended claims and equivalents. BRIEF DESCRIPTION OF THE DRAWINGS The accompanying drawings, which are incorporated in and constitute a part of this specification, illustrate several embodiments of the invention and, together with the description, serve to explain the principles of the invention. Fig. 1 is a block diagram of a computer system in accordance with a preferred embodiment of the present invention. Fig. 2 is another block diagram of a computer system in accordance with a preferred embodiment of the present invention. Fig. 3 is a diagram of data sent between a browser, server, and object manager in accordance with the embodiment of Fig. 1 . Fig. 4 is a diagram of a format in which objects are organized. Fig. 5 shows another example of a page displayed by the browser. Figs. 6(a) and 6(b) show an example of HTML that causes the browser to display a portion of the page of Fig. 5. Figs. 7(a) through 7(c) show further examples of HTML that result in the portions of page of Fig. 5. Figs. 8(a) and 8(b) show several examples of ORM (Object Resource Management) requests made by the server to the object manager and the resulting responses from the object manager. Fig. 9 shows another page displayed by the browser. Fig. 1 0 shows layers of functions available to the object manager. DETAILED DESCRIPTION OF PREFERRED EMBODIMENTS Reference will now be made in detail to a preferred embodiment of the invention, an example of which is illustrated in the accompanying drawings. Wherever possible, the same reference numbers will be used throughout the drawings to refer to the same or like parts. I. System Overview Fig. 1 is a block diagram of a computer system 100 in accordance with a preferred embodiment of the present invention. Computer system 100 includes a first computer 1 10 and a second computer 1 20. First computer 1 10 and second computer 1 20 are connected together via line 106, which can be, for example, a LAN, a WAN, or an internet connection. Line 106 can also represent a wireless connection, such as a cellular network connection. First computer 1 1 0 includes a CPU 1 02; a memory 104; input/output lines 1 05; an input device 1 60, such as a keyboard or mouse; and a display device 1 50, such as a display terminal. First computer 1 10 also includes an input device 1 61 that reads computer instructions stored on computer readable medium 1 62. These instructions are the instructions of e.g., browser software 1 30. Memory 1 04 of first computer 1 10 includes browser software 1 30, Hypertext Markup Language (HTML) 135, and objects 132. A person of ordinary skill in the art will understand that memory 104 also contains additional information, such as application programs, operating systems, data, etc., which are not shown in the figure for the sake of clarity. Second computer 120 includes a CPU 102' and a memory 104'. Memory 104' of second computer 120 includes server software 140, an object manager (ORM) 142, and objects 144. HTML 135 in the memory of first computer 1 10 was downloaded over line 106 from server 140 of second computer 1 20. A person of ordinary skill in the art will understand that memory 104' also contains additional information, such as application programs, operating systems, data, etc., which are not shown in the figure for the sake of clarity. Server 140, object manager 142, and objects 144 can also be located in memory 104 of first computer 1 10. It will be understood by a person of ordinary skill in the art that computer system 100 can also include numerous elements not shown in the Figure for the sake of clarity, such as disk drives, keyboards, display devices, network connections, additional memory, additional CPUs, LANs, input/output lines, etc. The following paragraphs provide a general discussion of the World Wide Web ("the Web"). The Web is built around a network of "server" computers, such as second computer 120, which exchange requests and data with each other using the hypertext transfer protocol ("http"). A human designer designs the layout of a Web page, which is then specified using HTML ("Hypertext Markup Language"). Several versions of HTML are currently in existence. Examples include HTML versions 2.0 and 3.0, as specified by the WWW Consortium of MIT. The HTML used in the described embodiment of the invention includes frames, forms, and tables, as are known to persons of ordinary skill in the art. A user views a Web page using one of a number of commercially available "browser" programs. The browser submits an appropriate http request to establish a communications link with a Web server of the network. A typical http request references a Web page by its unique Uniform Resource Locator ("URL"). A URL identifies the Web server hosting that Web page, so that an http request for access to the Web page can be routed to the appropriate Web server for handling. Web pages can also be linked graphically to each other. Fig. 2 is an additional block diagram of a computer system in accordance with a preferred embodiment of the present invention. Browser 1 30 communicates with server 1 40. Server 140 includes an http adapter 202 and a management gateway 204. Http Adapter 202 handles communication via the known http protocol. Management gateway 204 communicates with object manager 1 42. Server 140 communicates with one or more objects 1 32, 144 using a request/response (RR) protocol, such as the ORM (Object Resource Management) protocol, which is discussed below. Note that objects 1 32 and 144 can be located on the same or different physical computers or machines. Server 140 also communicates with external interface 206, which communicates using the known SNMP and CMIP protocols. Server 140 also communicates with external gateway 208, which communicates using the known SNMP and CMIP protocols. The system can contain more than one servers 1 40 and more objects than are shown in Fig. 4. Fig. 3 is a diagram of data sent between a browser, server, and object manager in accordance with the embodiment of Fig. 1 . In the example of Fig. 3, the user has already begun execution of browser software 1 30. In step 302, the user enters the URL of server 140 by way of browser 1 30. The browser sends a request to the server and, in step 304, the server responds with the HTML to generate a home page. The home page allows the user to enter a URL (or to chose a URL from those known provided within the HTML of the home page). The user can then chose to set/browse objects in the system, as described below. The user can also request information and statistics about once or more objects in the system. In step 306, the user enters a URL of an object by way of browser 1 30. Server 1 40 converts the URL to a request to an object manager. For example, in the described embodiment, server 1 40 converts the URL to an ORM request, as described below. The ORM request is sent to the object manager, which returns object data in steps 308 and 310. Server 140 converts the object data into HTML, which is sent to browser 1 30 in step 31 2. The HTML may be based on a predetermined page template known to the server. Alternately, the format of a page may be determined "on the fly" based on the information obtained from the object manager. Server 1 40 converts all pathnames, such as object-links in the object data (see Fig. 4) to URLs in HTML and vice versa. Thus, if a user clicks on an area in a page displayed by the browser that corresponds to an object-link, browser 130 has the URL corresponding to that object-link. This new URL is sent to the server, which obtains the page information and sends HTML to display information for the object connected to the object-link. Steps 314 through 320 represent a "set" mode, in which the user enters new values for an object by way of browser 130. In step 314, the user indicates that he wishes to enter "set" mode. This indication is usually accomplished by clicking on a button in the current page (thus, the HTML generated by server 140 should include HTML for this button). In step 31 6, server 140 sends a "form" for set mode. In step 318, the user enters new values into the form and clicks on "submit" (or "apply", (see Fig. 5), as is known to persons of ordinary skill in the art. Server 1 40 converts the submitted form to, for example, an ORM request, as described below. The ORM request is sent to the object manager, which returns object data in steps 31 7 and 31 9. Server 140 converts the object data of step 31 9 into HTML, which is sent to browser 1 30 in step 320. Steps 322 through 332 represent a "browse" mode, in which the user views values associated with an object by way of browser 1 30. In step 322, the user indicates that he wishes to enter "browse" mode. This indication is usually accomplished by clicking on a button in the current page (thus, the HTML generated by server 1 40 should include HTML for this button). In step 324, server 140 sends a "form" for browse mode. In step 326, the user enters new values into the form and clicks on "submit" (or "apply", see Fig. 5), as is known to persons of ordinary skill in the art. Server 140 converts the submitted form to, for example, an ORM request, as described below. The ORM request is sent to the object manager, which returns data corresponding to the object in steps 328 and 330. Server 140 converts the response of step 330 into HTML, which is sent to browser 1 30 in step 332. II. Hypermedia Object Management A. Object Organization Fig. 4 is a diagram of a format in which objects are organized in a preferred embodiment. This organization is transparent to server 1 40 and browser 1 30. It will be understood that the present invention can be used with a number of object organizations and with a number of object management protocols. The embodiment described herein uses the ORM protocol, as described below. The model of Fig. 4 assumes the following: 1 ) Management operations can be mapped to two basic operations: a) Get an attribute (or a set of attributes) of an object and b) set an attribute (or set of attributes) of an object. 2) All entities to be managed can be organized as a directed tree with nodes and leaves where the nodes are either (callable) objects or components (sub-parts of objects) with attributes as the leaves (with combined name/pair values), and 3) All knowledge about management operations and attributes is built into and controlled by the managed object. Fig. 4 shows the following types of entities: 1 ) Objects Objects encapsulate and control management aspects and respective management operations. In the described embodiment, an object is identified by a "pathname, " which is the destination for object calls. Each manageable object has its own virtual tree of components, attributes, and object-links. 2) Components Components are the primary structuring mechanism within an object. Component sub-trees may be of arbitrary depth and component nodes may contain any number of object-links, other sub-components, or attributes. 3) Attributes Attributes describe specific aspects of a component within an object (for example, "status = running" describes the state of a resource). Attribute nodes have additional properties beyond name and value, such s access mode and data type. Attribute nodes are leaves and do not have children. 4) Object-links Object-links contain an object reference to a related object. As every object is responsible for its own virtual tree of resources, one object can provide a reference (hyperlink) to another object. Thus, in the described embodiment, a first object can have links to a second object, so that objects can be "walked" by way of browser 1 30. 5) Relations Objects and components are the primary means for structuring and navigation in the described embodiment. Attributes have values that characterize the state of the resource. All operations (browsing and attribute retrieval/setting) are performed with respect to a single level of the tree (e.g., relative to a specific parent). Server 140 preferably issues the following requests to object manager 1 42: 1 ) Get a list of linked objects, 2) Get a list of components and/or sub-components, 3) Get a list of attributes, 4) Set a list of attributes (Along with name/value pairs for each attribute), and 5) Get an extended list of attributes, which returns meta-information about the attribute, such as data type, allowed access mode (ro, rw) or valid ranges of new attribute values. Within the ORM model, all management operations are mapped to these five operations. Thus, every managed object preferably supports these five operations. It should be understood that the attributes and object types shown in the examples herein are included only for the purposes of example. The present invention can be practiced using any appropriate object organization and type. B. Server Interface In the described embodiment, all messages passing in and out of server 140 are ASCII messages. A example URL for object 402 of Fig. 4 would look like: Http://ham/get/objectRoot/Component1 /Component2/ A example URL for attribute 404 of Fig. 4 would look like: Http://ham/get/objectRoot/Component1 /Component2/Attr1 / In both of these URLs, "ham" stands for "HyperMedia Adapter to Management" and represents the address of server 140; "get" (this could also be "set") represents an operation to be performed on an object or attribute; and the remainder of the URL represents the tree of the object or attribute known to the object manager. Other URLs may also include additional information use, for example, by the object manager. Fig. 5 shows a page displayed by browser 1 30 in "set" mode. Fig. 5 shows the values of attributes for a "Configuration" object component. These attributes include: 1 ) Status 520, 2) Maximum Concurrency 523, 3) Trace Level 524, 4) OSL Traces Enabled 526, 5) Script directory/Vol. 528, 6) Script File 530, 7) Cache Tel Scripts 532, 8) Tel Trace Enabled 534, and 9) Maximum Size of Synthesized Page 536. Fig. 5 also shows an entry 522 for changing the status attribute. It should be understood that the attributes of Fig. 5 are presented for the sake of example only and are not to be taken in a limiting sense. Fig. 5 also shows a reset button 540 and an apply button 550. When the user clicks reset button, original attribute values are returned. When apply button 550 is clicked, browser 1 30 posts a form, as is known to persons of ordinary skill in the art. Figs. 6(a) and 6(b) show an example of HTML generated by server 140. When browser 130 interprets the HTML of Fig. 6, it generates the portion containing attribute values 520-536 and buttons 540, 550 of Fig. 5. Figs. 7(a) through 7(c) show an example of HTML generated by server 140. When browser 1 30 interprets the HTML 702, 704, and 706 of Figs. 7(a) through 7(c), it generates portions 502, 506, and 504, respectively, of Fig. 5. Fig. 9 shows another page displayed by browser 1 30 in accordance with HTML generated by server 140. The page of Fig. 9 is used to browse objects, but cannot change the attributes of objects. The previous paragraphs discuss the browser GUI presented to the user and how server 1 40 translates between HTML and a protocol understood by the object manager. The following paragraphs describe the protocol used to communicate with object manager 142 about objects and to change objects in accordance with the HTML received by the server. Figs. 8(a) and 8(b) show several examples of ORM requests made by the server 140 to object manager 142 and the resulting responses from object manager 142. Pages of the description shows formats of such requests and responses. Request 802 is an example of an OrmGet request sent from server 140 to object manager 142. The format of an OrmGet request is: OrmGet: pathname entity types where pathname is a name of an object or an attribute. Possible entity types are: "Object" (all known objects at this level), "Component" (a list of all components below the level of the path specified in the OrmGet), "Attribute" (a list of attributes for the current node; for every attribute, its name and "stringified value is returned; if the pathname already navigates to an attribute, the object manager returns the empty string), "Info" (returns "meta-attributes" such as mode, range and unit), and < none > (i.e., an empty string). In request 802 of Fig. 8, the server "knows" about an object "HyperMedia Adapter NSK" , possibly from receiving a URL from browser 1 30. Line 820 represents a version of the server (e.g., version 1 .0). Line 822 is an "OrmGet" request for object "HyperMedia Adapter NSK". Server 140 requests information from object manager 142 about entity types (Info), Component, and Object (lines 824). Response 804 is generated by object manager 142 and sent to server 1 40. The object has four components, no info, and no objects at the same level. As seen in step 31 2 of Fig. 3, server 140 generates HTML 604 of Fig. 7(c) in accordance with response 804 and sends the generated HTML to browser 1 30. Assuming that the user wants to browse information about the Configuration component of object "HyperMedia Adapter NSK", browser 1 30 sends a request to server 140 to this effect. Server 140 then sends request 806 to the object manager, which responds with response 808. Request 806 is similar to request 802, but the pathname in line 830 is "HyperMedia Adapter NSK/Configuration" . Response 808 includes attributes for the "Info" entity. Thus, the response includes an attribute value, mode, field, and range for each of ten attributes of the component "Configuration". As seen in step 332 of Fig. 3, server 140 generates the HTML of Figs. 6(a) and 6(b) in accordance with response 808 and sends the generated HTML to browser 1 30 (see Fig. 5) . Assuming that the user wants to change one or more attributes of the Configuration component of object "HyperMedia Adapter NSK", browser 1 30 sends a request to server 140 to this effect (assuming that the browser is in "set" mode). Server 140 then sends request 810 to the object manager, which responds by sending a status value (not shown). A format of the OrmSet request is: OrmSet: pathname Attribute: name Value: val where "name" and "val" respectively, represent an attribute name and an attribute value. This command is shown in line 840. The command can include more than one Attribute/Value pairs. In the example, request 810 specifies new values for eight attributes of component "Configuration. " Assuming that no error occurs when the object manager changes the attribute values, server 140 generates HTML reflecting the new attribute values in accordance with the response and sends the generated HTML to browser 1 30 (not shown). A preferred embodiment of the present invention has a server that interfaces with "self describing" (or "introspective") objects. The server sends requests to and receives responses from an ORM (Object Resource Manager). The system may include more than one ORM and more than one server. Each server may "know" about zero or more ORMs. Thus, the system is not centralized and does not necessarily depend on a central point to interface with the objects. C. The Object Manager 1 . Self Describing Objects Fig. 4 shows an example of object organization in a preferred embodiment of the present invention. Pages of the description, shows examples of an ORM Server Support Library API (Application Program Interface) supported by the object manager to access objects in a preferred embodiment of the present invention. The routines in the API of pages are used by object manager (e.g., ORM 142 of Fig. 1 ) to receive requests from server 140 and to prepare responses to the requests. It will be understood be persons of ordinary skill in the art that any object manager can be used in conjunction with the present invention, as long as the object manager is capable of communicating with server 140 and of fulfilling GetOrm and SetOrm requests from server 140. Fig. 1 0 shows layers of functions available to the object manager. A Protocol layer 1 002 handles the ORM protocol, e.g., decodes the request from server 1 40, initiates the corresponding functions, and assembles an ORM response. Protocol layer 1002 is the lowest layer and drives all calls to the upper layers by calling "registered" functions. A Node layer 1004 handles navigation between nodes, ie.e, parsing the pathname to locate the virtual node, which represents some management entity. A Handle layer 1 006 maps "virtual nodes" to real objects/data. Such a mapping results in a "handle. " Handles are explicitly requested and released. An Aspects layer 1 008 handles instances that are made up from more than one ORM tree. For example, the "statistics" Component is not a single Component n the tree, but is generated by the object manager. As another example, some attributes depend on others and cannot be modified independently, but have to be treated as a single, atomic operation. These groups of attributes within an instance are called "aspects" and the corresponding Aspect layer is provided to extract and modify groups of attributes within an instance. An Attribute layer 1 01 0 retrieves or updates a single attribute (of an aspect) and provides the eta information corresponding to this attribute. A Conversion layer handles the actual conversion of attributes between the external (ORM) and the internal (native) presentation. This layer also converts states and bitmaps to "friendly strings." 2. Web Agents In another preferred embodiment of the present invention, the objects are not self-describing. In such an embodiment, one or more servers 140 in the system performs a "worm" function, i.e., one or more servers 1 40 follow object-links between objects and save all the information available concerning those objects. When a request is received from browser 1 30, server 140 sends its collected data to browser 1 30 (assuming that the collected data is not older than a threshold age value). In summary, the present invention allows a user to manage objects by way of hypermedia, such as the world wide web. In a preferred embodiment, the objects are self-describing and respond to questions about themselves from one or more object managers. A server communicates with the object manager(s) and generates HTML from responses received from the object manager. Conventional browser software allows a user to indicate which objects he wishes to browse or change. Using a conventional hypermedia request/response protocol, the browser and server communicate to obtain information about objects and their attributes. The server also translates HTML/URLs received from the browser to requests to the object manager. Such a system allows a non-centralized object management system. Other embodiments will be apparent to those skilled in the art from consideration of the specification and practice of the invention disclosed herein. It is intended that the specification and examples be considered as exemplary only, with a true scope of the invention being indicated by the following claims and equivalents. 5 Browse (readonly) and Change (read write) modes are differentiated by different URL's. For the Change mode an HTML input form is created with user interface elements dependant on the meta information provided with attributes. Dependant from this meta information, simple text input or numeric mput fields, popup boxes or radio buttons are generated. 6. A submit of this HTML form results in an HTTP POST request, which appears at the managements adapter with a special URL and the list of name/value pairs from the input form. These values can be checked against the information now retrieved from the object (see above) and a ORM SetAttπbute request is send to the respective object. This object initiates he intended state changes or returns an error to the adapter, which then creates a new page, which reflects the outcome of the operation. 7 Access control can be either applied by the generic HTTP adapter, filtering POST methods for example or by the called object itself using principal identifiers in the ORM request. 5.3 Events and Alerts Compared to SNMP or CMIP ORM has no event or trap mechanism. With this respect it is much closer to the NSK management protocol called SPI. Instead event and alert support is provided by another mechanism (and object) within MSF, called Alert Facility, which is built on top of the Common Execution Enmrσnment (CEE). 6.0 ORM Protocol 6.1 General Characteristics The ORM protocol is a simple request response protocol constructed out of lines of ASCII text and terminated by newline, to browse through the managed object and change its state. In this way, it is directly comparable to the HTTP protocol. It is bytestream oriented, as it contains no length fields or has any fixed structure, but the individual items are separated by special characters, i.e. colons and newlines. T e logical end of a protocol unit is determined by an empty line i.e. a line with a newline character as the first character. Remark: The decision for a pure ASCII protocol may be surprising, as MSF has a well defined presentation layer /protocol by IDL/PCU/GLU, but ORM is designed to support self contained object management, e.g. all manageable aspects of an object should be described by the managed object (or its manager) itself and just known by it. This implies, that a lot of human readable information has to be shipped with this protocol and using a pure ASCII protocol seemed quite natural. In addition the browsing nature of the protocol would have resulted in a quite unhandy IDL structure of unbounded sequences of any's or unbounded strings, probably with another layer of unbounded types above. Using ASCII strings simplifies the creation of protocol units. Last not least, ORM must also support the entities provided to build the MSF iruVastructure itself, e.g. must also be available with and without these execution environments. Internally the ORM protocol (ORM-P) is a tagged line protocol, as every line starts with a tag word followed by the tag value separated by a colon and terminated by an end of line character (newline). The protocol itself supports boxcarring (e.g. consolidated requests). Errors are reported inline with the data i.e., where they occur, by special error tags. Request and response units are constructed the same way and the response is merely a "filled out" or "completed'' request and as such, the information in it is self describing (i.e. need not necessarily correlated with the request). This is not true for authentication information, which is not mirrored in the response. The ORM-P basically supports two kinds of operations: 1. get entities (OrmGet) 2. set attributes (OrmSet). The two keywords OrmGet and OrmSet at the beginning of every sub-request describe the intended operation (Le. are the operation tags). In addition to these two basic operations there is a preamble required for every (consolidated) ORM packet, identifying the originators protocol version (tag Orm Version) and in the case of a request, there is an optional tag, to pass authentication information from the client to the server (Orm Who). 6.2 Pathnames: Pathnames provide the necessary navigation and identification information to locate a specific aspect of an object (or its internal entities). The different parts of the pathname usually are also the names of the entities in the generated user interface and as such, should be "friendly", descriptive names. A pathname consists of a "/" separated list of components, which in turn may contain any printable character including whitespace. For the current version, characters in the pathname components are restricted to the printable set of ASCII characters but may be extended to cover all printable ISO-8859-1 characters in the future (ORM-P is "8-bit clean", but this restriction is just to be more flexible in the choice of user interface construction). There are two special component names, which follow the POSLX convention for filesys- tem tree navigation: "." and "..". These are only allowed in conjunction with an OrmPath tag and refer to the current node and to the parent of the current node respectively, where the "current node" must have been defined by a previous ORM sub-request in the same protocol unit (i.e. OrmGet or OrmSet). An attempt to traverse the parent of the root of the tree is treated as an erroneous pathname (compare with "cd" in a POSLX system). 6.3 Error Reporting (OrmError): Errors are reported, where they are detected, i.e. the error tag (OrmError) usually appears directly behind the error causing tag in the response. This allows some kind of identification of the failed subrequest or protocol item even for large consolidated requests. An error tag in the response also indicates, where the request was aborted. Previous sub- requests in the same ORM packet may have been processed 1 . An error tag (OrmError) has a constant and a variable part, where the constant part identifies the kind of error, the variable part is used for additional hints, what caused the error. As the error is reported with a context, this context provides valuable information for error explanations. The Format of an error protocol item: OrmError : < decimal errorcodo <stringcode> : <variable part*\n' 6.4 Version Support: Orm Version: The first line in every protocol unit must identify the highest protocol version number, this protocol unit complies to. The actual version is 1.0! 1. When the ORM requests are issued vu the ID interface, the error also appears as an exception with the exception detail showing the actual ORM error code. e g- OrmVersιon: <major> . <rainor> A server/ application may respond to this request with an error VersionMissmatch followed by its desired version id. 6.4.1 Protocol Conformance & Protocol Errors: Unknown tags should be ignored unless they appear at a position, where another tag is required (an attribute tag must be followed by a value tag for example). If the latter occurs, the unidentified or unexpected tag is placed in the response message followed by an error tag with "ProtocolFailure" 6.5 Principal Identification Information: Orm Who For the purpose of propagating the identification of a principal causing the request or to be used with the request, ORM-P supports a protocol item to ship any kind of (encoded) principal identifier with a request in the following way: OrmWho : <principal identifier> Up to now, neither the <id-scheme> nor the encoding or interpretation of the "encoded- principal-identifier" are specified in any detail by ORM-P but are up to the application and require an agreement between the ORM-P client and server. This may be subject of change! 6.6 Browse Operation: OrmGet The operation tag "OrmGet" has to be followed by a colon (":" - the tag separator) and usually is followed by a "pathname". As every ORM protocol item, the operation tag followed by the optional pathname has to be terminated by a newline character. This first line is followed by a list of entity type spedfyers requested. 6.6.1 Entity Types The OrmGet request is followed by a list of type spedfyers to describe the kinds of entities requested for browsing. Allowed types (and entity spedfyers) are: • Object requests a list of all known object links at this level. A friendly name and the link- address (NOR) is returned per object • Component A list of all components below the level of the path specified in the GET line is requested. A list of names is returned. • Attribute A list of attributes for the current node is requested. For every attribute its name (Name:<name>) and its stringified value (Vβ/u«:<value) is returned. If the path in the OrmGet line already navigates to a single attribute, the returned name is the empty string. • Info (implies Attributes) This type addresses the same type of entities as "Attributes", but here meta information in addition to the name/value pair is requested, as there is Field for identifying the type of input expected. Mode to describe the access mode (read, read-write or write) and the so called hints (Range and Unit), which can be used by the user-interface to generate a more sophisticated presentation of the attribute. These info fields are described below in detail in the response section. • <Empty> An empty type spedfyer indicates that the validity of the pathname should be checked, but no information is requested. As all ORM protocol items, every single type spedfyer is teπninated by a newline. Examples: 1 ) OrmGe : /telne /windows\n CorπponentXn \n 2)OπnGet:/telnet/windows/#ptyl/status\n Attribute\n OrmPath: .. / .. /pty2/status\n Atcribute\n \n 3 )OrmGet : / elnet\n θbject\n Component\n InfcΛn \n Note: Leading blanks in front of the tag or the tag value are ignored as well as lines, whose first character is a "#". The OrmGet request may be called without a pathname specification (e.g. "OrmGetΛn") in which case the root object itself is referenced and the only valid type spedfyer is "Object", which will return the "friendly" name of this object manger and its link address (Note: this link address may be another one, as the request was sent to, i.e. this allows redirecting the management requests to another object reference). 6.6.2 OrmGet Response The response to a OrmGet request merely mirrors the request, but here the type spedfyers are used as tags (to type the following entity) followed by the name of the entity (separated by ":") followed by a newline character. The name item is followed by a type dependent list of additional tagged items, describing further properties of this entity. Although the partial responses below are listed per entity type, they appear in the same response unit in the same sequence as in the corresponding request unit, i.e. if the latter requested entity types by the sequence "Object\nComponent\Attribute\n", then the response will first list all available objects at this level followed by all available components followed by all available attribute/value pairs. If a requested type is not available at the spedfied level, an empty tag of that type (with a colon) is returned. The response unit for an OrmGet request starts with the common response header (i.e. OrmVersion:<version>) followed by the "OrmGet: <pathname>" line followed by any number of the following constructs. 6.6.3 Object Entities: Syntax: <object-item> ::= -Object* [*:* <scring> *\n* <object-link>] *\n* <object-link> ::= "Link* • :* <string> Example: Object : etwork Service Layer\n Link : <obj -re erence>\n Object :Media Access Layer\n Link : <obj -reference>\n \n ( if this is the end of the response ! ) 6.6.4 Component Entities: (have no additional properties) Syntax: <component-item> ::= 'Component* [*:* <string>] *\n* Example: Component :Conf iguration\n Componen : Statistics\n \n ( if this is the end of the response ! ) 6.6.5 Attribute Entities (simple request) Syntax: <attribute-itβm> : : = -Attribute* [ ' : * <atτintj> *\n* <attributβ-valu*>] "\n* <attribute-value> :. : » 'Value* * : * <βtrin r> Example : Attribute : Packets sen \n Value: 1234\n Attribute : Packets received\n Value: 4321\n 6.6.6 Attribute Entities (Info request): Synta : <attnbute-ιtem> = 'Attribute* [ ■ :* <string> * \n * <attribute-info> | *\n*l <attribute-info = <attπbute-value> *\n* (cnt) <attribute-mode>*\n* (cnt) <attribute-field> *\n* (cnt) (<attribute-range> *\n* I [<attribute-unit> "\n*l <attribute-mode> = 'Mode:' (*R0*|*W0*|*RW'l C'P'l <attribute- ield> = 'Field:* <ORM-fieldtype> <attribute-range> = 'Range:* <ORM-range-definition> <attribute-unit> = 'Unit:* <string> Example : Attribute: Status\n Value : Running\n Mode:R0\n Field: String\n Attribute:New StatusVn Value : unning\n Mode :W0\n Type : Enum\n Range : Stopped, Abor ed\n Here the sequence of the different info tags is not relevant, but "Attribute" always starts a new property set for the next attribute. The "Range" and "Unit" tags are optional. For "ORM-field type" and "ORM-range-deflnition" see below. Errors 6c Exceptions spedfic to this request • NoSuchNode: The path specified does not point to a legal virtual node-This error is only reported iinmediately after a "Orrn{Get/&t/Pam]: pathname>" command. • InvalidOperation: The path specifies a node, which can not support the requested entity type, an "Attribute" request for an *Objecf node or vice versa for example. This error is reported after a type spedfyer, listing the type spedfyer (without a colon) followed by a newline followed by the error tag. 6.7 Modification Requests: OrmSet The set request starts with the set-tag "OrmSet" followed by a pathname followed by a newline. The pathname at minimum must contain the name of the root e.g. "/<root- name>" (i.e. an empty pathname is not allowed!). This line is followed by a sequence of line pairs containing the name of the attribute and its value, e.g. Syntax: < attrιbute-ιtem> : : = 'Attribute* ( " : * <string> * \n* <attribute-value> l *\π* <attπbute-value> : ; = "Value : * <str ng> Example: Attribute : New Status\n Value : Suspended\n Attribute : Reset Statistιcs\n Value :Yes\n \n ( if this is the end of the protocol unit) 6.7.1 OrmSet Responses: If no error occurred, the response to the OrmSet request is a copy of the request itself. Otherwise an error-tag may appear somewhere in the response, and if the underlying request /response protocol permits, the response is flagged with an error indicator. The effect of an erroneous OrmSet sub-request is application dependant, but it is recommended, that a OrmSet sub-request either succeeds completely or has no effects at all (atomiάty). Any OrmSet requests preceding a failed one are not affected, any subsequent requests are ignored. 6.7.2 Error-Returns: • NoSuchNode: The path specified does not point to a legal virtual node. This error is only reported immediately after a "SET:<pathname>" command. • NoSuchAttribute: The string following an "Attribute:" tag does not identify a legal attribute. The error- tag follows the "Attribute:" tag (induding the string). • ValueOutOfRange The value specified is not within the range of legal new values for this attribute. The error tag follows the value-tag line. • Valuelnconsistent The set of attribute values in the request were no consistent or contradictory • InvalidOperation: The designated Attribute is not writeable. • NoPermission: The access rights of the requester do not allow to set the designated attribute.(This error and the previous one may have some overlap) 6.8 Request Type Independent Errors: • ProtocolError: [f pairs of tagged lines are expected and the sequence of pairs is not completed or an unknown or context illegal tag is detected, this error is generated, following the erroneous tagged line. • IntemalError: An internal error in the application /server was the cause, that this request could not be completed, (allocation failure, mangled structures). This indicates a severe error at the server side. • BufferTooSmall: The response buffer spedfied is too small to return the full response. • NoSpace: Some internal buffer could not be allocated or was to small for the requested operation. 6.9 ORM Attribute Info Descriptions: Within the ORM protocol there are two ways to retrieve an attribute: the short form returns just the name of the attribute and its value and the long form, returning additional meta information for every attribute, which can be used to create reasonable user interface elements by the ORM client The following fields appear n the extended description: - Field: identifies the kind of field, this attribute should be presented in - Mode: identifies applicable operations (readonly, read/write, writeonly) - Range: Provides bints for input checking and for user interface generation - Unit: a free form field often describing the metric of the value or scale. 6.9.1 ORM Field Types: Although in prindpaL the ORM field type item (Field) allows any prinάpal character string, the ORM support library and the user interface generator (HTML synthesizer) will only support a limited set of predefined field types, to ease the presentation of attributes. If a field type is not recognized, the default "String" is assumed. 6.9.1.1 Field: Integer The ORM protocol does not distinguish between unsigned and signed integers, e.g. every ascϋ string representing an integer may be prefixed by a "-" or a "+". There is also no size information in the field type. Any range restrictions have to be specified in the Range section. Syntax: Field: Integer 6.9.1.2 Field: Real The field type Real identifies dedmal floating point values. The allowed input formats are those of the POSLX 1003.2 scanf function for float and double values. Syntax: Field:Real 6.9.1.3 Field:HexOctet This field type is used to display and enter binary data as pairs of hexadecimal character Syntax: Field:HexOctet (a sequence of hexadecimal digits) 6.9.1.4 Compound-Field Types: The last set of field types allow much finer control of the input, an end user may provide to the ORM-P client side (or the client of the client...). These types are named Enum and Set, where Enum specifies a "one out ofm" field and Set specifies a "n out ofm" field. Both types are only valid with an appropriate Range field in the hints section, where the possible alternatives must appear in a comma separated list These two types often transformed into "Pop-Up" menus (Enum) or option lists (Set) or similar by the user interface generator. Syntax: Field:Enum (single selection from 'Range:') Field:Set (multiple choices from 'Range:') 6.9.2 ORM Attribute Modes: To generate reasonable user interfaces (as far as possible without object/component specific knowledge), the generator must know, whether an attribute is "read-only", "read- write" or "write-only". The latter is used to signal to the user interface, that this attribute should be only shown in "change-attribute" frames, if those are distinguished from pure browsing frames. An extension to these basic modes is provided for writable attributes to indicate, that an attribute value is mandatory, by appending the letter "M" The different modes are simply encoded as two-letter strings followed by an optional "P", e.g. Syntax - RO Read-only - O[M] Write-Only[non-null value mandatory] - RW(M] Read-Write (non-null value mandatory] 6.9.3 Range Identifiers: The range identifier, tagged with "Range:" is used as a kind of hint (and therefore it is optional except for the compound fields) to the user interface generator, what kind of input /output field it should generate. In addition the information can be used to check any optional input and give the end-user appropriate responses or hints, if these input checks fail. The range hints are type spedfic and as such different conventions are defined to specify valid ranges for an input field. The type independent convention is to separate alternatives by a comma "," and sequences by three subsequent dots "...".: 6.9.3.1 Range Specifications for Integer Fields: Valid range specifications for the integer types are: 1 of the values listed all numbers between 20 and 60 including every integer including 0 (up to typemax) every integer between -20 and +20 incl. every pos/neg integer within type 6.9.3.2 Range Specifications fro Floating Point Fields: Valid range specifications for the real types are: Range : 0 . 1 , 0 . 5 , 0 . 8 valid: one of the values listed Range : 0. le-3 . . .0. 1 valid: reals between 0.0001 and 0. 1 6.93.3 Range Specifications for String Fields If the first range value starts with a digit, the range indicates either the maximum or the range of valid string lengths. If the first character is non numeric the range is interpreted similar to the compound Enum field below, Le. one of these strings may be selected, but a different user interface element may be used (a list box). If the first character of the range string is a comma ",", this provided strings in the comma separated list are treated as examples, where the possible input is not restricted to the given alternatives. A major use of this kind of string selection is in file selection boxes. Syntax: Range:1...20 valid: strings with minimum length of 1 and max length of 20 characters Range: 10 valid: a string with at max 20 characters. Range: , filel.c, file2.c filel.c or £ile2.c are valid options, but other input is also valid 6.9.3.4 Range Specification for Compound Fields: For the Enum and the Set type fields lists of alternatives are required in the range section. The comma separated list identifies the different options a user is allowed to select. Syntax: Range : <comma separated list of alternatives> Example: For Enum ( choose one of ) Range : STOP , SUS P END , ABORT For field type Set (choose n or none of ) Range : Trace IP , race UDP, Trace TCP 6.9.4 The Unit Specification: The "Unit" specification is a free form string and currently not interpreted by me user interface generator. If present, it will append this string behind the value field as one would do with a unit description like "1.4 inches". Another important purpose of this field is for the use with customized object specific management pages (if used within an HTML environment). Here the unit could be used to identify an application specific type for example. 6.10 Navigation Request: Path This request extends the previous operation (OrmGet or OrmSet) to a new subtree and follows these tags in its syntax. It may appear everywhere, where a OrmGet or OrmSet tag may appear, except that it must be preceded by one of these items in the same protocol unit It usually is only found in sequences of ORM statements resulting from a "Dump" request! Syntax: QrraPati-: <pathname> Semantics: Extends the previous OrmGet or a OrmSet request into another subtree within the same object 6.11 Summary of ORM Error Codes: NoPerrnission: 1 The current authentication can not be used to perform the requested operation NoSuchNode: 2 The pathname specified in a Orm[Get/Set Path] request does not point to a known node. NoSuchAttribute: 3 The attribute specified in a OrmSet request could not be found NoSuchObject: 4 The Object specified could not be found. InvalidOperation: 5 The operation requested is not valid for this type of entity. (Example: attribute is not writable, request components of an attribute) ProtocolFailure: 6 A sequence of tags was encountered, which could not be parsed and decoded. VersionMissmatch: 7 The object could not deal with the version of the request packet. CommunicationError: 8 This is a client side error to map lower level communication errors too, if necessary. ValueOutOfRange: 9 The value passed in with a set request for an attribute is not within the allowed range and could not be accepted. Valuelnconsistent 10 The combination of values passed with a set request is not acceptable. NoSpace: 12 The request could not be completed because of internal space restrictions in the object. BufferTooSmall: 13 The response to the request exceeds the size of the response buffer provided by the underlying protocol. IntemalErroπ 14 ApplicationError: 15 These two errors are used to report back implementation problems like corrupt data structures, where the IntemalError usually is generated by the ORM support library, the ApplicationError instead is issued b the higher "application" layers. 3.1 ORM Protocol Layer And Upcall Interfaces This section was generated from <>tdιn> by CDOC on Sun Jan 29 1700 50 1995 ORM Application Context Application Sen er Capsules mav ^ r different kind of requests and therefor may have multiple d mains of ob|ects to be managed listening on multiple ports Following the ORM model, this av result in multiple parallel independant trees The ORM parser supports this by maintaining an application context, which has to be passed to the protocol layer to handle a request (there is also an opaque call-context, which may be passed to the protocol layer, but this isn't interpreted by the ssl) The application context contains beside (an opaque pointer) to the (virtual) root of the virtual tree, ainlv a list of tree/application specific function pointers. Before the first request can be passed on to the ORM protocol layer, this context has to be established with the ORM SSL \ ιa a call to ORM_Contextlnιtιalιze Accordingly there exist- * a function to inform ORM that this application context is not needed anymore (release) The following lists the function prototvpe definitions for actual functions to be provided, when establishing a context Note Some functions are defined to return pointers to character stπngs (ORM_Stπng) If the ORM protocol handler is used it is guaranteed, that the same function will not be called, before the string is copied or otherwise not needed anymore This allows the use of a single ate string buffers per function, if necessary 3.1.1 Authentication The following list of functions are included to enable an application to maintain its own authenticated context The ORM protocol just allows to forward some authentication related information from the client to the server (WHO...). This is passed on to the application layer as is, if encountered by the parser The actual meaning of this data is application and user interface dependant 3.1.2 Function Type ORM_AuthenticateFunc Performs any necessary authentication or preparation of authentication structures Usually, the authentication information is used to setup some context in the call-context, which is passed to the node/handle layer upcalls It is up to the application layer to free/clear such context after return from the protocol layer Declaration: tyccdef ~° _5-a:..s ( Jther. i ateFuπc) ( CRM AppCa.l πr.teκ Oef callccnteκc, / • in*/ C .M Srπ::j ?u: Jtrι.*ιq /* in • Fields calkont xi An opaque pointer to any kind of context, the caller has estab- lished.This passed to the node and handle layer. authstnng The string, the client passed in his request, if any. Usually uid.passwd status ORM_E\ ! oError if successfull, ORM_EPermissionDenied, if authentication unknown. 3.1.3 ORM.AuthFuncDef This structure is used to pass the Authentication function to ORM_ContextInιtialιze Declaration typeief r.r.:: ZR. _ft-jc f-.r.cTcg | ? _ A j • . " .•» ' • • _ i at.eTur.c a Jth: ' :.-: • ι.: k r .r.: ef; 3.1.4 Virtual Node & Tree Function Types The follow mg list ol functions (function types) are used to access the virtual tree of components, attributes and linked objects. They usually don't deal with application specific data. 3.1.5 Function Type ORM_NodeLookUpFunc This is the central function for the traversal of the tree . Returns an opaque pointer to a virtual node, which may subsequently be called to retrieve propertie* or children of specific types. Declaration v/pedet :?>ι Str.-u (*CRM Mode-.o kUpFunc ) ( ;ailcon:ext, ' in •/ C * HX_AppN<deOef root, * in « CRM_SLrιng patr.r.ame, /* in * / . ■ >>! -.r . αeDe. 'node, • out •/ ) Fields callcontext is an opaque pointer to the application specific call context provided with the Do_ equest function. root Opaque Pointer to root of virtual tree. This may be NULL, and is taken from the application context. pathname is a / separated list of component names optionally preceded by the name of the object (e.g. if the first component matches the roots object name, strip it, else take the first component to be a child under the applications root ) . Support for un*x style directory navi ¬ gation . and .. is highly recommended/required. A pathname of .. applied to the root with request type Object should return the root name and the actual servers link address (NOR) node The opaque node pointer, if found n ypc The ORM_.\odeType of the node found return ORM_E\!oError in case of success, or any other ORM error in case ot failure 3.1.6 Function Type O M_NodeChildNextFunc Used to subsequently scan the children of a single parent. Returns the next child of type type of parent parent. Which logically follows the child returned by the previous call to NodeCluldNextO. now passed in as lastchild. E.g. If lastchild is set to NULL the logically first child of this parent is requested. If there are no children (of the requested type), then NULL must be returned with OR.M.Status set to ORM_NoError. Declaration: ty e-aef c; _3ta- .; < ■ OR _N-'ieCriilcLNextFunc ) ( OPM_AρpCΛi. .-:.τ-.extDeπ r llccn ext, /' in OSM Ac N -leO€f rareric, / * in CRM_Kr.pHcdeDet las-child, /* in • OP>t_Nc2eTy ei . type, • in */ :PM_AppN)ieCer •child, • • ' out. •/ V RM jtr: - i "is rr. ' * * ' Fields: callcontext is an opaque pointer to the application specific call context provided with the Do_Request function. parent Opaque pointer to the virtual parent node. lastchild Opaque pointer to the last child returned by a call to this function (in this request), or NULL to request the first child. type node Pointer where to store the reference to the node found name Pointer to name of node found returns status value Possible status values, see below 1 3.1.7 Function Type ORM.NodeChildByNameFunc The little sister of ORV1_\odeLookUp Looks for a child with name childname directly under the given parent parent This function is pπmaπly used within the processing of Set- Attribute requests If there is no child with this name, return NULL and an error sta ¬ tus (see below) Declaration cypedef C _Sca. -is ι ) ( P-_A-:ρCΛli;ir.;*:'r.ref cillccπteκt, / * in * / OrM_Λcp:.O e!>of parent, /* in */ ;->' i :. * 2 hil ame, /* ι-ι */ -- • ■»_ • i.s-:-.re' ' hiLd, '* out *' _'...e: :÷ τf ■ chii.d_t.vpe /* o.t • • Field.- parent Opaque pointer to the virtual parent node. childname N me of the child (attribute), i e every printable char except 7 child Pointer where to store the reference to the node found child Jufv Pointer to type of node found. ret rn OR\!_£\oError if child was found, else ORM_ENoSuchNode 3.1. S Function Type ORM_NodeTypeGetFunc returns the type (enum ORM_.\'odeTypeDef) of the given node. Declaration- typede f C F ^ M_N - -r_Tv «jθ.-> f ( O : U / _ ode Type Get Fur. c ) ( CR. _AccNr -.*_>ei i ϋ * 1." * / I Fields node a pointer to a virtual node returns a v alid type or ORM_NodeTypeUnknown. 3.1.9 Function Type ORM.NodeNameGetFunc returns the name (ORM_Stπng) of the given node. Declaration: - y e-ic f C r : :: ( * p _ -eS'ameGet Func > ( ΛM A.ccNccleCe f -. _: oe / • in * ) ; Fields node a pointer to a virtual node returns a valid null terminated string of characters or NULL 3.1.10 Function Type ORM_NodeNotFoundTrapFunc This function is kind of special by providing the application layer a chance, if the lookup of a node failed, to create that node Normally, referencing a non-existent node in the pathname of an ORM request is treated as an error, evcept this is an internal ORM restore request. Reloading an ORM tree into an application may encounter subtrees, which where dynamically created by the application during a previous run (usually via a New subtree). This function is totally application dependant and is not covered by the ORM-SSL other than via this hook. Declaration: - - y.,!c-. * *S-'e r N cj-eN iFcur.dT ra r ur.c ) • .. • nύt '. . KM .- ::r.tl ; Fields: parent Reference to parent node name Name of node not found under this parent. rfiimsf Kind of ORM request (get/set/dump/restore) causing this lookup lailure newtiode Where to store the reference to the new node, if one was created. return* ORM_ENoError, if a node with the given name was created else ORM_ENoSuchNode. 3.1.11 Structure ORM_NodeFuncDef This structure bundles the virtual tree related functions for passing to Contextlnitialize Note: The ORM_.\odeNotFoundTrapFunc is not included in this function array, because it is application special anyway and must be passed explicitly, see ContextlnitialiseO Declaration: typeder' st ruct 0RK_Mo<ieF jncTag 1 CRM_ ?.e co.'.UpFunc lookup; CPM_Nc.;e r.iilNe.s : childnext; " J'i ύe?;". - -dByNd-r-T:: childryr.a.T.e; :* _:: -eTyp-eC-itF-r.- typese ; l >- \ ' -^:« ^ : ::' : r,a.τιege- : 3.1.12 Application Handles The following two function types are used to link the virtual nodes in the tree to (parts of) actual application data instances, visible to the ORM support layer as opaque handles. When an application handle is requested from the application layer, real things happen to start and it is assumed, that the instances are valid and available, until explicitly released " by the ORM layer The handles together with the aspect (identifying the type of handle to the application) will be passed to the application specific functions, when actual values have to be accessed (either ( or g t or set). If these functions are not set in the ORM context, NL'LL will bv passed uuo those calls for both, the handle and the handleclass. 3.1.13 Function Type ORM_HandleGetFunc Request (and lock) an actual handle (pointer to an application level instance) and a handleclass based on the current virtual node and the current principal. Declaration: :? «■? : TypeDe ! ' in ■ / 0K. A=cK ar.T.l -ef • handle, / * out • / IRy. A. cAscfl::'. ;* : ' •aspect / * oat * / Fields: is an opaque pointer to the application specific call context pro- ided with the Do_Request function. node Pointer to current Node. op Operation Code, e.g. ORM_Request handle Pointer, where to store the handle reference aspect Pointer, where to store the aspect reference returns ORM_ENoError if no error occured or any of the ORM error codes. 3.1.14 Function Type ORM.HandleReleaseFunc Returns a given handle back to the application layer. This should be more understood as an unlock operation than a free! Declaration: r-ypecief oiJ ( •0?-y_:- , .andl P.c-.easeFunc ) ( CP l_A?pCoilC niexcDef cailccncexc, /* in • / CPM_A?ρ ar.αie-e£ handle, /* in « / CR.V A A3p* ; ef aspect, * in * ) : Fields Ctlll Or.'ll'M is an opaque pointer to the application specific call context provided with the Do_Request function. handle a handle obtained via a call to HandleGet aspect Aspect as returned from HandleGet op Operation Code, e.g. ORM_Request 3.1.15 Function Type ORM_ObjectLinkGetFunc Retrieve the Ol wt Link from a node of type Object given the node, the handle and the aspect The standard Handle Layer functions just return the link stored in the corresponding field in the node struct. Declaration: type ef CR.!_iti^ j3 < *or<M_Har.dleOb ecr_ .r.iGe-Func ) ( "R. __».:: N j l*ref r.-ie, CRM_Ac :'.3nGl«i:~eϊ τ;ar.._Ue, in * ' cur. • / Fields: node Reference to node of Object Type handle Reference to application defined handle as returned from HandleGet aspect Reference to application defined aspect as returned from Han- link Location where to store the reference to the stringified link information returns ORM_E\'oError if successfull, else ORM nvahdOperation, if the node is not ot type Object 3.1.16 Function Type ORM.AttributeDescrGetFunc Retrieve the opaque reference unique to a node of type Attribute (usually the attribute descriptor), given the node, the handle and the aspect. The standard Handle Layer functions just return the pointer stored in the corresponding field in the node struct. Declaration- r. v:;e..-τ . ~. ' ; • } . . - . ' ' - ' ■ ' -* - - '. -At t ri huceDesc r'Η .Func ) ( n ' a spect , i n ' ■ at: r bdesc 0 -r_ Fields πϋiif Reference to node of Object Type handle Reference to application defined handle as returned from HandleGet aspect Reference to application defined aspect as returned from HandleGet attnbdesc Location where to store the reference to the attribute information returns ORM_EN'oError if successfull, else ORMJnvalidOperation, if the node is not of type Object 3.1.17 Structure ORM_HandleFuncDef This structure bundles the handle related functions for passing to Contextlnitialize Declaration :PM_- J ar.l 5er.F:r. get ; CR _.-«ιr.ulιfPcleas«?F>.r.c re .ease; cr v ._ J -.nd e3tι;ect lin*.; CR><_-..r ..eΛtt - b.:teDe* rG€r.F-jnc attrit; 3.1.18 Accessing Application Data: Aspects the following group of functions (function types) has to be provided to access actual val ¬ ues of the application either for retrieval or for updating. All functions in this group are mandatory, if the ORM protocol layer is used. 3.1.19 Function Type ORM.AspectCallGetFunc This function retπeves an aspect from the application layer, e.g. a reference to a blob of native application data (a pointer to a (part of) an application data structure, or a response buffer ) The ORM protocol layer calls this function once for every unique handle/aspect combination (and not per Attribute) within a single AttπbuteGet Request _ If the HandleGet Function returns a different pair or there are no more attribute nodes to process, the current aspect is released 1 Declaration . e'Se . H.« i". -3 <• jr." ice " CailGer. Func ) ( OP._ s Λ.-ι ^ -t. «i£ -ar.rile, /• in */ ;-H>< cspect, /* in */ ry _'• ι.τ. =t -- : v-. 'rurren- /* oαt */ ) Fields handle Handle as retrieved from HandleGet aspect Aspect Reference, as retrieved from HandleGet current Where to store the reference to the current value (opaque) 3.1.20 Function Type ORM.AspectCalllnitFunc This function requests an asfvel container from the application layer, e.g. a reference to a blob, where new attribute values can be selectivly written to to perform AttributeSet requests In addition hte application layer may return a reference to the current aspects values (cnip CallCet), which is passed unchanged to the CallSet routine. The ORM protocol layer calls this function once for every unique handle/aspect combination (and not per Attribute) within a single AttributeSet Request. If the HandleGet Function returns a different pair for a node or there are no more attribute nodes to process, the CallSet function is called (Note AsptctRelease is only called for aspects retrieved via CallGet!) The ORM SSL Implementation of these functions copies the current values and returns a reference to this copy in new and a reference to the current values in current. Declaration tv::ei-- -.1 - ; - > -. a \" " - :' _Λ-iccc Ca 11. ' n tFJΓ.C ) < _?- v _ r c - i - i.' eZ i -ale, /* ir. • / „-.'_ .. ■ ,..,. .- ■ ;- - j - .. ι, - " :- •/ :-. • ' - -cCit art z 1 - i ' ew, /* out */ 1"'* ^ . . ' . Λ '. ϊ?t -,cf - -rront /* cut */ ) Fields handle Handle as retrieved from HandleGet rtn/vi Aspect Reference, as retrieved from HandleGet new Where to store the reference to the native blob to update with new attribute values (opaque) current Where to store the reference to the current aspect (opaque) 3.1.21 Function Type ORM_AspectCallSetFunc This function is called to actually apply the new attribute values for the current aspect by the application layer It is up to the aspect/application layer, to check the values in the request structure for validity and consistency and to determine which attπbutes got new values (by comparison with the curr nt values). In addition it is the responsibility of the aspect/application layer to deallocate any structures allocated by AspectCalllntt. Only if the Set-Function is not called, the call to AspectRelease is performed. The ORM protocol layer calls Set-function once for every unique handle/aspect combination (and not per Attribute) within a single AttributeSet Request. If the HandleGet Function returns a different pair for a node or there are no more attribute nodes to process, the CallSet function is called (Note: AspectRelease is only called for aspects retrieved via CallCet!) The ORM SSL Implementation of these functions copies the current values and returns a reference to this copy in new and a reference to the current values in current. aspect Aspect Reference, as retrieved from HandleGet request Where to store the reference to the native blob to update with new attribute values (opaque) current Where to store the reference to the current aspect (opaque) rsdetail Where to store a textual hint, why the call failed, if any. returns ORVI_E\oError if new values could be applied successfully, else ORM_ERange 3.1.22 Function Type ORM.AspectReleaseFunc Lsed to tell the application layer, that the reference retπeved via an AspectCet or Aspec- tlnit call is no longer needed anymore by the ORM layer. This function is called, when GetHandle returns a new handle aspect call within a AttnbuteGet processing or a conversion in an AttributeSet processing failed Declaration .. r'e ieaseFur.c ) ( ■ r r , - n * ■ :tv e I T; ■ / ) ; Fields: handle Handle as retrieved from HandleGet .ispect Aspect et rence, as retπeved from HandleGet current Reference to data as returned from AspectCalllnit or Aspect- C llCct reqlype ORM_RequestGet or ORM_RequestSet depending whether this dataptr resulted from an AspectGet or Aspectlntt call. 3.1.23 ORM_AspectFuncDef This function groups the function pomters of the aspect layer Declaration cyr-odcf ;τ..c". HX_As;>cct Fur.cTag 1 :PM_A.pe tC.::.e:F r: tillget; ~rV-!_As[;e : i :.-.: , .r"-:.. rail .nit . ORM_Asρ ct aliSetF!.-.r allset; CRM_Λ * nee t Re i a se F ". - -el ease ; 1 cr-. w - 1 l ic: Fϋπ -'if . * 3.1.24 Attribute Functions The following group of functions is called to actually perform the the single attribute Get/Set and the corresponding conversions between the applications native and the ORM (ascn) presentation. 3.1.25 Data Structure: O _AttributelnfoDef This structure is used to return the all the meta information and the actual value of an attribute It is passed by reference to the application/attπbute layer to be filled. Note: The string pointers do not point to valid buffers, when passed to the attribute layer! <- τ ' .'. r . _' • - , STRING, Hzxocτ, :.::ir: • . alj-; .n its ascii presentation '. • — cit. • : :. ■ : ~: u r 'ic- string '...-... Jet .-.r.d_. : 7.÷ -.-.it stung Declaration: :v <ϊi-: « • • ..:- . ' Λ>C_«" " ". i -::-:teIritoTag i . • ■■ : ; .. - - . -.. -e ; ' .Fv.-' . . ■ . jr.: - "• ''_ - - : range; -:*. . t.1-3 JΓ.I:; • ":-:■'_'-.: ■ r .:,uteIn.oS-rf; 3.1.26 Function Type ORM_AttributeNativeToStringFunc This function converts the applications native value of an attπbute, specified by handle, aspect and the attribute descriptor to a C-stπng (ORM_String). Declaration: typedef CRM_S.a- s ( *CRM_At - rif-teNativeTcS rinqrunc) < ;K- AcpHcndlerj ' handle, '* m */ :PM_AppAspect:e. aspect, .' * m */ ~PM AppΛr. r.r icZcscrTo attn'odescr, / « in */ dataptr, /* in */ - i r::.q * strval-e /* out */ 1 ; Fields: handle Handle as obtained from the last call to HandleGet or NULL. aspect Aspect as returned from the last call to HandleGet or NULL Attribute Descriptor as returned form AttribDescrCet call. dataptr Opaque Pointer as returned from AspectGetCall. strvalue Where to store the reference to the converted value. returns ORM_ENoError (Null) if conversion was successfull, else a valid ORM Error return code. 3.1.27 Function Type ORM_AttributeNativeToInfo This function performs the same as the previous function ORM_AttnbuteNatιveToStrιng, except that it also provides the additional meta information to this attribute, as far as available. Declaration: .e e. CP.M_3r.a-.i3 ( *C ^ M_At*. nbi C * RM _AppHanuIe2ef r : .!_A p s pe t .; c t :?M ArpA-τ r. -^Ecr e t\Z < . direct out Fields: handle Handle as obtained from the last call to HandleGet or NULL. aspect Aspect as returned from the last call to HandleGet or NULL attrιbde > cr Mlrύmle Descriptor as returned form AttribDescrCet call. diitapti Opaque Pointer as returned from AspectGetCall. ext re] Pointer to structure, where to store the string references. returns ORM_E.\oError (Null) if conversion was successfull, else a valid ORM Error return code. 3.1.28 Function Type ORM_AttributeStringToNativeFunc This function converts an ORM_S ng value for an attπbute into the applications native presentation. The conversion should be done into the structure (dataptr) obtained by a call to AspectCalllnit Declaration ypc-def - '- , _j rt : J« > ' ^ 1 : ributeStringT Na iveFuriC) ( ; -. c-ir.zz.-. ■?.- r-.3r.dle, * in * ;-:* aspect, /* in */ tz iZ-άz atcritdesci , <'* 1.-1 */ - >.: dataptr, * n, ir.di: e t cut strvj.ue '• in • / Fields handle Handle as obtained from the last call to HandleGet or NULL. aspect Aspect as returned from the last call to HandleGet or NULL Attribute Descriptor as returned form AttribDescrCet call. dataptr Opaque Pointer as returned from AspectGetCall. st rvalue New value as a C-Stπng (ascn) returns ORM_E.\ ' oError (Null) if conversion was successfull, else a valid ORM Error return code. 3.1.29 Structure ORM_AttributeFuncDef This structure bundles the attribute related functions for passing to Contextlnitialize Declaration. typedet' sti'.ct :?.V_Attπc_teruncTag l CFvM_λr tris.reϊ: r intjr j it iveFunc s ππgto.ative; CP._Aεtrιr_ t£Na ιveTcStrιngFunc nativetostring; ~rM_Λtt r: •' ■ -za-idz I .-zTz, ".f >Fur c nf ctsstπng; ■ lry._-.zz i -..'. -t<=F jn::÷f • 3.1.30 Structure ORM_ContextDef This is an internal structure to ORM and opaque to the application layer. It stores the function pointers and the information of the root node. Note. This structure and the related procedure definitions may change authfuncs Pointer to list of authentication related functions or NULL, if no application specific authentication is needed. notfound \'o description 3.1.32 ORM.ContextRelease Release an Application Contevt Prototype. J . Z. S CR Ccr.teκt÷-.elea.'e ( CPM Ccr.text ef contκt ) Parameters: contxt Pointer to application context as obtained from ORM_ContextInitialize 3.1.33 OR.M.DoRequest This function calls the protocol layer to parse an ORM request received and act on it accordingly via upcalls to functions in the application context, i.e. this is the function to be dispatched, when ORM requests are received on a server port. Prototype: ? . i t .. * - ; = :i n o l J ORM_Conteχtlnιtialize. illl t M An arbitrary call context (reference) maintained by the application layer and passed to the authentication, node and handle upcalls. request Pointer to received ORM request reqlen Length of request buffer in bytes response Pointer to allocated response buffer maxresp Reference to maximum response buffer length in bytes, on return points to number of bytes used in response buffer 3.2 ORM Node Layer This section was generated from <stdin> by ' CDOC on Fri Jan 27 19:59:34 1995. The ORM Node layer adds another level of ORM application/server support, as it actu ¬ ally maintains a tree structure to access the application level datastructures. This e! is accessed from the application/server level via the ORM_Node... functions to actually build /destroy the tree of objects, components and attributes. On the other side it is called from the protocol level and frees up the application to provide the appropriate functions for navigation and name space/entity management itself. 3.2.1 Application Handles The nodes of the node layer provide a tree structured view to application/server level data but the\ vusu lh ) do not contain the actual data. A link to the actual instances of application lev ei data is maintained by handles and aspects. Both are opaque to the ORM- Node level but are interpreted at the layer on top of ORM-Node. Typically the handle is a~ pointer to some application level instance, and the aspect is a pointer, index or type identifier, which identifies the type of the instance 3.2.2 The ORM.Node Structure Instances of this structure maintain the tree of virtual components, objects and attributes Every node h s a name and a type, identifying the three different entity types: Object, Component i Attribute Object and Attπbute nodes are leaf nodes, e.g. they can't have children In addition, every node has a parent and a next pointer, to link the actual tree structure. Only component nodes have a pointer to the list of children. Object Nodes have an additional attribute, called the Link (or Link-Info which usually is a stringified NOR). Attπbute Nodes reference a single attribute by, which is characterize by additional information like • a value type, w hich describes the kind of value e.g. integer (different sizes), real (sizes!), string, single-selection or multiple choice • a value mode, specifying this attribute as read-only read-wnte, write-only or persist- ant. • hints section, which contains additional information for use by the user-interface creator, e.g. valid ranges for this value and a unit string. Both values are optional. The nodes prov ide a tree structured view to application/ server level data, but they (usually ) do not contain the actual data. 3.2.3 Struct NodeDef Declaration -yrxs ej; ->" V_'JccleT«ι.j , cr-.ar « na.τ.e; struct OKK_ o eTag 'carent; stt. t CrW_M2 eT rt 'r.ext; O _A hin--!!e e handle; Cr^Ac Ai e .-ef aspect; .-- - ., .-'• ■ 'I. erj) 'firs .- • -...t :.% v _:. -. - Tia '.ast. . !• r • . • - • .-1 ' :s;:, I a-. rib; 'tr ct ! :!-i: ' * .r.<; i -t-e-:τ. Fields ryrv indentities the type of entity, this node describes, i.e. ORM_ι\'odeType[Object, Component Attribute, Unknown] flag Internal use name The name of the node (object, component or attribute name parent pointer to the parent in the tree, NUL for the root of the tree. next pointer to next sibblmg in chain. This defines the order in which nodes of a given type appear in the response handle an opaque pointer for use by the upper layers aspect another opaque identifier for use by the upper layers u.comp union variant for component nodes u ca p fιr>t pointer to first child of this component node n ht pointer to last child of this component node w altnb union variant for attπbute nodes u attrib a r opaque pointer for use by upper layers u.object.inik pointer to stnngified link-address of this object (NOR), e.g. the hyperlink 3.2.4 ORM.NodeCreate Creates a new unlinked node. Usually only used by convenience functions and to create the root node. Prototype: C?. v . :::.:et C?. v ι_ l ι-ιeC r.- : ( ;r-!_Sr rt.-.q name, * in */ ;p>!_Nos^Ty eCef type /* in • / Parameters: name The name of this node (for navigation) type The type of this node. This type also determines which functions - can be applied to this node later on. 3.2.5 ORM.NodeDelete Deletes the given node and all its children e.g. returns the space allocated Note: if the nodes parent pointer is not NULL, the node will not be deleted. Prototype: :J-^?: ϋ.ϊ-.-i l .?. ■ *. ;e.e: -.i-e Parameters node The node (and the subtree) to delete 3.2.6 ORM_NodeAttach Attaches a node (and its subtree) into an existing tree as a new subtree. Every node (subtree) is in at most 1 tree! Prototype- CPM _NTT.eA t.--T; i t ' M e-ii ior.Der relation, /* in */ :p>!_NcrieDef relative, /* in • / ;:oi MccieDet subtree /* in */ Parameters: relation Rag either ORM.NodeStbbling or ORM_NodeChild, specifying the role of the relative node, e.g. its a sibbling or its the parent of the subtree to attach. If its a parent, the new node will be attached at the end of all children, if its a sibbling, it will be placed right before this child. relative an existing node, either parent of sibbling subtree description 3.2.7 ORM.NodeDetach Detaches a subtree from the current root tree. This <- .vays has to be called, before a subtree is actually deallocated The subtree may also be reattached in the same tree again after this call Prototvpe ,-.- • M • • r .-><__ N- -.. ti- .J ir z -ee '" n ■ No parameter descriptions are available 3.2.8 ORM.NodeHandleSet Sets the handle in the given node (see also OR _Node<convenιence functions:-) Prototype CrM N:- ---.-- i I "RM .cαeDer ncαe, / ■ in */ nandle '* n « / ) . Parameters node Reference to node structure of any type. handl Reference to opaque handle 3.2.9 ORM.NodeHandleGet Retπeves the handle from a given node Prototype int ; .'' , _Sc-.r--.-ιr Uf " i\; ( OXH _'<1 s seCef loαe, / * in « /' PM Ai- HcnaleDet 'handle '* out *' No parameter descriptions are available. 3.2.10 ORM.NodeAspectSet Sets the aspect in the giv en node (see also ORM_Node<convenience functions>) Prototype c.d OPΛ_NcdeAspectSet ( ORM_ cceDef node, /* in * / CRM_λppAspectDef aspect /* in •/ ) ; Parameters: node Reference to node structure of any valid node type. (j. / i / Reference t opaque aspect description. 3.2.11 ORM.NodeAspectGet Retrieves the aspect from a given node Prototype: - r. Z "sy - . - ; - - , - ; - c " e . * f r.-dC ι / * n * : :-- v _.-.^-.A =cectDe f ' aspect / • out * No parameter descriptions are available. 3.2.12 ORM.NodeAttributeDescrSet Sets the attribute description of an attribute node Prototype: Parameters: node Reference to node structure of type Attribute. attrib Reference to opaque attribute description 3.2.13 ORM.NodeAttributeDescrGet Cets the attribute description of an attribute node Prototype: int ( ORM_NodeDef node, /■ in «/ :? _ΛppAttribDescr-ief "attrib /• out •/ I ; No parameter descriptions are available. 3.2.14 ORM_NodeObjectLinkSet Sets the link of an object node Prototype: :'r. v '_'i- ' Tf.-C^-».-f.!.'.:.<ie: ( A.M_M^τιeDef ??.e, '* in • ' : >!_5trιr.g lιr.< / ■ in * Parameters: f/ι)./ι' Reference to node structure of type Object. link Stringified version of the address/nor to call this object. 3.2.15 ORM_NodeObjectLinkGet Gets the linkaddress of an object node Prototyp 1 - 1 " • *_ ■> •: ■ ■ .. ■■ : ■ . - " ' . > •" --• ■ •. :?-"_N:rieD-5 I n = de, /• in * ,' . " A . iz:~r.g ' zr. > • cut * ' I : No parameter descriptions are available. 3.2.16 ORM_NodeObjectAdd for an explanations of paramters, see above. Return created node if operation succeeded else NULL. Prototype: 'iRM_Hoce r i. » f C R.M_P.e 1 a 11 or.De f CRM~N deDef ;FM_String -RM VppKandleΞef CRM^AppAa ec Def C String ) ; No parameter descriptions are available 3.2.17 ORMJModeComponentAdd Prototype relation, /* in ■ / C- v M_:ic eCcnp r.crtAdd ( CRM_P.eIatιonDef C!>t_Nτ>τleDef relative, /* in •/ ;pM_3 rιr.g name, /* in */ -•■ •• ' l_AppKan le->ef handle, /* in • /- c 3>!_AppA3pectθe f aspect /• in */ No parameter descriptions are available. 3.2.18 ORM_NodeAttributeAdd Prototype: CPM_M :ieS*jt f re * a ιcr., .'- v i At-.π c>_z ^ ? .τϋ K."! - laticr.-ie :?.M_". j« e£ :c...:ve, ir . » *._; t ri g me, ";p:-_AppKanjle-ef handle, ."RM AppAioectOef aspect. CRM_AppAttε b3esccDef attribdescr ) ; No parameter descriptions are available. 3.3 ORM Aspect Layer This section was- enerated from <stdin> by DOC on Sun Jan 2917:00:511995. The ORM aspect layer adds another level of ORM application/server support on top of theORVI Node/ Handle layer, and supports the retrieval and modification of aspects, i.e. groups of attπbutesfrom or into application data structures, once those have been regis ¬ tered with this layer This level has no additional (downoll) functions but defines data structures to be pro ¬ vided by the application layer. These are then accessed/used by the aspect upcall func ¬ tions, if those have been registered with the ORM protocol layer. The Aspect layer implementation of the ORM-SSL works as follows: On AspectCallCet requests, just a pointer is returned which points at offset bytes (as set in the aspect descriptor ) from the beginning of the handle. On AspectCalllnit calls, a copy of the aspect, e g size bytes from the area pointed to by handle, starting from offset, is taken into a private memory area. This copy is then passed to the Attribute conversion routines to write the new values into. On AspectCallSet calls, the application level set function as denoted by the aspect descriptor is called and the pπvate copy (request structure) is released afterward. 3.3.1 Function Type ORM_AspectSetFunc This function is called from the aspect layer to actually apply the new attribute values to the application layer and/or inmate the requested state changes. This function usually should not block, e should not wait until the initiated state change is completed. Any kind of intermediate state should instead be visible to a client on request (i.e. not STOPPED -> STARTED, but STOPPED -> STARTINC -> STARTED, if starting implies a heavier operation. Declaration: CR.M_Stat.-3 typedϊf ; ' aM_As::« :S- ranc) ( CR A pi-an- 'r f r.andle, • ι.-ι */ . __A-'i..-!.-.:.ι , jτi.i!ι:uef aspe t, * in ■ : •> : • : A.cpCϊ- 1?: z2<=i request, /* in */ ' ."-"'•< •'-.;. ;:;:,nr i- L:..C: -urrent, " in •/ Cι~: « i_i i-.-.a *errorteκt * out */ ) . Fields: liandle the handle as returned from HandleGet aspct Reference to the aspectdescr. r ui t Copy of the aspect as described by the aspectdescr updated with new values. current Reference to aspect within handle errortext Where to store a pointer to a short textual description if the requested values could NOT be applied. returns ORM_E.\'oError if all new values could be applied, or ORM_EParameterϋst if paremter set is inconsistent or ORM.EMissingAttribute if a mandatory attribute is MULL. 3.3.2 The ORM.AspectDescrDef This descriptor maintains information about the application data structure (usually refer ¬ ences by the ORM.AppHandle) or parts of it. It describes the binary size, the offset within the handle, and contains pointers to functions to actually retrieve or modify this aspect of the application instance. Not : It is currently open, whether there should be a procedural interface to set up the aspect descriptor instead of providing a structure type definition to be passed initialized by the application code Declaration Fields: name Pointer to name string, for identification mainly. ffset The offset in bytes within the instance, where this aspect starts. This usually is the offset of a sub structure in the instance. size The size in bytes of the instance, the application handle pointer points to. For set-requests, the container for the new value is created by copying the handle, and inserting the new values in it. fl"X If set to ORM_AspectGetIndirect. the offset indicates the offset to a pointer, pointing to another structure of the above size. setj Pointer to function, which is called to apply (a set of) new values to an application instance. appext any value of pointer size the application wants to store with the aspect. This may be used to store a create_aspect function pointer. apptd Opaque identifier, which may be used by the applications layer 3.4 ORM Attribute Layer This section was generated from <stdιn> by CDOC on Fri Jan 2719:59:341995. The OR.M Attπbute layer adds another level of ORM application/ server support on top of the ORM node layer, by providing (list ofl attπbute descriptors, which simply initial ¬ ized by the application code, allowe automatic conversion and generation of the attribute meta information, requested by the ORM protocol layer. The implementation of the attπbute layer in the ORM SSL assumes, that it is converting to and from a binary blob of data, identified by the (lower level) aspect descriptor. The goal of this layer is to reduce the coding effort needed by the application writer at this layer, just to provide some initialized descriptors and pass them to the ORM SSL via single calls per every instance created. 3.4.1 The ORM_AttributeDescriptorDef Thι data structure es ribe a si gle attribute, e g. its native type and mode, its size, pointers to cum rniu functions In addition it maintains hooks for preset meta-info like - Unit and Ringe Declaration: zγps-ei struct -r , .M_ At ncυteDescrTag ( 0RM_5tcιr.q name; :? s - A tricTyreP f datatype; 'PM_A'. : α 'Λ :leC«i a-rcessmode; ' . "'' • * S-. r: - 7 range; " ->' • . -nit; • 7-i - offset; . « ... ■ .-. • .•j: , . ::v-:'.;.:ιιa'jr i .nc nativeto.it r ng; ;r.'.er-.κ:-3 ri.r.gT jrJ-ϊ iveFunc st nngtona e; PM_AcpCcr.vert rArgiet ccnvarg; I 0RM_A-.tributeDe5ccDef ; Fields: name The name of the attribute. datatype I e t\ pe of data of this attribute (ORM_AttributeTypeDeO. This is Λ superset of the data types, the ORM protocol defines and used to determine implicit conversion routines. mode The allowed access modes of this attribute out of ORM_AttπbMode values, e.g. read-only, write- only, read-write. range A string describing the allowed ranges for new values for read- write or write-only attributes only. This is a ORM hint, and as such optional 'i it A unit string (usually ms, Mb, etc.) which may be used by object ->pecιnc user interface generators in any way, and by default if present is placed behind the attribute value. This is also an ORM hint and as such optional. conversion function A function pointer to an application specific conversion function, to convert between native and ORM presentations. Note: This is not to be confused with the similar functions of the ORM_Context structure. For the <con version- function> to be called, the ORM_.N!ode conversions functions have to be setup in the ORM.Context. conversion-arg An opaque pointer to any argument, the conversion function may need to convert this attribute. 3.4.2 ORM_AttributeCreale This function combines several actions required to register an attribute of a (new) instance with the ORM SSL, i.e it creates an attribute node under the given parent (which must be of ORM_\odeTypeComponent) and attaches the attribute description and the handle information to it. Prototype: i n - :e" r*-:.te ( ' -\M_'< . jer.« : relative, * in * / „r>*. <e .ά zzr. ei relation, / ' in */' :?--ι_Ar. -. : ;c ute:es ;t Lι.stDe£ at rit- escr , / * in • / . ?y. Aopert trri.istDef aspectdescr, / * in * / ϊsM_Ac :iandle c: nandle, /* in " / ;?>' Ncc^Oet ' * Γ.ΪW / * out • ; i .- Parameters: relative pointer to relative node. If relation is set ORM ModelsParent, then this has to be a node of ORM_NodeTypeComponent. If relation is set to ORM_.\odelsSibbling, then this node can be of any valid node type. relatton Either ORM_NodeIsParent, if the node relative should be the parent of the new attribute node, or ORM_NodeIsSibbling, if the new attribute node should be inserted after the relative node as a sibbling. attribih'scr No description aspci tdocr No description handle Pointer to the application instance this attribute belongs to or ORM_Handlelnherit (-1), if the handle should be taken from the parent (or its parent and so on). new Pointer to new attribute node or NPJLL on failure. 3.4-3 ORM_A.tributeDes.roy This function detaches the attπbute node from the tree of nodes if any, deletes the node structure and deletes any depending structures, i.e. the attribute descriptor. In the current implementation this function maps directly to ORM_NodeDestroy, but nevertheless this function should be called for attribute nodes created with functions of this layer to be able to deallocate any dynamic memory. Prototype: int PM_At : i -; : e. : t r = y OPM ModeDe f at t rncde ) Parameters: at t mode Pointer to attrbute node. 3.4.4 ORM_AttributeListCreate This is another convenience functions to add a list of attributes to a component. The given node must be a of component type and is used as the parent for the new list of attributes ( which is appended to the end of the list of child-nodes). The pointer to the attribute descriptor now points to an array of those descriptors, where the end of the array is marked by a descπptor svhose name pointer is NULL. Prototype. pa rent , :oKar. sieC e r " . handle , . f.- 'j i : ∑ .^n cspect Tiescr , - ~y, At : : : .--•& 0c5 i -.i 2tDe f attrdeacrliat, attrccunt Parameters. parent Pointer to an existing component node, who is the parent node of ail newly created attribute nodes. handle Pointer to the application instance, all attribute belongs to or ORM_HandleInherit (-1), which indicates, that the actual handle is determined by the parent (which again may have its handle set to ORM Handlelnherit!) aspectdescr o description atlrdescrlisl Pointer to an array of ORM.AttributeDescr, with name=NULL in the last element if attrcount is < 0. attrcoiuii The number of attribute descriptors in the list or the number of initial attributes from this list to attach to this node or -1, if the end of the list (array) should be determined by a fULL nodeinfo pointer. 3.5 ORM Attribute Conversion Support This section was generated from <stdιn> by CDOC on Sun Jan 29 18:13:38 1995. This part or the ORM Server Support Layer provides functions for converting generic ORM data types between their native (binary) and the ORM (ASCII) presentation. The interface between the attribute and the conversion layer is defined by to function types, one for converting application native data into an ORM representation, one to convert ORM attribute value stπngs into the applications native presentation. Beside the conver ¬ sion functions provided by the ORM-SSL, every application may provide its own special converters as long as their interfaces conform these function types. 3.5.1 Function Type ORM.ConverterNativeToString This function is called to convert a single native value into its string representation. In addition to the value string it may generate the range and unit strings, if the pointer values passed are non-null. If the converter function returns NULL in these pointers, the lower (attribute) layer may provide default stπngs if any Memory Allocation: The memory to hold the converted string value(s) has to be provided bv the converter function. It is reasonable to use static memory for this purpose, because before the converter function is called again, the ORM protocol layer will copy the strings returned Declaration ty; . T M : -.verterNat iveToSt rir.gFur.c ) ( - ?»M_ή::p <ιr. sF r:,e f pt r , j z t size, CRM_A t r r;ut 0 tsc: r i 3tDef datatype, CPM_AppConve r erArgDef. convarg, GRM_Sr. r i.ng - strva iue, CRM_≤ πr.g ' strrange, -M_St r ir.q * 3tr nit ) ; Fields ptr Address of native data element (e.g. attπbute value) size Byte-size of data element datatype One of the ORM_AttributeTypes identifying the type of the native data element and its mapping to an ORM Protocol data type (??is this overloaded ??) convarg Any kind of argument (pointer) for this converter (as provided with the attribute descπptor for ex.) st rvalue Where to store the pointer to the converted value string. strrange Where to store the reference to the optional range string. slrunit Where to store the reference to the optional unit string. 3.5.2 Function Type ORM_ConverterStringToNative This function is called to convert a single ORM string value into its native presentation. The pointer for the result usually points into a set of different attributes, e.g. an aspect, which usually is a (partial) copy of some application data instance. Memory Allocation: The destination pointer provided references some valid memory (e.g. an aspect), but for references (the native value is a C-string for ex.), there is usually not enough space for the referenced value. This space must be allocated /provided by the converter itself. It is legal, to reference the original string as passed in to the converter function, but then the AspectCallSet function should make a copy, if the string is needed beyond this call Declaration typede . :?M_i: :s ( * OP.M Co.nve te rS nr.gTcNat veFuπc ) ( C r> « Λrrjp j -. t ct Pr r e f dest , ; i z -_ r . si ze , • a-.i :. c : r . r Tv eDe datatype, Zr ._ ,ρ r. .- rt e iArgDef ccnva rg, - 1 •* • ■ r : rq st rvalue Fields: dest Address/destination of native data element (e.g. attribute value) maxsize Maximum byte-size of data element datatype One of the ORM.AttributeTypes identifying the type of the native data element convarg Any kind of data (pointer) for this converter as provided with the attribute descriptor slrvalue The new attribute value in its ascii presentation. returns ORM_ENoError if conversion was successfull and the resulting attribute value is valid or ORM_ERangeError. 3.5.3 ORM Built In Conversion Functions The follov% mg functions are provided to convert generic C datatypes between their ORM and their native presentation. In addition sub functions are provided to support the special ORM SELECT and MCHOICE types, which are called by the generic converters. Along with these sets two new data structure (types) are introduced. 3.5.4 Function ORM.GenericNativeToString This function converts standard C-data types into their ASCII presentation. It returns only the converted value, but does not support the range and unit parts (e.g. returns NULL for those, if requested). In case of SELECT or MCHOICE functions, this function calls the related ORM_Select.. or ORM_MChoice functions. Note: It is currently open, whether the conversion argument convarg may be used to spec ¬ ify a format strin a la printf. Furthermore it is currently open, whether a NULL conver ¬ sion function in the attribute descriptor should be directed to this (default) function. Arguments as for ORM_Converter.NativeToString! Prototype: CRM j ι • .No parameter descriptions are available. 3.5.5 Function ORM.GenericStringToNative This function converts ASCII C-strings into standard C-datatypes. In case of SELECT or MCHOICE functions, this function calls the related ORM_SeIec . or ORM_MChoice functions. Note: It is currently open, whether the conversion argument convarg may be used to specify a format string a la ssc nf. Furthermore it is currently open, whether a NULL conversion function in the attribute descriptor should be directed to this (default) function. Arguments as for ORM_ConverterStringToNative! Prototype: CRM C M .7-une r icSt r i nαToNative ( No parameter descriptions are available. 3.5.6 Structure O M.StringMapDef This type of staicture is used to map strings to binary values and vice versa. It may be used to convert internal flags and states to friendly names. StringMaps must be terminated by an entry with name set to NULL. Declaration: ryr-edef :-r..ct CSX_St r ir.rjS ipTag ( . • " . = . _i • : - ." s a e : .- Fields. name Friendly name for this key. key The binary native value of the key 3.5.7 ORM.StringMapToString This function maps a value key to a stπng using the given StringMap. It returns the string of that map key is equal to the given key, else it returns the string passed in notfound Prototype: CP.M_3t.t- :-3, C py . 3ϊri"-3.MΛp:rϊ;rιr.<jι VR.M_3trιngMap2ef map, "JP.M_Key key, '.A'y. itrir.a notround) ; Parameters a Pointer to a sequence of map entries key Binary key value. notfound string to give back, if none of the keys in the map matched. 3.5.8 ORM_StringMapToKey This function maps a string value to a binary key using the given StringMap. It returns the key of that map entry, whose string is equal to the given key, else it returns the key passed in nniilidki Prototype. CR.M_ ey CRM_;rπ:qM*o:cr".y( CPM_όt r xnq.MapDef map, CR.M_ Jc ring name, - w ._ ι? invalidicey) ; Parameters. map Pointer to a sequence of map entries name No description invalidkey Nlo description 3.5.9 Structure ORM_StateMapDef This structure is used to map states into stπngs, where a state is assumed to have a distinct set of possible next states, depending on the current value. E.g. this structure can be used to deπve the set of possible new values i.e. it can provide the range value for a state attribute. Otherwise it is used similar to the simpler StringMap structure. StateMaps must be termi ¬ nated by an entry with name set to MULL. Declaration I '* r. z or -r»e U.S.A. ' ' •/ state; •1 >'._£ ' r : :ιg al icineκr.5 ; • * ;<M_ό z a t ≤MapDe f .- Fields: name Friendly name for this key. state The binary native value of this state val inex String of comma separated names of next valid states which may follow this state. 3.5.10 ORM.StateMapToString Convert an encoding of a state into a friendly name using the given statemap. If the state could not be found, the string passed in notfound is returned. Prototype. l = v_ : :. ; - ' .HM J-. i-.c:-'.c:-.j;::r,ι i '."RM_:>tareMapCef rr.aρ, CX.M_.-ir. ring r.c found) ; Parameters: map Pointer to a (name=NULL) terminated state map. state the binary state notfound string to return, if none of the entries in the map had exactly the ι $ ιven state key. 3.5.11 ORiVt.State apToKey Convert a string representation of a state into a native encoding of a state using the given statemap. If the string could not be found, the state passed in mvalidstate is returned. Prototype ?y. .'Sy CF -t_i>-. ( CR _5tareMapDef map, CRM_Stt.--.ng r.ame, CRM_Key inval dntate) ; Parameters: map Pointer to a (name=NULL) terminated state map. name No description mvalidstate o description 3.5.12 ORM_StateMapNextByKey Return the comma separated list of valid next states given the current state. Prototype: Cr . itr:-.3 CrwM__;t »: «Xa : y.: 2yKiiy t K _sr.steXaρDef map, . ' :<y. 5 r i. - ::a:el; Parameters. map Pointer to a (name=MULL) terminated state map. state the binary state 3.6 ORM Dump & Restore Support This section was generated from <stdm> by CDOC on Fri Jan 17 19:59:34 1995. This module of the ORM Server Support Library supports the dump and restore of complete subtrees, and therefore can be used to save the current configuration to a persistant storage media (i e the MSF Warehouse) and reload it from there. The actual IO functions are currently not supported by this layer or the support library at all! Dump and Restore are functions of the ORM SSL and not of the ORM protocol (i.e. there is no DUMP or RESTORE request defined in the protocol). This implies, that these functions have to be dispatched out of the application layer explicitly. One (intended) way to dispatch those functions interactively is to provide pseudo components in every subtree, which should be independent storable/ reloadable. These contain the required parameters like Warehouse location or version name as attributes An Attribute-Set request to this subtree then results in the execution of the cor ¬ responding function Under the layered view of the ORM SSL, these two functions belong to the protocol layer, as they use (nearly) the same functionality of the higher layers via upcalls. 3.6.1 General Model: Starting from a given node, which is used as the root of the relevant subtree to dump, all component:., object links and writable attributes with their meta information are recur- sivly extracted relative to the current subtree root. The extended/meta information on the persistent media can be used to interprete the stored attributes and apply changes to the stored version without the ORM server/application alive but through special clients (by an ORM /Warehouse gateway for example). The dumped ORM tree can be used to reload the whole subtree at any time, by providing the node and call the restore function of the ORM SSL (which is a special kind of Set- Request). This special kind of SOT request creates a new situation, as components (or any new subtree) may have been created dynamically by the ORM server application on request. On the next cold start ot the application, these subtrees do not exist. This results in failed lookup requests by the ORM protocol layer, which usually is treated as an error (remember: ORM-P has no direct support for object/component creation, but this is emulated by sets of writeonly attributes in separate subtrees, i.e. New..). To handle this case, the application can provide a special function during application context setup to create new instances including the ORM subtree (ORM_NodeNotFoundTrapFuncO). A parameter is passed to this creation function, which indicates, whether this situation was caused by a regular ORM protocol request or by an internally generated restore request, so the ,ι pplic.it ion code can still decide to refuse the creation. 3.6.2 ORM_Dump This function extracts the ORM entities in the subtree pointed to by subtree into the character buffer, so it can be used by a later ORM_Restore function ( or can be used as a subre- quest in a regular ORM protocol request). It is the responsibility of the caller to provide a sufficient buffer, which can hold the sub ¬ tree information of the given depth! Prototype- ι»M C Λ- .5 :-> _; :- p ( ; ε.v_AL Mc:ieD'r i sub*-, rise , 1 -r.ς eptr. , . . ' wrist , rtM 3r. r -.rta cut te r, r r.η * s:axlen ) - • Parameters i trei The root of the subtree to dump. All navigation information is saved relative to this node. depth The depth, up to which entities in this subtree should be extracted. A depth of 0 means, direct childs of the given sub-root only, i.e. if the subtree points to a component node with an attribute node as one of its direct children, the name of the attribute would be extracted, but not the value or other extended attribute information, if depth=0. A depth of -ϊ extracts the whole subtree, independent of its depth. what Is A bitmask, defining what kind of entities should be extracted: ORM_DumpSetObjects ORM_DumpSetComponents ORM_DumpSetAttributes ORM_DumpSetWritable ORM.DumpSetDefault = Objects I Components I Writable ORM.DumpSetE very Thing = Objects I Components I Attributes buffer The address of a character buffer, where to store the extracted entity information maxlen Pointer to the maximum length of this buffer. On return, maxlen will contain the number of bytes used in this buffer including the C-String Λϋ" terminator. 3.6.3 ORM_Restore Function to reload the saved ORM information into an existing subtree, where at least the root of the given subtree has to exist. Note: Because the restore request may fail with some attribute modifications already performed, an application may want to call ORM_Dump (into a temporary buffer) before actually calling ORM_Restore, to be able to undo the par ¬ tial operations. Prototype: Parameters: subtree Node of the subtree to load the management information into. buffer pointer to ORM subrequest sequence. length pointer to length of the request. On return, this will contain the number ot bytes processed from this request. 3.7 ORM SSL Generic Datatypes lifndef _ORM_TYPE_H ♦ define __[ORM~TYPE~H / « * Some generic de initions, may become obsolete « / cypeccf er.u.- ■ "a 5c, True 1 ccc1ean : lifndef NULL Idefine NULL (vo d ")0 ♦endif typedef unsigned long sιze_t; • define Z~y_rz:{ csse, zits zt (void *) ((sιze_t ) (base) ♦ (size_t ) (of fset ) ) » * ) .τ.a i 1 oc (x ) lce:.-e Z~ty_T:e-£'.-.ι ::=e(xl /" * -nore CRM spec ic scuff '/ I" * How requests and responses are passed to the ORM protocol layer "/ typedef r-.ar • ORM_Reσυes'-Def ; tyce-ie: r.a: • :RM_Sespor.seDe ; / • * The principal "ype of every ORM protocol entity, e.g. names and values, * but also ..sed most C-s tings. •/ typedef char *O _S rιng; /* * Used for S^aceMaps and 5. ring Maps as the lookup key * / type Jet .;ng ' .?._ ey; /* * The following are various opaque handles. Opaque mainly to the protocol * layer out also for the lower of two stacked layers. •/ typedef vo d "CRM_AppNodeDef ; cypedef voiα 'CRM_AppHandleDe ; typedef :i • "RM_AppAscectDef ; .ypece: . : . : • ZrlM_AppDa.aP rDef ; typedef vo:. ■ CRM_AppAttπbDe3crθef ; typedef void CRM__AρpCa.lContex Def / typedef vtid • CP.M~AppC c r.ve r t e r ArgDef ; /' * Valid Access rr.ca.es for an attribute typedef er.j.r. : ?RM_Att ιc> , .cde or.e, CRK_A: Z - 1 cMcdeP.w , ZHy._i\zz πcModeRC, ORM_A 1 r i Mode O , CRM_AtcπcModeRWP I ORM A ribModeDef . / • Known (native) datatypes, which are supported by the Generic converter : ?y._A:.:;::ypcN z r,e , /R>!_At t r icType Zr.z '. , :~y. AttπcT ce'r.-. : CRM_A t c r ic Type'.' I r. 2 , CRM_At πr;Tyce-r.t<l , 0RM_Att ibType' :r.t4 r M_A. z ricType: r.t 3 , CRX_A -. t r i cTy eV I r.t S , CRM_At t ifcTypeSea 132 , ORM_At z πbTypeRea 16 , CRM_At z r.t Type St ri g, :RM_A.-. :::Ty C e V , RM_A;tπoType3eiect, / " 1 out of many •/ ? !_At c : ? e State, / • 1 cut of many, but with dynamic range */ Z?y._Az z r PTy peOpc l cr. , /* binary switch ON/OFF YES/NO */ ORM_A πbTypeMChoice, / • n out of many */ ORM_A ioType'Jn nown I ORM_Attrib?-/peDef ; CRM Error Cedes, used as well by the protocol as by the ORM SSL :ypedef er-.-.-n • 0RM_£ £rrcr , /* Operation successfull! • / ORM_£Pe rmi ss : c r. , None or wrong auth. information */ ORM____εNo≤ chNode, /• some name in pathname could not be found */ ORM_εNoSuchAttrιbute, /' Attribute in Set-Request doesn't exist */ RM_ENcSucr-.Object, / ■ Ob ect/Manager could not be found */ ORM_EInvalidOpera ion, /• Operation not applicable to node type */ ORM_EPrococol, /• ORM protocol violation */ ORM_εcommu.-.ιcatιor., /* lower level comm error « / 0RM_ERange, / ■ new attribute value out of range */ ORM_ΞParameterLιs , / ■ set of attributes not applicable */ CRM_EM 5Sir.5A : r oute, /* mandatory attrib. missing or NULL */ ORM__εNc Sp e, / • internal allocation */ ; .M response buffer */ 0RM_ε Inte nal, * ORM Internal error -> bug */ CRM_εApρl cat on, ■' * application level error -> bug */ I CRM Status; .-pes :. -zzzes . r. t!-.e v.rt_al ree. Note, that only nodes of type :.y 'iriaT perc- :r.er.t zi~. nave cr. ldren! typedef enum ( CRM_NodeType ; nknown, CRM_NodeTypeObjβct, CRM_NcdeTy peCcnpoπent , ORM_NcdeTypeAt rιbute, RM_Moae ype Any CRM_:: eT-. peDef ; /• • T.pei c: Z?y. .cq.es'.j Ncte tr.at the Dump and Restore requests are • net cart :: ' zr-i Z~y. pr":ccl, cut only available within the ORM • server s-ppor -lorary */ typedef enum < #enαιf

Claims: WHAT IS CLAIMED IS: 1 . A system for managing objects, including a first server, comprising: a first receiver portion configured to receive a request in a hypermedia format; a first translator portion configured to convert the hypermedia request to an object request; a sender portion configured to send the object request to an object manager; a second receiver portion configured to receive a response from the object manager; and a second translator portion configured to convert the object manager response to the hypermedia format. 2. The system of claim 1 , further comprising a second server, including: a third receiver portion configured to receive a request in a hypermedia format; a third translator portion configured to convert the hypermedia request to an object request; a second sender portion configured to send the object request to an object manager; a fourth receiver portion configured to receive a response from the object manager; and a fourth translator portion configured to convert the object manager response to the hypermedia format. 3. The system of claim 1 , further comprising: a second sending portion configured to send the hypermedia format data from the sender portion to a browser to be displayed. 4. The system of claim 1 , where the object manager manages a self- describing object. 5. The system of claim 1 , where the object manager manages a non-self describing object. 6. The system of claim 5, where the object manager performs a "worm" function. 7. A method for browsing objects, where a browser communicates with a server, comprising the steps, performed by the browser, of: sending an initial URL to the server; receiving first data from the server, where the first data specifies an object corresponding to the URL; sending user-entered data associated with the object to the server; and receiving second data from the server, where the second data specifies a second object corresponding to the user-entered data. 8. The method of claim 7, wherein the step of sending an initial URL to the server comprises the step of sending an initial URL known to the browser, where the URL is the URL of the server. 9. The method of claim 7, wherein the step of sending an initial URL to the server comprises the step of sending an initial URL entered by the user, where the URL is the URL of the server. 1 0. The method of claim 7, wherein the step of sending user-entered data associated with the object to the server includes the step of indicating a "set" operation in the user- entered data. 1 1 . The method of claim 7, wherein the step of sending user-entered data associated with the object to the server includes the step of indicating a "get" operation in the user- entered data. 1 2. The method of claim 7, wherein the step of receiving second data from the server includes the step of receiving data corresponding to an attribute value of the object. 1 3. The method of claim 7, wherein the step of receiving second data from the server includes the step of receiving data corresponding to a second object linked to the first object via an object-link. 1 4. A computer program product comprising: a computer usable medium having computer readable code embodied therein for managing objects, the computer program product comprising: computer readable program code devices configured to cause a computer to effect receiving a request in a hypermedia format; computer readable program code devices configured to cause a computer to effect converting the hypermedia request to an object request; computer readable program code devices configured to cause a computer to effect sending the object request to an object manager; computer readable program code devices configured to cause a computer to effect receiving a response from the object manager; and computer readable program code devices configured to cause a computer to effect converting the object manager response to a second hypermedia format. 1 5. The computer program product of claim 14, further comprising: computer readable program code devices configured to cause a computer to effect sending the second hypermedia format data to a browser to be displayed.

Inventors: BONHAM PETER DOUGLAS, DE BORST JEROEN PETER, ERLENKOETTER ANSGAR, BONHAM, PETER, DOUGLAS, DE BORST, JEROEN, PETER, ERLENKOETTER, ANSGAR
Applicants: TANDEM COMPUTERS INC, TANDEM COMPUTERS INCORPORATED
Application year: 1997
Main classification: G06F17
IPC codes: G06F9, G06F12, G06F13, G06F17